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