interface/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     @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     @see wxTextInputStream::SetStringSeparators
  54 */
  55 class wxTextInputStream
  56 {
  57 public:
  58     /**
  59         )
  60         Constructs a text stream associated to the given input stream.
  61
  62         @param stream
  63             The underlying input stream.
  64         @param sep
  65             The initial string separator characters.
  66         @param conv
  67             In Unicode build only: The encoding converter used to convert the bytes in
  68         the
  69               underlying input stream to characters.
  70     */
  71     wxTextInputStream(wxInputStream& stream,
  72                       const wxString& sep = " \t");
  73
  74     /**
  75         Destroys the wxTextInputStream object.
  76     */
  77     ~wxTextInputStream();
  78
  79     /**
  80         Reads a character, returns 0 if there are no more characters in the stream.
  81     */
  82     wxChar GetChar();
  83
  84     /**
  85         Reads a unsigned 16 bit integer from the stream.
  86         See wxTextInputStream::Read8 for the
  87         description of the @a base parameter.
  88     */
  89     wxUint16 Read16(int base = 10);
  90
  91     /**
  92         Reads a signed 16 bit integer from the stream.
  93         See wxTextInputStream::Read8 for the
  94         description of the @a base parameter.
  95     */
  96     wxInt16 Read16S(int base = 10);
  97
  98     /**
  99         Reads a 32 bit unsigned integer from the stream.
 100         See wxTextInputStream::Read8 for the
 101         description of the @a base parameter.
 102     */
 103     wxUint32 Read32(int base = 10);
 104
 105     /**
 106         Reads a 32 bit signed integer from the stream.
 107         See wxTextInputStream::Read8 for the
 108         description of the @a base parameter.
 109     */
 110     wxInt32 Read32S(int base = 10);
 111
 112     /**
 113         Reads a single unsigned byte from the stream, given in base @e base.
 114         The value of @a base must be comprised between 2 and 36, inclusive, or
 115         be a special value 0 which means that the usual rules of @c C numbers are
 116         applied: if the number starts with @c 0x it is considered to be in base
 117         16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note
 118         that you may not want to specify the base 0 if you are parsing the numbers
 119         which may have leading zeroes as they can yield unexpected (to the user not
 120         familiar with C) results.
 121     */
 122     wxUint8 Read8(int base = 10);
 123
 124     /**
 125         Reads a single signed byte from the stream.
 126         See wxTextInputStream::Read8 for the
 127         description of the @a base parameter.
 128     */
 129     wxInt8 Read8S(int base = 10);
 130
 131     /**
 132         Reads a double (IEEE encoded) from the stream.
 133     */
 134     double ReadDouble();
 135
 136     /**
 137         Reads a line from the input stream and returns it (without the end of line
 138         character).
 139     */
 140     wxString ReadLine();
 141
 142     /**
 143         @b NB: This method is deprecated, use ReadLine()
 144         or ReadWord() instead.
 145         Same as ReadLine().
 146     */
 147     wxString ReadString();
 148
 149     /**
 150         Reads a word (a sequence of characters until the next separator) from the
 151         input stream.
 152
 153         @see SetStringSeparators()
 154     */
 155     wxString ReadWord();
 156
 157     /**
 158         Sets the characters which are used to define the word boundaries in
 159         ReadWord().
 160         The default separators are the space and @c TAB characters.
 161     */
 162     void SetStringSeparators(const wxString& sep);
 163 };
 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 };
 259