compilation fix for PCH-less build

[wxWidgets.git] / interface / txtstrm.h

diff --git a/interface/txtstrm.h b/interface/txtstrm.h
index 90597ebcdfbfda1e0647755762d29132a78add8d..89dd37741a7cb32c2e420b3661f32e597eee294f 100644 (file)
--- a/interface/txtstrm.h
+++ b/interface/txtstrm.h
@@ -6,57 +6,56 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+
+

 /**
     @class wxTextInputStream
     @wxheader{txtstrm.h}
 
 /**
     @class wxTextInputStream
     @wxheader{txtstrm.h}
 

-    This class provides functions that read text datas using an input stream.
-    So, you can read @e text floats, integers.
-
-    The wxTextInputStream correctly reads text files (or streams) in DOS, Macintosh
-    and Unix formats and reports a single newline char as a line ending.
-
-    Operator  is overloaded and you can use this class like a standard C++ iostream.
-    Note, however, that the arguments are the fixed size types wxUint32, wxInt32 etc
-    and on a typical 32-bit computer, none of these match to the "long" type
-    (wxInt32
-    is defined as int on 32-bit architectures) so that you cannot use long. To avoid
-    problems (here and elsewhere), make use of wxInt32, wxUint32 and similar types.
-
-    If you're scanning through a file using wxTextInputStream, you should check for
-    EOF @b before
-    reading the next item (word / number), because otherwise the last item may get
-    lost.
-    You should however be prepared to receive an empty item (empty string / zero
-    number) at the
-    end of file, especially on Windows systems. This is unavoidable because most
-    (but not all) files end
-    with whitespace (i.e. usually a newline).
+    This class provides functions that reads text data using an input stream,
+    allowing you to read text, floats, and integers.
+
+    The wxTextInputStream correctly reads text files (or streams) in DOS,
+    Macintosh and Unix formats and reports a single newline char as a line
+    ending.
+
+    wxTextInputStream::operator>>() is overloaded and you can use this class
+    like a standard C++ iostream. Note, however, that the arguments are the
+    fixed size types wxUint32, wxInt32 etc and on a typical 32-bit computer,
+    none of these match to the "long" type (wxInt32 is defined as int on 32-bit
+    architectures) so that you cannot use long. To avoid problems (here and
+    elsewhere), make use of wxInt32, wxUint32 and similar types.
+
+    If you're scanning through a file using wxTextInputStream, you should check
+    for @c EOF @b before reading the next item (word / number), because
+    otherwise the last item may get lost. You should however be prepared to
+    receive an empty item (empty string / zero number) at the end of file,
+    especially on Windows systems. This is unavoidable because most (but not
+    all) files end with whitespace (i.e. usually a newline).

 
     For example:
 
     @code
     wxFileInputStream input( "mytext.txt" );
 
     For example:
 
     @code
     wxFileInputStream input( "mytext.txt" );

-      wxTextInputStream text( input );
-      wxUint8 i1;
-      float f2;
-      wxString line;
-
-      text  i1;       // read a 8 bit integer.
-      text  i1  f2; // read a 8 bit integer followed by float.
-      text  line;     // read a text line
+    wxTextInputStream text( input );
+    wxUint8 i1;
+    float f2;
+    wxString line;
+
+    text >> i1;       // read a 8 bit integer.
+    text >> i1 >> f2; // read a 8 bit integer followed by float.
+    text >> line;     // read a text line

     @endcode
 
     @library{wxbase}
     @category{streams}
 
     @endcode
 
     @library{wxbase}
     @category{streams}
 

-    @see wxTextInputStream::SetStringSeparators
+    @see wxTextOutputStream

 */
 class wxTextInputStream
 {
 public:
     /**
 */
 class wxTextInputStream
 {
 public:
     /**

-        )

         Constructs a text stream associated to the given input stream.
 
         @param stream
         Constructs a text stream associated to the given input stream.
 
         @param stream


@@ -64,67 +63,69 @@ public:
         @param sep
             The initial string separator characters.
         @param conv
         @param sep
             The initial string separator characters.
         @param conv

-            In Unicode build only: The encoding converter used to convert the bytes in
-        the
-              underlying input stream to characters.
+            <b>In Unicode build only:</b> The encoding converter used to
+            convert the bytes in the underlying input stream to characters.

     */
     wxTextInputStream(wxInputStream& stream,
     */
     wxTextInputStream(wxInputStream& stream,

-                      const wxString& sep = " \t");
+                      const wxString& sep = " \t",
+                      const wxMBConv& conv = wxConvAuto());

 
     /**
 
     /**

-        Destroys the wxTextInputStream object.
+        Destructor.

     */
     ~wxTextInputStream();
 
     /**
     */
     ~wxTextInputStream();
 
     /**

-        Reads a character, returns 0 if there are no more characters in the stream.
+        Reads a character, returns 0 if there are no more characters in the
+        stream.

     */
     wxChar GetChar();
 
     /**
         Reads a unsigned 16 bit integer from the stream.
     */
     wxChar GetChar();
 
     /**
         Reads a unsigned 16 bit integer from the stream.

-        See wxTextInputStream::Read8 for the
-        description of the @a base parameter.
+
+        See Read8() for the description of the @a base parameter.

     */
     wxUint16 Read16(int base = 10);
 
     /**
         Reads a signed 16 bit integer from the stream.
     */
     wxUint16 Read16(int base = 10);
 
     /**
         Reads a signed 16 bit integer from the stream.

-        See wxTextInputStream::Read8 for the
-        description of the @a base parameter.
+
+        See Read8() for the description of the @a base parameter.

     */
     wxInt16 Read16S(int base = 10);
 
     /**
         Reads a 32 bit unsigned integer from the stream.
     */
     wxInt16 Read16S(int base = 10);
 
     /**
         Reads a 32 bit unsigned integer from the stream.

-        See wxTextInputStream::Read8 for the
-        description of the @a base parameter.
+
+        See Read8() for the description of the @a base parameter.

     */
     wxUint32 Read32(int base = 10);
 
     /**
         Reads a 32 bit signed integer from the stream.
     */
     wxUint32 Read32(int base = 10);
 
     /**
         Reads a 32 bit signed integer from the stream.

-        See wxTextInputStream::Read8 for the
-        description of the @a base parameter.
+
+        See Read8() for the description of the @a base parameter.

     */
     wxInt32 Read32S(int base = 10);
 
     /**
     */
     wxInt32 Read32S(int base = 10);
 
     /**

-        Reads a single unsigned byte from the stream, given in base @e base.
+        Reads a single unsigned byte from the stream, given in base @a base.
+

         The value of @a base must be comprised between 2 and 36, inclusive, or
         The value of @a base must be comprised between 2 and 36, inclusive, or

-        be a special value 0 which means that the usual rules of @c C numbers are
+        be a special value 0 which means that the usual rules of C numbers are

         applied: if the number starts with @c 0x it is considered to be in base
         applied: if the number starts with @c 0x it is considered to be in base

-        16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note
-        that you may not want to specify the base 0 if you are parsing the numbers
-        which may have leading zeroes as they can yield unexpected (to the user not
-        familiar with C) results.
+        16, if it starts with 0 - in base 8 and in base 10 otherwise. Note that
+        you may not want to specify the base 0 if you are parsing the numbers
+        which may have leading zeroes as they can yield unexpected (to the user
+        not familiar with C) results.

     */
     wxUint8 Read8(int base = 10);
 
     /**
         Reads a single signed byte from the stream.
     */
     wxUint8 Read8(int base = 10);
 
     /**
         Reads a single signed byte from the stream.

-        See wxTextInputStream::Read8 for the
-        description of the @a base parameter.
+
+        See Read8() for the description of the @a base parameter.

     */
     wxInt8 Read8S(int base = 10);
 
     */
     wxInt8 Read8S(int base = 10);
 


@@ -134,21 +135,21 @@ public:
     double ReadDouble();
 
     /**
     double ReadDouble();
 
     /**

-        Reads a line from the input stream and returns it (without the end of line
-        character).
+        Reads a line from the input stream and returns it (without the end of
+        line character).

     */
     wxString ReadLine();
 
     /**
     */
     wxString ReadLine();
 
     /**

-        @b NB: This method is deprecated, use ReadLine()
-        or ReadWord() instead.
+        @deprecated Use ReadLine() or ReadWord() instead.
+

         Same as ReadLine().
     */
     wxString ReadString();
 
     /**
         Same as ReadLine().
     */
     wxString ReadString();
 
     /**

-        Reads a word (a sequence of characters until the next separator) from the
-        input stream.
+        Reads a word (a sequence of characters until the next separator) from
+        the input stream.

 
         @see SetStringSeparators()
     */
 
         @see SetStringSeparators()
     */


@@ -157,64 +158,106 @@ public:
     /**
         Sets the characters which are used to define the word boundaries in
         ReadWord().
     /**
         Sets the characters which are used to define the word boundaries in
         ReadWord().

-        The default separators are the space and @c TAB characters.
+
+        The default separators are the @c space and @c TAB characters.

     */
     void SetStringSeparators(const wxString& sep);
 };
 
 
     */
     void SetStringSeparators(const wxString& sep);
 };
 
 

