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