docs/latex/wx/txtstrm.tex

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