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