interface/wx/datstrm.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        datstrm.h
   3 // Purpose:     interface of wxDataInputStream and wxDataOutputStream
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxDataOutputStream
  10
  11     This class provides functions that write binary data types in a portable
  12     way.
  13
  14     Data can be written in either big-endian or little-endian format,
  15     little-endian being the default on all architectures but BigEndianOrdered()
  16     can be used to change this. The default format for the floating point types
  17     is 80 bit "extended precision" unless @c wxUSE_APPLE_IEEE was turned off
  18     during the library compilation, in which case extended precision is not
  19     available at all. You can call UseBasicPrecisions() to change this and
  20     use the standard IEEE 754 32 bit single precision format for floats and
  21     standard 64 bit double precision format for doubles. This is recommended
  22     for the new code for better interoperability with other software that
  23     typically uses standard IEEE 754 formats for its data, the use of extended
  24     precision by default is solely due to backwards compatibility.
  25
  26     If you want to write data to text files (or streams) use wxTextOutputStream
  27     instead.
  28
  29     The "<<" operator is overloaded and you can use this class like a standard
  30     C++ iostream. See wxDataInputStream for its usage and caveats.
  31
  32     @library{wxbase}
  33     @category{streams}
  34
  35     @see wxDataInputStream
  36 */
  37 class wxDataOutputStream
  38 {
  39 public:
  40     /**
  41         Constructs a datastream object from an output stream.
  42         Only write methods will be available.
  43
  44         Note that the @a conv parameter is only available in Unicode builds of wxWidgets.
  45
  46         @param stream
  47             The output stream.
  48         @param conv
  49             Charset conversion object used to encoding Unicode strings
  50             before writing them to the stream in Unicode mode (see
  51             WriteString() for a detailed description). Note that you must not
  52             destroy @a conv before you destroy this wxDataOutputStream
  53             instance! It is recommended to use the default value (UTF-8).
  54     */
  55     wxDataOutputStream(wxOutputStream& stream,
  56                        const wxMBConv& conv = wxConvUTF8);
  57
  58     /**
  59         Destroys the wxDataOutputStream object.
  60     */
  61     ~wxDataOutputStream();
  62
  63     /**
  64         If @a be_order is @true, all data will be written in big-endian order,
  65         e.g. for reading on a Sparc or from Java-Streams (which always use
  66         big-endian order), otherwise data will be written in little-endian
  67         order.
  68     */
  69     void BigEndianOrdered(bool be_order);
  70
  71     /**
  72        Returns the current text conversion class used for
  73        writing strings.
  74     */
  75     wxMBConv *GetConv() const;
  76
  77     /**
  78        Sets the text conversion class used for writing strings.
  79     */
  80     void SetConv( const wxMBConv &conv );
  81
  82     /**
  83         Disables the use of extended precision format for floating point
  84         numbers.
  85
  86         This method disables the use of 80 bit extended precision format for
  87         the @c float and @c double values written to the stream, which is used
  88         by default (unless @c wxUSE_APPLE_IEEE was set to @c 0 when building
  89         the library, in which case the extended format support is not available
  90         at all and this function does nothing).
  91
  92         After calling it, @c float values will be written out in one of IEEE
  93         754 "basic formats", i.e. 32 bit single precision format for floats and
  94         64 bit double precision format for doubles.
  95
  96         @since 2.9.5
  97     */
  98     void UseBasicPrecisions();
  99
 100     /**
 101         Explicitly request the use of extended precision for floating point
 102         numbers.
 103
 104         This function allows the application code to explicitly request the use
 105         of 80 bit extended precision format for the floating point numbers.
 106         This is the case by default but using this function explicitly ensures
 107         that the compilation of code relying on producing the output stream
 108         using extended precision would fail when using a version of wxWidgets
 109         compiled with @c wxUSE_APPLE_IEEE==0 and so not supporting this format
 110         at all.
 111
 112         @since 2.9.5
 113      */
 114     void UseExtendedPrecision();
 115
 116     /**
 117         Writes the single byte @a i8 to the stream.
 118     */
 119     void Write8(wxUint8 i8);
 120     /**
 121         Writes an array of bytes to the stream. The number of bytes to write is
 122         specified with the @a size variable.
 123     */
 124     void Write8(const wxUint8* buffer, size_t size);
 125
 126     /**
 127         Writes the 16 bit unsigned integer @a i16 to the stream.
 128     */
 129     void Write16(wxUint16 i16);
 130     /**
 131         Writes an array of 16 bit unsigned integer to the stream. The number of
 132         16 bit unsigned integer to write is specified with the @a size variable.
 133     */
 134     void Write16(const wxUint16* buffer, size_t size);
 135
 136     /**
 137         Writes the 32 bit unsigned integer @a i32 to the stream.
 138     */
 139     void Write32(wxUint32 i32);
 140     /**
 141         Writes an array of 32 bit unsigned integer to the stream. The number of
 142         32 bit unsigned integer to write is specified with the @a size variable.
 143     */
 144     void Write32(const wxUint32* buffer, size_t size);
 145
 146     /**
 147         Writes the 64 bit unsigned integer @a i64 to the stream.
 148     */
 149     void Write64(wxUint64 i64);
 150     /**
 151         Writes an array of 64 bit unsigned integer to the stream. The number of
 152         64 bit unsigned integer to write is specified with the @a size variable.
 153     */
 154     void Write64(const wxUint64* buffer, size_t size);
 155
 156     /**
 157         Writes the float @a f to the stream.
 158
 159         If UseBasicPrecisions() had been called, the value is written out using
 160         the standard IEEE 754 32 bit single precision format. Otherwise, this
 161         method uses the same format as WriteDouble(), i.e. 80 bit extended
 162         precision representation.
 163
 164         @since 2.9.5
 165     */
 166     void WriteFloat(float f);
 167
 168     /**
 169         Writes an array of float to the stream. The number of floats to write is
 170         specified by the @a size variable.
 171
 172         @since 2.9.5
 173     */
 174     void WriteFloat(const float* buffer, size_t size);
 175
 176     /**
 177         Writes the double @a d to the stream.
 178
 179         The output format is either 80 bit extended precision or, if
 180         UseBasicPrecisions() had been called, standard IEEE 754 64 bit double
 181         precision.
 182     */
 183     void WriteDouble(double d);
 184
 185     /**
 186         Writes an array of double to the stream. The number of doubles to write is
 187         specified by the @a size variable.
 188     */
 189     void WriteDouble(const double* buffer, size_t size);
 190
 191     /**
 192         Writes @a string to the stream. Actually, this method writes the size
 193         of the string before writing @a string itself.
 194
 195         In ANSI build of wxWidgets, the string is written to the stream in
 196         exactly same way it is represented in memory. In Unicode build,
 197         however, the string is first converted to multibyte representation with
 198         @e conv object passed to stream's constructor (consequently, ANSI
 199         applications can read data written by Unicode application, as long as
 200         they agree on encoding) and this representation is written to the
 201         stream. UTF-8 is used by default.
 202     */
 203     void WriteString(const wxString& string);
 204 };
 205
 206
 207
 208 /**
 209     @class wxDataInputStream
 210
 211     This class provides functions that read binary data types in a portable
 212     way.
 213
 214     Please see wxDataOutputStream for the discussion of the format expected by
 215     this stream on input, notably for the floating point values.
 216
 217     If you want to read data from text files (or streams) use wxTextInputStream
 218     instead.
 219
 220     The ">>" operator is overloaded and you can use this class like a standard
 221     C++ iostream. Note, however, that the arguments are the fixed size types
 222     wxUint32, wxInt32 etc and on a typical 32-bit computer, none of these match
 223     to the "long" type (wxInt32 is defined as signed int on 32-bit
 224     architectures) so that you cannot use long. To avoid problems (here and
 225     elsewhere), make use of the wxInt32, wxUint32, etc types.
 226
 227     For example:
 228
 229     @code
 230     wxFileInputStream input( "mytext.dat" );
 231     wxDataInputStream store( input );
 232     wxUint8 i1;
 233     float f2;
 234     wxString line;
 235
 236     store >> i1;       // read a 8 bit integer.
 237     store >> i1 >> f2; // read a 8 bit integer followed by float.
 238     store >> line;     // read a text line
 239     @endcode
 240
 241     @library{wxbase}
 242     @category{streams}
 243
 244     @see wxDataOutputStream
 245 */
 246 class wxDataInputStream
 247 {
 248 public:
 249     /**
 250         Constructs a datastream object from an input stream.
 251         Only read methods will be available.
 252
 253         Note that the @a conv parameter is only available in Unicode builds of wxWidgets.
 254
 255         @param stream
 256             The input stream.
 257         @param conv
 258             Charset conversion object used to decode strings in Unicode
 259             mode (see ReadString() for a detailed description). Note that you
 260             must not destroy @a conv before you destroy this wxDataInputStream
 261             instance!
 262     */
 263     wxDataInputStream(wxInputStream& stream,
 264                       const wxMBConv& conv = wxConvUTF8 );
 265
 266     /**
 267         Destroys the wxDataInputStream object.
 268     */
 269     ~wxDataInputStream();
 270
 271     /**
 272         If @a be_order is @true, all data will be read in big-endian order,
 273         such as written by programs on a big endian architecture (e.g. Sparc)
 274         or written by Java-Streams (which always use big-endian order).
 275     */
 276     void BigEndianOrdered(bool be_order);
 277
 278     /**
 279        Returns the current text conversion class used for
 280        reading strings.
 281     */
 282     wxMBConv *GetConv() const;
 283
 284     /**
 285         Reads a single byte from the stream.
 286     */
 287     wxUint8 Read8();
 288     /**
 289         Reads bytes from the stream in a specified buffer. The number of bytes
 290         to read is specified by the @a size variable.
 291     */
 292     void Read8(wxUint8* buffer, size_t size);
 293
 294     /**
 295         Reads a 16 bit unsigned integer from the stream.
 296     */
 297     wxUint16 Read16();
 298     /**
 299         Reads 16 bit unsigned integers from the stream in a specified buffer.
 300         The number of 16 bit unsigned integers to read is specified by the
 301         @a size variable.
 302     */
 303     void Read16(wxUint16* buffer, size_t size);
 304
 305     /**
 306         Reads a 32 bit unsigned integer from the stream.
 307     */
 308     wxUint32 Read32();
 309     /**
 310         Reads 32 bit unsigned integers from the stream in a specified buffer.
 311         The number of 32 bit unsigned integers to read is specified by the
 312         @a size variable.
 313     */
 314     void Read32(wxUint32* buffer, size_t size);
 315
 316     /**
 317         Reads a 64 bit unsigned integer from the stream.
 318     */
 319     wxUint64 Read64();
 320     /**
 321         Reads 64 bit unsigned integers from the stream in a specified buffer.
 322         The number of 64 bit unsigned integers to read is specified by the
 323         @a size variable.
 324     */
 325     void Read64(wxUint64* buffer, size_t size);
 326
 327     /**
 328         Reads a float from the stream.
 329
 330         Notice that if UseBasicPrecisions() hadn't been called, this function
 331         simply reads a double and truncates it to float as by default the same
 332         (80 bit extended precision) representation is used for both float and
 333         double values.
 334
 335         @since 2.9.5
 336     */
 337     float ReadFloat();
 338
 339     /**
 340         Reads float data from the stream in a specified buffer.
 341
 342         The number of floats to read is specified by the @a size variable.
 343
 344         @since 2.9.5
 345     */
 346     void ReadFloat(float* buffer, size_t size);
 347
 348     /**
 349         Reads a double from the stream.
 350
 351         The expected format is either 80 bit extended precision or, if
 352         UseBasicPrecisions() had been called, standard IEEE 754 64 bit double
 353         precision.
 354     */
 355     double ReadDouble();
 356
 357     /**
 358         Reads double data  from the stream in a specified buffer.
 359
 360         The number of doubles to read is specified by the @a size variable.
 361     */
 362     void ReadDouble(double* buffer, size_t size);
 363
 364     /**
 365         Reads a string from a stream. Actually, this function first reads a
 366         long integer specifying the length of the string (without the last null
 367         character) and then reads the string.
 368
 369         In Unicode build of wxWidgets, the fuction first reads multibyte
 370         (char*) string from the stream and then converts it to Unicode using
 371         the @e conv object passed to constructor and returns the result as
 372         wxString. You are responsible for using the same converter as when
 373         writing the stream.
 374
 375         @see wxDataOutputStream::WriteString()
 376     */
 377     wxString ReadString();
 378
 379     /**
 380        Sets the text conversion class used for reading strings.
 381     */
 382     void SetConv( const wxMBConv &conv );
 383
 384     /**
 385         Disables the use of extended precision format for floating point
 386         numbers.
 387
 388         This method disables the use of 80 bit extended precision format for
 389         the @c float and @c double values read from the stream, which is used
 390         by default (unless @c wxUSE_APPLE_IEEE was set to @c 0 when building
 391         the library, in which case the extended format support is not available
 392         at all and this function does nothing).
 393
 394         After calling it, @c float values will be expected to appear in one of
 395         IEEE 754 "basic formats", i.e. 32 bit single precision format for
 396         floats and 64 bit double precision format for doubles in the input.
 397
 398         @since 2.9.5
 399     */
 400     void UseBasicPrecisions();
 401
 402     /**
 403         Explicitly request the use of extended precision for floating point
 404         numbers.
 405
 406         This function allows the application code to explicitly request the use
 407         of 80 bit extended precision format for the floating point numbers.
 408         This is the case by default but using this function explicitly ensures
 409         that the compilation of code relying on reading the input containing
 410         numbers in extended precision format would fail when using a version of
 411         wxWidgets compiled with @c wxUSE_APPLE_IEEE==0 and so not supporting
 412         this format at all.
 413
 414         @since 2.9.5
 415      */
 416     void UseExtendedPrecision();
 417 };
 418