support for iPhone callbacks

[wxWidgets.git] / interface / wx / datstrm.h

diff --git a/interface/wx/datstrm.h b/interface/wx/datstrm.h
index 7f0861b8c0d8fc0c1523804ab27ba7bd99645caf..c4fc3d272ea4122abf99364e32c5d4f28d664a01 100644 (file)
--- a/interface/wx/datstrm.h
+++ b/interface/wx/datstrm.h
@@ -10,8 +10,19 @@
     @class wxDataOutputStream
 
     This class provides functions that write binary data types in a portable
     @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.
 
     If you want to write data to text files (or streams) use wxTextOutputStream
     instead.


@@ -57,24 +68,58 @@ public:
         order.
     */
     void BigEndianOrdered(bool be_order);
         order.
     */
     void BigEndianOrdered(bool be_order);

-    
+

     /**
        Returns the current text conversion class used for
        writing strings.
     */
     wxMBConv *GetConv() const;
 
     /**
        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 );
        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 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);
         specified with the @a size variable.
     */
     void Write8(const wxUint8* buffer, size_t size);


@@ -84,7 +129,7 @@ public:
     */
     void Write16(wxUint16 i16);
     /**
     */
     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);
         16 bit unsigned integer to write is specified with the @a size variable.
     */
     void Write16(const wxUint16* buffer, size_t size);


@@ -94,7 +139,7 @@ public:
     */
     void Write32(wxUint32 i32);
     /**
     */
     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);
         32 bit unsigned integer to write is specified with the @a size variable.
     */
     void Write32(const wxUint32* buffer, size_t size);


@@ -104,18 +149,43 @@ public:
     */
     void Write64(wxUint64 i64);
     /**
     */
     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);
 
     /**
         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 d 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 WriteFloat(float f);
+
+    /**
+        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);
     */
     void WriteDouble(double d);

+

     /**
     /**

-        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 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);
 
     */
     void WriteDouble(const double* buffer, size_t size);
 


@@ -140,8 +210,10 @@ public:
     @class wxDataInputStream
 
     This class provides functions that read binary data types in a portable
     @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.
 
     If you want to read data from text files (or streams) use wxTextInputStream
     instead.


@@ -204,19 +276,18 @@ public:
     */
     void BigEndianOrdered(bool be_order);
 
     */
     void BigEndianOrdered(bool be_order);
 

-    

     /**
        Returns the current text conversion class used for
        reading strings.
     */
     wxMBConv *GetConv() const;
     /**
        Returns the current text conversion class used for
        reading strings.
     */
     wxMBConv *GetConv() const;

-    
+

     /**
         Reads a single byte from the stream.
     */
     wxUint8 Read8();
     /**
     /**
         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);
         to read is specified by the @a size variable.
     */
     void Read8(wxUint8* buffer, size_t size);


@@ -227,7 +298,7 @@ public:
     wxUint16 Read16();
     /**
         Reads 16 bit unsigned integers from the stream in a specified buffer.
     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);
         @a size variable.
     */
     void Read16(wxUint16* buffer, size_t size);


@@ -238,7 +309,7 @@ public:
     wxUint32 Read32();
     /**
         Reads 32 bit unsigned integers from the stream in a specified buffer.
     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);
         @a size variable.
     */
     void Read32(wxUint32* buffer, size_t size);


@@ -249,18 +320,45 @@ public:
     wxUint64 Read64();
     /**
         Reads 64 bit unsigned integers from the stream in a specified buffer.
     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);
 
     /**
         @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();
     */
     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);
 
     */
     void ReadDouble(double* buffer, size_t size);
 


@@ -279,9 +377,43 @@ public:
     */
     wxString ReadString();
 
     */
     wxString ReadString();
 

-    /** 
+    /**

        Sets the text conversion class used for reading strings.
     */
     void SetConv( const wxMBConv &conv );
        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();

 };
 
 };