Make storing non-trivial data in wxThreadSpecificInfo possible.

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

diff --git a/interface/wx/datstrm.h b/interface/wx/datstrm.h
index 44b4a812c90a68e07e90907537b09d420f245765..2a54d9f57ba3d5d82390389092ab33f7c421833d 100644 (file)
--- 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
 // 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
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @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.


@@ -28,29 +38,22 @@ class wxDataOutputStream
 {
 public:
     /**
 {
 public:
     /**

-        Constructs a datastream object from an output stream. Only write
-        methods will be available.
+        Constructs a datastream object from an output stream.
+        Only write methods will be available.

 
 

-        @param stream
-            The output stream.
-    */
-    wxDataOutputStream(wxOutputStream& stream);
-    /**
-        Constructs a datastream object from an output stream. Only write
-        methods will be available. This constructor is only available in
-        Unicode builds of wxWidgets.
+        Note that the @a conv parameter is only available in Unicode builds of wxWidgets.

 
         @param stream
             The output stream.
         @param conv
 
         @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,
             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.
 
     /**
         Destroys the wxDataOutputStream object.


@@ -65,12 +68,57 @@ public:
     */
     void BigEndianOrdered(bool be_order);
 
     */
     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 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);


@@ -80,7 +128,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);


@@ -90,7 +138,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);


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


@@ -136,8 +209,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.


@@ -172,28 +247,21 @@ class wxDataInputStream
 {
 public:
     /**
 {
 public:
     /**

-        Constructs a datastream object from an input stream. Only read methods
-        will be available.
+        Constructs a datastream object from an input stream.
+        Only read methods will be available.

 
 

-        @param stream
-            The input stream.
-    */
-    wxDataInputStream(wxInputStream& stream);
-    /**
-        Constructs a datastream object from an input stream. Only read methods
-        will be available. This constructor is only available in Unicode builds
-        of wxWidgets.
+        Note that the @a conv parameter is only available in Unicode builds of wxWidgets.

 
         @param stream
             The input stream.
         @param conv
 
         @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,
             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.
 
     /**
         Destroys the wxDataInputStream object.


@@ -207,12 +275,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;
+

     /**
         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);


@@ -223,7 +297,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);


@@ -234,7 +308,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);


@@ -245,18 +319,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);
 


@@ -268,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
         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();
         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();

 };
 
 };