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