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         Constructs a text stream associated to the given input stream.
  62
  63         @param stream
  64             The underlying input stream.
  65         @param sep
  66             The initial string separator characters.
  67         @param conv
  68             In Unicode build only: The encoding converter used to convert the bytes in
  69         the
  70               underlying input stream to characters.
  71     */
  72     wxTextInputStream(wxInputStream& stream,
  73                       const wxString& sep = " \t");
  74
  75     /**
  76         Destroys the wxTextInputStream object.
  77     */
  78     ~wxTextInputStream();
  79
  80     /**
  81         Reads a character, returns 0 if there are no more characters in the stream.
  82     */
  83     wxChar GetChar();
  84
  85     /**
  86         Reads a unsigned 16 bit integer from the stream.
  87         See wxTextInputStream::Read8 for the
  88         description of the @a base parameter.
  89     */
  90     wxUint16 Read16(int base = 10);
  91
  92     /**
  93         Reads a signed 16 bit integer from the stream.
  94         See wxTextInputStream::Read8 for the
  95         description of the @a base parameter.
  96     */
  97     wxInt16 Read16S(int base = 10);
  98
  99     /**
 100         Reads a 32 bit unsigned integer from the stream.
 101         See wxTextInputStream::Read8 for the
 102         description of the @a base parameter.
 103     */
 104     wxUint32 Read32(int base = 10);
 105
 106     /**
 107         Reads a 32 bit signed integer from the stream.
 108         See wxTextInputStream::Read8 for the
 109         description of the @a base parameter.
 110     */
 111     wxInt32 Read32S(int base = 10);
 112
 113     /**
 114         Reads a single unsigned byte from the stream, given in base @e base.
 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 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 @c 0 - in base 8 and in base 10 otherwise. Note
 119         that 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 not
 121         familiar with C) results.
 122     */
 123     wxUint8 Read8(int base = 10);
 124
 125     /**
 126         Reads a single signed byte from the stream.
 127         See wxTextInputStream::Read8 for the
 128         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 line
 139         character).
 140     */
 141     wxString ReadLine();
 142
 143     /**
 144         @b NB: This method is deprecated, use ReadLine()
 145         or ReadWord() instead.
 146         Same as ReadLine().
 147     */
 148     wxString ReadString();
 149
 150     /**
 151         Reads a word (a sequence of characters until the next separator) from the
 152         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         The default separators are the space and @c TAB characters.
 162     */
 163     void SetStringSeparators(const wxString& sep);
 164 };
 165
 166
 167 /**
 168     @class wxTextOutputStream
 169     @wxheader{txtstrm.h}
 170
 171     This class provides functions that write text datas using an output stream.
 172     So, you can write @e text floats, integers.
 173
 174     You can also simulate the C++ cout class:
 175
 176     @code
 177     wxFFileOutputStream output( stderr );
 178       wxTextOutputStream cout( output );
 179
 180       cout  "This is a text line"  endl;
 181       cout  1234;
 182       cout  1.23456;
 183     @endcode
 184
 185     The wxTextOutputStream writes text files (or streams) on DOS, Macintosh
 186     and Unix in their native formats (concerning the line ending).
 187
 188     @library{wxbase}
 189     @category{streams}
 190 */
 191 class wxTextOutputStream
 192 {
 193 public:
 194     /**
 195         )
 196         Constructs a text stream object associated to the given output stream.
 197
 198         @param stream
 199             The output stream.
 200         @param mode
 201             The end-of-line mode. One of wxEOL_NATIVE, wxEOL_DOS, wxEOL_MAC and
 202         wxEOL_UNIX.
 203         @param conv
 204             In Unicode build only: The object used to convert
 205             Unicode text into ASCII characters written to the output stream.
 206     */
 207     wxTextOutputStream(wxOutputStream& stream,
 208                        wxEOL mode = wxEOL_NATIVE);
 209
 210     /**
 211         Destroys the wxTextOutputStream object.
 212     */
 213     ~wxTextOutputStream();
 214
 215     /**
 216         Returns the end-of-line mode. One of @b wxEOL_DOS, @b wxEOL_MAC and @b
 217         wxEOL_UNIX.
 218     */
 219     wxEOL GetMode();
 220
 221     /**
 222         Writes a character to the stream.
 223     */
 224     void PutChar(wxChar c);
 225
 226     /**
 227         Set the end-of-line mode. One of @b wxEOL_NATIVE, @b wxEOL_DOS, @b wxEOL_MAC
 228         and @b wxEOL_UNIX.
 229     */
 230     void SetMode(wxEOL mode = wxEOL_NATIVE);
 231
 232     /**
 233         Writes the 16 bit integer @a i16 to the stream.
 234     */
 235     void Write16(wxUint16 i16);
 236
 237     /**
 238         Writes the 32 bit integer @a i32 to the stream.
 239     */
 240     void Write32(wxUint32 i32);
 241
 242     /**
 243         Writes the single byte @a i8 to the stream.
 244     */
 245     void Write8(wxUint8 i8);
 246
 247     /**
 248         Writes the double @a f to the stream using the IEEE format.
 249     */
 250     virtual void WriteDouble(double f);
 251
 252     /**
 253         Writes @a string as a line. Depending on the end-of-line mode the end of
 254         line ('\n') characters in the string are converted to the correct
 255         line ending terminator.
 256     */
 257     virtual void WriteString(const wxString& string);
 258 };