interface/txtstrm.h

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