interface/wx/txtstrm.h

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