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