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 licence
   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, const wxString& sep = " \t",
  69                       const wxMBConv& conv = wxConvAuto());
  70
  71     /**
  72         Destructor.
  73     */
  74     ~wxTextInputStream();
  75
  76     /**
  77         Returns a pointer to the underlying input stream object.
  78
  79         @since 2.9.2
  80     */
  81     const wxInputStream& GetInputStream() const;
  82
  83     /**
  84         Reads a character, returns 0 if there are no more characters in the
  85         stream.
  86     */
  87     wxChar GetChar();
  88
  89     /**
  90         Reads a unsigned 16 bit integer from the stream.
  91
  92         See Read8() for the description of the @a base parameter.
  93     */
  94     wxUint16 Read16(int base = 10);
  95
  96     /**
  97         Reads a signed 16 bit integer from the stream.
  98
  99         See Read8() for the description of the @a base parameter.
 100     */
 101     wxInt16 Read16S(int base = 10);
 102
 103     /**
 104         Reads a 32 bit unsigned integer from the stream.
 105
 106         See Read8() for the description of the @a base parameter.
 107     */
 108     wxUint32 Read32(int base = 10);
 109
 110     /**
 111         Reads a 32 bit signed integer from the stream.
 112
 113         See Read8() for the description of the @a base parameter.
 114     */
 115     wxInt32 Read32S(int base = 10);
 116
 117     /**
 118         Reads a single unsigned byte from the stream, given in base @a base.
 119
 120         The value of @a base must be comprised between 2 and 36, inclusive, or
 121         be a special value 0 which means that the usual rules of C numbers are
 122         applied: if the number starts with @c 0x it is considered to be in base
 123         16, if it starts with 0 - in base 8 and in base 10 otherwise. Note that
 124         you may not want to specify the base 0 if you are parsing the numbers
 125         which may have leading zeroes as they can yield unexpected (to the user
 126         not familiar with C) results.
 127     */
 128     wxUint8 Read8(int base = 10);
 129
 130     /**
 131         Reads a single signed byte from the stream.
 132
 133         See Read8() for the description of the @a base parameter.
 134     */
 135     wxInt8 Read8S(int base = 10);
 136
 137     /**
 138         Reads a double (IEEE encoded) from the stream.
 139     */
 140     double ReadDouble();
 141
 142     /**
 143         Reads a line from the input stream and returns it (without the end of
 144         line character).
 145     */
 146     wxString ReadLine();
 147
 148     /**
 149         @deprecated Use ReadLine() or ReadWord() instead.
 150
 151         Same as ReadLine().
 152     */
 153     wxString ReadString();
 154
 155     /**
 156         Reads a word (a sequence of characters until the next separator) from
 157         the input stream.
 158
 159         @see SetStringSeparators()
 160     */
 161     wxString ReadWord();
 162
 163     /**
 164         Sets the characters which are used to define the word boundaries in
 165         ReadWord().
 166
 167         The default separators are the @c space and @c TAB characters.
 168     */
 169     void SetStringSeparators(const wxString& sep);
 170 };
 171
 172
 173 /**
 174     Specifies the end-of-line characters to use with wxTextOutputStream.
 175 */
 176 typedef enum
 177 {
 178     /**
 179         Specifies wxTextOutputStream to use the native end-of-line characters.
 180     */
 181     wxEOL_NATIVE,
 182
 183     /**
 184         Specifies wxTextOutputStream to use Unix end-of-line characters.
 185     */
 186     wxEOL_UNIX,
 187
 188     /**
 189         Specifies wxTextOutputStream to use Mac end-of-line characters.
 190     */
 191     wxEOL_MAC,
 192
 193     /**
 194         Specifies wxTextOutputStream to use DOS end-of-line characters.
 195     */
 196     wxEOL_DOS
 197 } wxEOL;
 198
 199
 200 /**
 201     @class wxTextOutputStream
 202
 203     This class provides functions that write text data using an output stream,
 204     allowing you to write text, floats, and integers.
 205
 206     You can also simulate the C++ @c std::cout class:
 207
 208     @code
 209     wxFFileOutputStream output( stderr );
 210     wxTextOutputStream cout( output );
 211
 212     cout << "This is a text line" << endl;
 213     cout << 1234;
 214     cout << 1.23456;
 215     @endcode
 216
 217     The wxTextOutputStream writes text files (or streams) on DOS, Macintosh and
 218     Unix in their native formats (concerning the line ending).
 219
 220     @library{wxbase}
 221     @category{streams}
 222
 223     @see wxTextInputStream
 224 */
 225 class wxTextOutputStream
 226 {
 227 public:
 228     /**
 229         Constructs a text stream object associated to the given output stream.
 230
 231         @param stream
 232             The output stream.
 233         @param mode
 234             The end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS,
 235             ::wxEOL_MAC and ::wxEOL_UNIX.
 236         @param conv
 237             <b>In Unicode build only:</b> The object used to convert
 238             Unicode text into ASCII characters written to the output stream.
 239     */
 240     wxTextOutputStream(wxOutputStream& stream,
 241                        wxEOL mode = wxEOL_NATIVE,
 242                        const wxMBConv& conv = wxConvAuto());
 243
 244     /**
 245         Destroys the wxTextOutputStream object.
 246
 247         Also calls Flush().
 248     */
 249     virtual ~wxTextOutputStream();
 250
 251     /**
 252         Flushes the stream.
 253
 254         This method should be called when using stateful encodings (currently
 255         the only example of such encoding in wxWidgets is wxMBConvUTF7) to
 256         write the end of the encoded data to the stream.
 257
 258         @since 2.9.0
 259      */
 260     void Flush();
 261
 262     /**
 263         Returns a pointer to the underlying output stream object.
 264
 265         @since 2.9.2
 266     */
 267     const wxOutputStream& GetOutputStream() const;
 268
 269     /**
 270         Returns the end-of-line mode. One of ::wxEOL_DOS, ::wxEOL_MAC and
 271         ::wxEOL_UNIX.
 272     */
 273     wxEOL GetMode();
 274
 275     /**
 276         Writes a character to the stream.
 277     */
 278     wxTextOutputStream& PutChar(wxChar c);
 279
 280     /**
 281         Set the end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS,
 282         ::wxEOL_MAC and ::wxEOL_UNIX.
 283     */
 284     void SetMode(wxEOL mode = wxEOL_NATIVE);
 285
 286     /**
 287         Writes the 16 bit integer @a i16 to the stream.
 288     */
 289     void Write16(wxUint16 i16);
 290
 291     /**
 292         Writes the 32 bit integer @a i32 to the stream.
 293     */
 294     void Write32(wxUint32 i32);
 295
 296     /**
 297         Writes the single byte @a i8 to the stream.
 298     */
 299     void Write8(wxUint8 i8);
 300
 301     /**
 302         Writes the double @a f to the stream using the IEEE format.
 303     */
 304     virtual void WriteDouble(double f);
 305
 306     /**
 307         Writes @a string as a line. Depending on the end-of-line mode the end of
 308         line ('\\n') characters in the string are converted to the correct line
 309         ending terminator.
 310     */
 311     virtual void WriteString(const wxString& string);
 312 };
 313