X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7323ff1aee02cc8c8979b6b25f84049ab0c081ae..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/datstrm.h diff --git a/interface/wx/datstrm.h b/interface/wx/datstrm.h index 8ff65a4495..2a54d9f57b 100644 --- a/interface/wx/datstrm.h +++ b/interface/wx/datstrm.h @@ -2,16 +2,26 @@ // Name: datstrm.h // Purpose: interface of wxDataInputStream and wxDataOutputStream // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @class wxDataOutputStream This class provides functions that write binary data types in a portable - way. Data can be written in either big-endian or little-endian format, - little-endian being the default on all architectures. + way. + + Data can be written in either big-endian or little-endian format, + little-endian being the default on all architectures but BigEndianOrdered() + can be used to change this. The default format for the floating point types + is 80 bit "extended precision" unless @c wxUSE_APPLE_IEEE was turned off + during the library compilation, in which case extended precision is not + available at all. You can call UseBasicPrecisions() to change this and + use the standard IEEE 754 32 bit single precision format for floats and + standard 64 bit double precision format for doubles. This is recommended + for the new code for better interoperability with other software that + typically uses standard IEEE 754 formats for its data, the use of extended + precision by default is solely due to backwards compatibility. If you want to write data to text files (or streams) use wxTextOutputStream instead. @@ -36,14 +46,14 @@ public: @param stream The output stream. @param conv - Charset conversion object object used to encoding Unicode strings + Charset conversion object used to encoding Unicode strings before writing them to the stream in Unicode mode (see WriteString() for a detailed description). Note that you must not destroy @a conv before you destroy this wxDataOutputStream instance! It is recommended to use the default value (UTF-8). */ wxDataOutputStream(wxOutputStream& stream, - const wxMBConv& conv = wxConvAuto()); + const wxMBConv& conv = wxConvUTF8); /** Destroys the wxDataOutputStream object. @@ -58,12 +68,57 @@ public: */ void BigEndianOrdered(bool be_order); + /** + Returns the current text conversion class used for + writing strings. + */ + wxMBConv *GetConv() const; + + /** + Sets the text conversion class used for writing strings. + */ + void SetConv( const wxMBConv &conv ); + + /** + Disables the use of extended precision format for floating point + numbers. + + This method disables the use of 80 bit extended precision format for + the @c float and @c double values written to the stream, which is used + by default (unless @c wxUSE_APPLE_IEEE was set to @c 0 when building + the library, in which case the extended format support is not available + at all and this function does nothing). + + After calling it, @c float values will be written out in one of IEEE + 754 "basic formats", i.e. 32 bit single precision format for floats and + 64 bit double precision format for doubles. + + @since 2.9.5 + */ + void UseBasicPrecisions(); + + /** + Explicitly request the use of extended precision for floating point + numbers. + + This function allows the application code to explicitly request the use + of 80 bit extended precision format for the floating point numbers. + This is the case by default but using this function explicitly ensures + that the compilation of code relying on producing the output stream + using extended precision would fail when using a version of wxWidgets + compiled with @c wxUSE_APPLE_IEEE==0 and so not supporting this format + at all. + + @since 2.9.5 + */ + void UseExtendedPrecision(); + /** Writes the single byte @a i8 to the stream. */ void Write8(wxUint8 i8); /** - Writes an array of bytes to the stream. The amount of bytes to write is + Writes an array of bytes to the stream. The number of bytes to write is specified with the @a size variable. */ void Write8(const wxUint8* buffer, size_t size); @@ -73,7 +128,7 @@ public: */ void Write16(wxUint16 i16); /** - Writes an array of 16 bit unsigned integer to the stream. The amount of + Writes an array of 16 bit unsigned integer to the stream. The number of 16 bit unsigned integer to write is specified with the @a size variable. */ void Write16(const wxUint16* buffer, size_t size); @@ -83,7 +138,7 @@ public: */ void Write32(wxUint32 i32); /** - Writes an array of 32 bit unsigned integer to the stream. The amount of + Writes an array of 32 bit unsigned integer to the stream. The number of 32 bit unsigned integer to write is specified with the @a size variable. */ void Write32(const wxUint32* buffer, size_t size); @@ -93,18 +148,43 @@ public: */ void Write64(wxUint64 i64); /** - Writes an array of 64 bit unsigned integer to the stream. The amount of + Writes an array of 64 bit unsigned integer to the stream. The number of 64 bit unsigned integer to write is specified with the @a size variable. */ void Write64(const wxUint64* buffer, size_t size); /** - Writes the double @a f to the stream using the IEEE format. + Writes the float @a f to the stream. + + If UseBasicPrecisions() had been called, the value is written out using + the standard IEEE 754 32 bit single precision format. Otherwise, this + method uses the same format as WriteDouble(), i.e. 80 bit extended + precision representation. + + @since 2.9.5 */ - void WriteDouble(double f); + void WriteFloat(float f); + /** - Writes an array of double to the stream. The amount of double to write is - specified with the @a size variable. + Writes an array of float to the stream. The number of floats to write is + specified by the @a size variable. + + @since 2.9.5 + */ + void WriteFloat(const float* buffer, size_t size); + + /** + Writes the double @a d to the stream. + + The output format is either 80 bit extended precision or, if + UseBasicPrecisions() had been called, standard IEEE 754 64 bit double + precision. + */ + void WriteDouble(double d); + + /** + Writes an array of double to the stream. The number of doubles to write is + specified by the @a size variable. */ void WriteDouble(const double* buffer, size_t size); @@ -129,8 +209,10 @@ public: @class wxDataInputStream This class provides functions that read binary data types in a portable - way. Data can be read in either big-endian or little-endian format, - little-endian being the default on all architectures. + way. + + Please see wxDataOutputStream for the discussion of the format expected by + this stream on input, notably for the floating point values. If you want to read data from text files (or streams) use wxTextInputStream instead. @@ -173,13 +255,13 @@ public: @param stream The input stream. @param conv - Charset conversion object object used to decode strings in Unicode + Charset conversion object used to decode strings in Unicode mode (see ReadString() for a detailed description). Note that you must not destroy @a conv before you destroy this wxDataInputStream instance! */ wxDataInputStream(wxInputStream& stream, - const wxMBConv& conv = wxConvAuto()); + const wxMBConv& conv = wxConvUTF8 ); /** Destroys the wxDataInputStream object. @@ -193,12 +275,18 @@ public: */ void BigEndianOrdered(bool be_order); + /** + Returns the current text conversion class used for + reading strings. + */ + wxMBConv *GetConv() const; + /** Reads a single byte from the stream. */ wxUint8 Read8(); /** - Reads bytes from the stream in a specified buffer. The amount of bytes + Reads bytes from the stream in a specified buffer. The number of bytes to read is specified by the @a size variable. */ void Read8(wxUint8* buffer, size_t size); @@ -209,7 +297,7 @@ public: wxUint16 Read16(); /** Reads 16 bit unsigned integers from the stream in a specified buffer. - The amount of 16 bit unsigned integers to read is specified by the + The number of 16 bit unsigned integers to read is specified by the @a size variable. */ void Read16(wxUint16* buffer, size_t size); @@ -220,7 +308,7 @@ public: wxUint32 Read32(); /** Reads 32 bit unsigned integers from the stream in a specified buffer. - The amount of 32 bit unsigned integers to read is specified by the + The number of 32 bit unsigned integers to read is specified by the @a size variable. */ void Read32(wxUint32* buffer, size_t size); @@ -231,18 +319,45 @@ public: wxUint64 Read64(); /** Reads 64 bit unsigned integers from the stream in a specified buffer. - The amount of 64 bit unsigned integers to read is specified by the + The number of 64 bit unsigned integers to read is specified by the @a size variable. */ void Read64(wxUint64* buffer, size_t size); /** - Reads a double (IEEE encoded) from the stream. + Reads a float from the stream. + + Notice that if UseBasicPrecisions() hadn't been called, this function + simply reads a double and truncates it to float as by default the same + (80 bit extended precision) representation is used for both float and + double values. + + @since 2.9.5 + */ + float ReadFloat(); + + /** + Reads float data from the stream in a specified buffer. + + The number of floats to read is specified by the @a size variable. + + @since 2.9.5 + */ + void ReadFloat(float* buffer, size_t size); + + /** + Reads a double from the stream. + + The expected format is either 80 bit extended precision or, if + UseBasicPrecisions() had been called, standard IEEE 754 64 bit double + precision. */ double ReadDouble(); + /** - Reads double data (IEEE encoded) from the stream in a specified buffer. - The amount of doubles to read is specified by the @a size variable. + Reads double data from the stream in a specified buffer. + + The number of doubles to read is specified by the @a size variable. */ void ReadDouble(double* buffer, size_t size); @@ -254,11 +369,50 @@ public: In Unicode build of wxWidgets, the fuction first reads multibyte (char*) string from the stream and then converts it to Unicode using the @e conv object passed to constructor and returns the result as - wxString. You are responsible for using the same convertor as when + wxString. You are responsible for using the same converter as when writing the stream. @see wxDataOutputStream::WriteString() */ wxString ReadString(); + + /** + Sets the text conversion class used for reading strings. + */ + void SetConv( const wxMBConv &conv ); + + /** + Disables the use of extended precision format for floating point + numbers. + + This method disables the use of 80 bit extended precision format for + the @c float and @c double values read from the stream, which is used + by default (unless @c wxUSE_APPLE_IEEE was set to @c 0 when building + the library, in which case the extended format support is not available + at all and this function does nothing). + + After calling it, @c float values will be expected to appear in one of + IEEE 754 "basic formats", i.e. 32 bit single precision format for + floats and 64 bit double precision format for doubles in the input. + + @since 2.9.5 + */ + void UseBasicPrecisions(); + + /** + Explicitly request the use of extended precision for floating point + numbers. + + This function allows the application code to explicitly request the use + of 80 bit extended precision format for the floating point numbers. + This is the case by default but using this function explicitly ensures + that the compilation of code relying on reading the input containing + numbers in extended precision format would fail when using a version of + wxWidgets compiled with @c wxUSE_APPLE_IEEE==0 and so not supporting + this format at all. + + @since 2.9.5 + */ + void UseExtendedPrecision(); };