+/**
+    Specifies the end-of-line characters to use with wxTextOutputStream.
+*/
+typedef enum
+{
+    /**
+        Specifies wxTextOutputStream to use the native end-of-line characters.
+    */
+    wxEOL_NATIVE,
+
+    /**
+        Specifies wxTextOutputStream to use Unix end-of-line characters.
+    */
+    wxEOL_UNIX,
+
+    /**
+        Specifies wxTextOutputStream to use Mac end-of-line characters.
+    */
+    wxEOL_MAC,
+
+    /**
+        Specifies wxTextOutputStream to use DOS end-of-line characters.
+    */
+    wxEOL_DOS
+} wxEOL;
+

 
 /**
     @class wxTextOutputStream
     @wxheader{txtstrm.h}
 
 
 /**
     @class wxTextOutputStream
     @wxheader{txtstrm.h}
 

-    This class provides functions that write text datas using an output stream.
-    So, you can write @e text floats, integers.
+    This class provides functions that write text data using an output stream,
+    allowing you to write text, floats, and integers.

 
 

-    You can also simulate the C++ cout class:
+    You can also simulate the C++ @c std::cout class:

 
     @code
     wxFFileOutputStream output( stderr );
 
     @code
     wxFFileOutputStream output( stderr );

-      wxTextOutputStream cout( output );
+    wxTextOutputStream cout( output );

 
 

-      cout  "This is a text line"  endl;
-      cout  1234;
-      cout  1.23456;
+    cout << "This is a text line" << endl;
+    cout << 1234;
+    cout << 1.23456;

     @endcode
 
     @endcode
 

-    The wxTextOutputStream writes text files (or streams) on DOS, Macintosh
-    and Unix in their native formats (concerning the line ending).
+    The wxTextOutputStream writes text files (or streams) on DOS, Macintosh and
+    Unix in their native formats (concerning the line ending).

 
     @library{wxbase}
     @category{streams}
 
     @library{wxbase}
     @category{streams}

+
+    @see wxTextInputStream

 */
 class wxTextOutputStream
 {
 public:
     /**
 */
 class wxTextOutputStream
 {
 public:
     /**

-        )

         Constructs a text stream object associated to the given output stream.
 
         @param stream
             The output stream.
         @param mode
         Constructs a text stream object associated to the given output stream.
 
         @param stream
             The output stream.
         @param mode

-            The end-of-line mode. One of wxEOL_NATIVE, wxEOL_DOS, wxEOL_MAC and
-        wxEOL_UNIX.
+            The end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS,
+            ::wxEOL_MAC and ::wxEOL_UNIX.

         @param conv
         @param conv

-            In Unicode build only: The object used to convert
+            <b>In Unicode build only:</b> The object used to convert

             Unicode text into ASCII characters written to the output stream.
     */
     wxTextOutputStream(wxOutputStream& stream,
             Unicode text into ASCII characters written to the output stream.
     */
     wxTextOutputStream(wxOutputStream& stream,

-                       wxEOL mode = wxEOL_NATIVE);
+                       wxEOL mode = wxEOL_NATIVE,
+                       const wxMBConv& conv = wxConvAuto());

 
     /**
         Destroys the wxTextOutputStream object.
 
     /**
         Destroys the wxTextOutputStream object.

+
+        Also calls Flush().

     */
     ~wxTextOutputStream();
 
     /**
     */
     ~wxTextOutputStream();
 
     /**

-        Returns the end-of-line mode. One of @b wxEOL_DOS, @b wxEOL_MAC and @b
-        wxEOL_UNIX.
+        Flushes the stream.
+
+        This method should be called when using stateful encodings (currently
+        the only example of such encoding in wxWidgets is wxMBConvUTF7) to
+        write the end of the encoded data to the stream.
+
+        @since 2.9.0
+     */
+    void Flush();
+
+    /**
+        Returns the end-of-line mode. One of ::wxEOL_DOS, ::wxEOL_MAC and
+        ::wxEOL_UNIX.

     */
     wxEOL GetMode();
 
     */
     wxEOL GetMode();
 


@@ -224,8 +267,8 @@ public:
     void PutChar(wxChar c);
 
     /**
     void PutChar(wxChar c);
 
     /**

-        Set the end-of-line mode. One of @b wxEOL_NATIVE, @b wxEOL_DOS, @b wxEOL_MAC
-        and @b wxEOL_UNIX.
+        Set the end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS,
+        ::wxEOL_MAC and ::wxEOL_UNIX.

     */
     void SetMode(wxEOL mode = wxEOL_NATIVE);
 
     */
     void SetMode(wxEOL mode = wxEOL_NATIVE);
 


@@ -251,8 +294,8 @@ public:
 
     /**
         Writes @a string as a line. Depending on the end-of-line mode the end of
 
     /**
         Writes @a string as a line. Depending on the end-of-line mode the end of

-        line ('\n') characters in the string are converted to the correct
-        line ending terminator.
+        line ('\\n') characters in the string are converted to the correct line
+        ending terminator.

     */
     virtual void WriteString(const wxString& string);
 };
     */
     virtual void WriteString(const wxString& string);
 };