interface/wx/txtstrm.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        txtstrm.h
   3 // Purpose:     interface of wxTextInputStream
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10
  11 /**
  12     @class wxTextInputStream
  13
  14     This class provides functions that reads text data using an input stream,
  15     allowing you to read text, floats, and integers.
  16
  17     The wxTextInputStream correctly reads text files (or streams) in DOS,
  18     Macintosh and Unix formats and reports a single newline char as a line
  19     ending.
  20
  21     wxTextInputStream::operator>>() is overloaded and you can use this class
  22     like a standard C++ iostream. Note, however, that the arguments are the
  23     fixed size types wxUint32, wxInt32 etc and on a typical 32-bit computer,
  24     none of these match to the "long" type (wxInt32 is defined as int on 32-bit
  25     architectures) so that you cannot use long. To avoid problems (here and
  26     elsewhere), make use of wxInt32, wxUint32 and similar types.
  27
  28     If you're scanning through a file using wxTextInputStream, you should check
  29     for @c EOF @b before reading the next item (word / number), because
  30     otherwise the last item may get lost. You should however be prepared to
  31     receive an empty item (empty string / zero number) at the end of file,
  32     especially on Windows systems. This is unavoidable because most (but not
  33     all) files end with whitespace (i.e. usually a newline).
  34
  35     For example:
  36
  37     @code
  38     wxFileInputStream input( "mytext.txt" );
  39     wxTextInputStream text( input );
  40     wxUint8 i1;
  41     float f2;
  42     wxString line;
  43
  44     text >> i1;       // read a 8 bit integer.
  45     text >> i1 >> f2; // read a 8 bit integer followed by float.
  46     text >> line;     // read a text line
  47     @endcode
  48
  49     @library{wxbase}
  50     @category{streams}
  51
  52     @see wxTextOutputStream
  53 */
  54 class wxTextInputStream
  55 {
  56 public:
  57     /**
  58         Constructs a text stream associated to the given input stream.
  59
  60         @param stream
  61             The underlying input stream.
  62         @param sep
  63             The initial string separator characters.
  64         @param conv
  65             <b>In Unicode build only:</b> The encoding converter used to
  66             convert the bytes in the underlying input stream to characters.
  67     */
  68     wxTextInputStream(wxInputStream& stream,
  69                       const wxString& sep = " \t",
  70                       const wxMBConv& conv = wxConvAuto());
  71
  72     /**
  73         Destructor.
  74     */
  75     ~wxTextInputStream();
  76
  77     /**
  78         Reads a character, returns 0 if there are no more characters in the
  79         stream.
  80     */
  81     wxChar GetChar();
  82
  83     /**
  84         Reads a unsigned 16 bit integer from the stream.
  85
  86         See Read8() for the description of the @a base parameter.
  87     */
  88     wxUint16 Read16(int base = 10);
  89
  90     /**
  91         Reads a signed 16 bit integer from the stream.
  92
  93         See Read8() for the description of the @a base parameter.
  94     */
  95     wxInt16 Read16S(int base = 10);
  96
  97     /**
  98         Reads a 32 bit unsigned integer from the stream.
  99
 100         See Read8() for the description of the @a base parameter.
 101     */
 102     wxUint32 Read32(int base = 10);
 103
 104     /**
 105         Reads a 32 bit signed integer from the stream.
 106
 107         See Read8() for the description of the @a base parameter.
 108     */
 109     wxInt32 Read32S(int base = 10);
 110
 111     /**
 112         Reads a single unsigned byte from the stream, given in base @a base.
 113
 114         The value of @a base must be comprised between 2 and 36, inclusive, or
 115         be a special value 0 which means that the usual rules of C numbers are
 116         applied: if the number starts with @c 0x it is considered to be in base
 117         16, if it starts with 0 - in base 8 and in base 10 otherwise. Note that
 118         you may not want to specify the base 0 if you are parsing the numbers
 119         which may have leading zeroes as they can yield unexpected (to the user
 120         not familiar with C) results.
 121     */
 122     wxUint8 Read8(int base = 10);
 123
 124     /**
 125         Reads a single signed byte from the stream.
 126
 127         See Read8() for the description of the @a base parameter.
 128     */
 129     wxInt8 Read8S(int base = 10);
 130
 131     /**
 132         Reads a double (IEEE encoded) from the stream.
 133     */
 134     double ReadDouble();
 135
 136     /**
 137         Reads a line from the input stream and returns it (without the end of
 138         line character).
 139     */
 140     wxString ReadLine();
 141
 142     /**
 143         @deprecated Use ReadLine() or ReadWord() instead.
 144
 145         Same as ReadLine().
 146     */
 147     wxString ReadString();
 148
 149     /**
 150         Reads a word (a sequence of characters until the next separator) from
 151         the input stream.
 152
 153         @see SetStringSeparators()
 154     */
 155     wxString ReadWord();
 156
 157     /**
 158         Sets the characters which are used to define the word boundaries in
 159         ReadWord().
 160
 161         The default separators are the @c space and @c TAB characters.
 162     */
 163     void SetStringSeparators(const wxString& sep);
 164 };
 165
 166
 167 /**
 168     Specifies the end-of-line characters to use with wxTextOutputStream.
 169 */
 170 typedef enum
 171 {
 172     /**
 173         Specifies wxTextOutputStream to use the native end-of-line characters.
 174     */
 175     wxEOL_NATIVE,
 176
 177     /**
 178         Specifies wxTextOutputStream to use Unix end-of-line characters.
 179     */
 180     wxEOL_UNIX,
 181
 182     /**
 183         Specifies wxTextOutputStream to use Mac end-of-line characters.
 184     */
 185     wxEOL_MAC,
 186
 187     /**
 188         Specifies wxTextOutputStream to use DOS end-of-line characters.
 189     */
 190     wxEOL_DOS
 191 } wxEOL;
 192
 193
 194 /**
 195     @class wxTextOutputStream
 196
 197     This class provides functions that write text data using an output stream,
 198     allowing you to write text, floats, and integers.
 199
 200     You can also simulate the C++ @c std::cout class:
 201
 202     @code
 203     wxFFileOutputStream output( stderr );
 204     wxTextOutputStream cout( output );
 205
 206     cout << "This is a text line" << endl;
 207     cout << 1234;
 208     cout << 1.23456;
 209     @endcode
 210
 211     The wxTextOutputStream writes text files (or streams) on DOS, Macintosh and
 212     Unix in their native formats (concerning the line ending).
 213
 214     @library{wxbase}
 215     @category{streams}
 216
 217     @see wxTextInputStream
 218 */
 219 class wxTextOutputStream
 220 {
 221 public:
 222     /**
 223         Constructs a text stream object associated to the given output stream.
 224
 225         @param stream
 226             The output stream.
 227         @param mode
 228             The end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS,
 229             ::wxEOL_MAC and ::wxEOL_UNIX.
 230         @param conv
 231             <b>In Unicode build only:</b> The object used to convert
 232             Unicode text into ASCII characters written to the output stream.
 233     */
 234     wxTextOutputStream(wxOutputStream& stream,
 235                        wxEOL mode = wxEOL_NATIVE,
 236                        const wxMBConv& conv = wxConvAuto());
 237
 238     /**
 239         Destroys the wxTextOutputStream object.
 240
 241         Also calls Flush().
 242     */
 243     virtual ~wxTextOutputStream();
 244
 245     /**
 246         Flushes the stream.
 247
 248         This method should be called when using stateful encodings (currently
 249         the only example of such encoding in wxWidgets is wxMBConvUTF7) to
 250         write the end of the encoded data to the stream.
 251
 252         @since 2.9.0
 253      */
 254     void Flush();
 255
 256     /**
 257         Returns the end-of-line mode. One of ::wxEOL_DOS, ::wxEOL_MAC and
 258         ::wxEOL_UNIX.
 259     */
 260     wxEOL GetMode();
 261
 262     /**
 263         Writes a character to the stream.
 264     */
 265     void PutChar(wxChar c);
 266
 267     /**
 268         Set the end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS,
 269         ::wxEOL_MAC and ::wxEOL_UNIX.
 270     */
 271     void SetMode(wxEOL mode = wxEOL_NATIVE);
 272
 273     /**
 274         Writes the 16 bit integer @a i16 to the stream.
 275     */
 276     void Write16(wxUint16 i16);
 277
 278     /**
 279         Writes the 32 bit integer @a i32 to the stream.
 280     */
 281     void Write32(wxUint32 i32);
 282
 283     /**
 284         Writes the single byte @a i8 to the stream.
 285     */
 286     void Write8(wxUint8 i8);
 287
 288     /**
 289         Writes the double @a f to the stream using the IEEE format.
 290     */
 291     virtual void WriteDouble(double f);
 292
 293     /**
 294         Writes @a string as a line. Depending on the end-of-line mode the end of
 295         line ('\\n') characters in the string are converted to the correct line
 296         ending terminator.
 297     */
 298     virtual void WriteString(const wxString& string);
 299 };
 300