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 licence
   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 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 = wxConvUTF8);
  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        Returns the current text conversion class used for
  63        writing strings.
  64     */
  65     wxMBConv *GetConv() const;
  66
  67     /**
  68        Sets the text conversion class used for writing strings.
  69     */
  70     void SetConv( const wxMBConv &conv );
  71
  72     /**
  73         Writes the single byte @a i8 to the stream.
  74     */
  75     void Write8(wxUint8 i8);
  76     /**
  77         Writes an array of bytes to the stream. The amount of bytes to write is
  78         specified with the @a size variable.
  79     */
  80     void Write8(const wxUint8* buffer, size_t size);
  81
  82     /**
  83         Writes the 16 bit unsigned integer @a i16 to the stream.
  84     */
  85     void Write16(wxUint16 i16);
  86     /**
  87         Writes an array of 16 bit unsigned integer to the stream. The amount of
  88         16 bit unsigned integer to write is specified with the @a size variable.
  89     */
  90     void Write16(const wxUint16* buffer, size_t size);
  91
  92     /**
  93         Writes the 32 bit unsigned integer @a i32 to the stream.
  94     */
  95     void Write32(wxUint32 i32);
  96     /**
  97         Writes an array of 32 bit unsigned integer to the stream. The amount of
  98         32 bit unsigned integer to write is specified with the @a size variable.
  99     */
 100     void Write32(const wxUint32* buffer, size_t size);
 101
 102     /**
 103         Writes the 64 bit unsigned integer @a i64 to the stream.
 104     */
 105     void Write64(wxUint64 i64);
 106     /**
 107         Writes an array of 64 bit unsigned integer to the stream. The amount of
 108         64 bit unsigned integer to write is specified with the @a size variable.
 109     */
 110     void Write64(const wxUint64* buffer, size_t size);
 111
 112     /**
 113         Writes the double @a f to the stream using the IEEE format.
 114     */
 115     void WriteDouble(double f);
 116     /**
 117         Writes an array of double to the stream. The amount of double to write is
 118         specified with the @a size variable.
 119     */
 120     void WriteDouble(const double* buffer, size_t size);
 121
 122     /**
 123         Writes @a string to the stream. Actually, this method writes the size
 124         of the string before writing @a string itself.
 125
 126         In ANSI build of wxWidgets, the string is written to the stream in
 127         exactly same way it is represented in memory. In Unicode build,
 128         however, the string is first converted to multibyte representation with
 129         @e conv object passed to stream's constructor (consequently, ANSI
 130         applications can read data written by Unicode application, as long as
 131         they agree on encoding) and this representation is written to the
 132         stream. UTF-8 is used by default.
 133     */
 134     void WriteString(const wxString& string);
 135 };
 136
 137
 138
 139 /**
 140     @class wxDataInputStream
 141
 142     This class provides functions that read binary data types in a portable
 143     way. Data can be read in either big-endian or little-endian format,
 144     little-endian being the default on all architectures.
 145
 146     If you want to read data from text files (or streams) use wxTextInputStream
 147     instead.
 148
 149     The ">>" operator is overloaded and you can use this class like a standard
 150     C++ iostream. Note, however, that the arguments are the fixed size types
 151     wxUint32, wxInt32 etc and on a typical 32-bit computer, none of these match
 152     to the "long" type (wxInt32 is defined as signed int on 32-bit
 153     architectures) so that you cannot use long. To avoid problems (here and
 154     elsewhere), make use of the wxInt32, wxUint32, etc types.
 155
 156     For example:
 157
 158     @code
 159     wxFileInputStream input( "mytext.dat" );
 160     wxDataInputStream store( input );
 161     wxUint8 i1;
 162     float f2;
 163     wxString line;
 164
 165     store >> i1;       // read a 8 bit integer.
 166     store >> i1 >> f2; // read a 8 bit integer followed by float.
 167     store >> line;     // read a text line
 168     @endcode
 169
 170     @library{wxbase}
 171     @category{streams}
 172
 173     @see wxDataOutputStream
 174 */
 175 class wxDataInputStream
 176 {
 177 public:
 178     /**
 179         Constructs a datastream object from an input stream.
 180         Only read methods will be available.
 181
 182         Note that the @a conv parameter is only available in Unicode builds of wxWidgets.
 183
 184         @param stream
 185             The input stream.
 186         @param conv
 187             Charset conversion object used to decode strings in Unicode
 188             mode (see ReadString() for a detailed description). Note that you
 189             must not destroy @a conv before you destroy this wxDataInputStream
 190             instance!
 191     */
 192     wxDataInputStream(wxInputStream& stream,
 193                       const wxMBConv& conv = wxConvUTF8 );
 194
 195     /**
 196         Destroys the wxDataInputStream object.
 197     */
 198     ~wxDataInputStream();
 199
 200     /**
 201         If @a be_order is @true, all data will be read in big-endian order,
 202         such as written by programs on a big endian architecture (e.g. Sparc)
 203         or written by Java-Streams (which always use big-endian order).
 204     */
 205     void BigEndianOrdered(bool be_order);
 206
 207
 208     /**
 209        Returns the current text conversion class used for
 210        reading strings.
 211     */
 212     wxMBConv *GetConv() const;
 213
 214     /**
 215         Reads a single byte from the stream.
 216     */
 217     wxUint8 Read8();
 218     /**
 219         Reads bytes from the stream in a specified buffer. The amount of bytes
 220         to read is specified by the @a size variable.
 221     */
 222     void Read8(wxUint8* buffer, size_t size);
 223
 224     /**
 225         Reads a 16 bit unsigned integer from the stream.
 226     */
 227     wxUint16 Read16();
 228     /**
 229         Reads 16 bit unsigned integers from the stream in a specified buffer.
 230         The amount of 16 bit unsigned integers to read is specified by the
 231         @a size variable.
 232     */
 233     void Read16(wxUint16* buffer, size_t size);
 234
 235     /**
 236         Reads a 32 bit unsigned integer from the stream.
 237     */
 238     wxUint32 Read32();
 239     /**
 240         Reads 32 bit unsigned integers from the stream in a specified buffer.
 241         The amount of 32 bit unsigned integers to read is specified by the
 242         @a size variable.
 243     */
 244     void Read32(wxUint32* buffer, size_t size);
 245
 246     /**
 247         Reads a 64 bit unsigned integer from the stream.
 248     */
 249     wxUint64 Read64();
 250     /**
 251         Reads 64 bit unsigned integers from the stream in a specified buffer.
 252         The amount of 64 bit unsigned integers to read is specified by the
 253         @a size variable.
 254     */
 255     void Read64(wxUint64* buffer, size_t size);
 256
 257     /**
 258         Reads a double (IEEE encoded) from the stream.
 259     */
 260     double ReadDouble();
 261     /**
 262         Reads double data (IEEE encoded) from the stream in a specified buffer.
 263         The amount of doubles to read is specified by the @a size variable.
 264     */
 265     void ReadDouble(double* buffer, size_t size);
 266
 267     /**
 268         Reads a string from a stream. Actually, this function first reads a
 269         long integer specifying the length of the string (without the last null
 270         character) and then reads the string.
 271
 272         In Unicode build of wxWidgets, the fuction first reads multibyte
 273         (char*) string from the stream and then converts it to Unicode using
 274         the @e conv object passed to constructor and returns the result as
 275         wxString. You are responsible for using the same converter as when
 276         writing the stream.
 277
 278         @see wxDataOutputStream::WriteString()
 279     */
 280     wxString ReadString();
 281
 282     /**
 283        Sets the text conversion class used for reading strings.
 284     */
 285     void SetConv( const wxMBConv &conv );
 286 };
 287