interface/wx/datstrm.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        datstrm.h
   3 // Purpose:     interface of wxDataInputStream and wxDataOutputStream
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDataOutputStream
  11
  12     This class provides functions that write binary data types in a portable
  13     way. Data can be written in either big-endian or little-endian format,
  14     little-endian being the default on all architectures.
  15
  16     If you want to write data to text files (or streams) use wxTextOutputStream
  17     instead.
  18
  19     The "<<" operator is overloaded and you can use this class like a standard
  20     C++ iostream. See wxDataInputStream for its usage and caveats.
  21
  22     @library{wxbase}
  23     @category{streams}
  24
  25     @see wxDataInputStream
  26 */
  27 class wxDataOutputStream
  28 {
  29 public:
  30     /**
  31         Constructs a datastream object from an output stream.
  32         Only write methods will be available.
  33
  34         Note that the @a conv parameter is only available in Unicode builds of wxWidgets.
  35
  36         @param stream
  37             The output stream.
  38         @param conv
  39             Charset conversion object object used to encoding Unicode strings
  40             before writing them to the stream in Unicode mode (see
  41             WriteString() for a detailed description). Note that you must not
  42             destroy @a conv before you destroy this wxDataOutputStream
  43             instance! It is recommended to use the default value (UTF-8).
  44     */
  45     wxDataOutputStream(wxOutputStream& stream,
  46                        const wxMBConv& conv = wxConvAuto());
  47
  48     /**
  49         Destroys the wxDataOutputStream object.
  50     */
  51     ~wxDataOutputStream();
  52
  53     /**
  54         If @a be_order is @true, all data will be written in big-endian order,
  55         e.g. for reading on a Sparc or from Java-Streams (which always use
  56         big-endian order), otherwise data will be written in little-endian
  57         order.
  58     */
  59     void BigEndianOrdered(bool be_order);
  60
  61     /**
  62         Writes the single byte @a i8 to the stream.
  63     */
  64     void Write8(wxUint8 i8);
  65     /**
  66         Writes an array of bytes to the stream. The amount of bytes to write is
  67         specified with the @a size variable.
  68     */
  69     void Write8(const wxUint8* buffer, size_t size);
  70
  71     /**
  72         Writes the 16 bit unsigned integer @a i16 to the stream.
  73     */
  74     void Write16(wxUint16 i16);
  75     /**
  76         Writes an array of 16 bit unsigned integer to the stream. The amount of
  77         16 bit unsigned integer to write is specified with the @a size variable.
  78     */
  79     void Write16(const wxUint16* buffer, size_t size);
  80
  81     /**
  82         Writes the 32 bit unsigned integer @a i32 to the stream.
  83     */
  84     void Write32(wxUint32 i32);
  85     /**
  86         Writes an array of 32 bit unsigned integer to the stream. The amount of
  87         32 bit unsigned integer to write is specified with the @a size variable.
  88     */
  89     void Write32(const wxUint32* buffer, size_t size);
  90
  91     /**
  92         Writes the 64 bit unsigned integer @a i64 to the stream.
  93     */
  94     void Write64(wxUint64 i64);
  95     /**
  96         Writes an array of 64 bit unsigned integer to the stream. The amount of
  97         64 bit unsigned integer to write is specified with the @a size variable.
  98     */
  99     void Write64(const wxUint64* buffer, size_t size);
 100
 101     /**
 102         Writes the double @a f to the stream using the IEEE format.
 103     */
 104     void WriteDouble(double f);
 105     /**
 106         Writes an array of double to the stream. The amount of double to write is
 107         specified with the @a size variable.
 108     */
 109     void WriteDouble(const double* buffer, size_t size);
 110
 111     /**
 112         Writes @a string to the stream. Actually, this method writes the size
 113         of the string before writing @a string itself.
 114
 115         In ANSI build of wxWidgets, the string is written to the stream in
 116         exactly same way it is represented in memory. In Unicode build,
 117         however, the string is first converted to multibyte representation with
 118         @e conv object passed to stream's constructor (consequently, ANSI
 119         applications can read data written by Unicode application, as long as
 120         they agree on encoding) and this representation is written to the
 121         stream. UTF-8 is used by default.
 122     */
 123     void WriteString(const wxString& string);
 124 };
 125
 126
 127
 128 /**
 129     @class wxDataInputStream
 130
 131     This class provides functions that read binary data types in a portable
 132     way. Data can be read in either big-endian or little-endian format,
 133     little-endian being the default on all architectures.
 134
 135     If you want to read data from text files (or streams) use wxTextInputStream
 136     instead.
 137
 138     The ">>" operator is overloaded and you can use this class like a standard
 139     C++ iostream. Note, however, that the arguments are the fixed size types
 140     wxUint32, wxInt32 etc and on a typical 32-bit computer, none of these match
 141     to the "long" type (wxInt32 is defined as signed int on 32-bit
 142     architectures) so that you cannot use long. To avoid problems (here and
 143     elsewhere), make use of the wxInt32, wxUint32, etc types.
 144
 145     For example:
 146
 147     @code
 148     wxFileInputStream input( "mytext.dat" );
 149     wxDataInputStream store( input );
 150     wxUint8 i1;
 151     float f2;
 152     wxString line;
 153
 154     store >> i1;       // read a 8 bit integer.
 155     store >> i1 >> f2; // read a 8 bit integer followed by float.
 156     store >> line;     // read a text line
 157     @endcode
 158
 159     @library{wxbase}
 160     @category{streams}
 161
 162     @see wxDataOutputStream
 163 */
 164 class wxDataInputStream
 165 {
 166 public:
 167     /**
 168         Constructs a datastream object from an input stream.
 169         Only read methods will be available.
 170
 171         Note that the @a conv parameter is only available in Unicode builds of wxWidgets.
 172
 173         @param stream
 174             The input stream.
 175         @param conv
 176             Charset conversion object object used to decode strings in Unicode
 177             mode (see ReadString() for a detailed description). Note that you
 178             must not destroy @a conv before you destroy this wxDataInputStream
 179             instance!
 180     */
 181     wxDataInputStream(wxInputStream& stream,
 182                       const wxMBConv& conv = wxConvAuto());
 183
 184     /**
 185         Destroys the wxDataInputStream object.
 186     */
 187     ~wxDataInputStream();
 188
 189     /**
 190         If @a be_order is @true, all data will be read in big-endian order,
 191         such as written by programs on a big endian architecture (e.g. Sparc)
 192         or written by Java-Streams (which always use big-endian order).
 193     */
 194     void BigEndianOrdered(bool be_order);
 195
 196     /**
 197         Reads a single byte from the stream.
 198     */
 199     wxUint8 Read8();
 200     /**
 201         Reads bytes from the stream in a specified buffer. The amount of bytes
 202         to read is specified by the @a size variable.
 203     */
 204     void Read8(wxUint8* buffer, size_t size);
 205
 206     /**
 207         Reads a 16 bit unsigned integer from the stream.
 208     */
 209     wxUint16 Read16();
 210     /**
 211         Reads 16 bit unsigned integers from the stream in a specified buffer.
 212         The amount of 16 bit unsigned integers to read is specified by the
 213         @a size variable.
 214     */
 215     void Read16(wxUint16* buffer, size_t size);
 216
 217     /**
 218         Reads a 32 bit unsigned integer from the stream.
 219     */
 220     wxUint32 Read32();
 221     /**
 222         Reads 32 bit unsigned integers from the stream in a specified buffer.
 223         The amount of 32 bit unsigned integers to read is specified by the
 224         @a size variable.
 225     */
 226     void Read32(wxUint32* buffer, size_t size);
 227
 228     /**
 229         Reads a 64 bit unsigned integer from the stream.
 230     */
 231     wxUint64 Read64();
 232     /**
 233         Reads 64 bit unsigned integers from the stream in a specified buffer.
 234         The amount of 64 bit unsigned integers to read is specified by the
 235         @a size variable.
 236     */
 237     void Read64(wxUint64* buffer, size_t size);
 238
 239     /**
 240         Reads a double (IEEE encoded) from the stream.
 241     */
 242     double ReadDouble();
 243     /**
 244         Reads double data (IEEE encoded) from the stream in a specified buffer.
 245         The amount of doubles to read is specified by the @a size variable.
 246     */
 247     void ReadDouble(double* buffer, size_t size);
 248
 249     /**
 250         Reads a string from a stream. Actually, this function first reads a
 251         long integer specifying the length of the string (without the last null
 252         character) and then reads the string.
 253
 254         In Unicode build of wxWidgets, the fuction first reads multibyte
 255         (char*) string from the stream and then converts it to Unicode using
 256         the @e conv object passed to constructor and returns the result as
 257         wxString. You are responsible for using the same convertor as when
 258         writing the stream.
 259
 260         @see wxDataOutputStream::WriteString()
 261     */
 262     wxString ReadString();
 263 };
 264