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 \wxheading{Library}
  43
  44 \helpref{wxBase}{librarieslist}
  45
  46 \latexignore{\rtfignore{\wxheading{Members}}}
  47
  48
  49 \membersection{wxTextInputStream::wxTextInputStream}\label{wxtextinputstreamctor}
  50
  51 \func{}{wxTextInputStream}{\param{wxInputStream\&}{ stream}, \param{const wxString\&}{ sep=" $\backslash$t"},
  52   \param{const wxMBConv\&}{ conv = wxConvAuto()} }
  53
  54 Constructs a text stream associated to the given input stream.
  55
  56 \wxheading{Parameters}
  57
  58 \docparam{stream}{The underlying input stream.}
  59
  60 \docparam{sep}{The initial string separator characters.}
  61
  62 \docparam{conv}{{\it In Unicode build only:} The encoding converter used to convert the bytes in the
  63   underlying input stream to characters.}
  64
  65
  66 \membersection{wxTextInputStream::\destruct{wxTextInputStream}}\label{wxtextinputstreamdtor}
  67
  68 \func{}{\destruct{wxTextInputStream}}{\void}
  69
  70 Destroys the wxTextInputStream object.
  71
  72
  73 \membersection{wxTextInputStream::Read8}\label{wxtextinputstreamread8}
  74
  75 \func{wxUint8}{Read8}{\param{int}{ base = 10}}
  76
  77 Reads a single unsigned byte from the stream, given in base {\it base}.
  78
  79 The value of {\it base} must be comprised between $2$ and $36$, inclusive, or
  80 be a special value $0$ which means that the usual rules of {\tt C} numbers are
  81 applied: if the number starts with {\tt 0x} it is considered to be in base
  82 $16$, if it starts with {\tt 0} - in base $8$ and in base $10$ otherwise. Note
  83 that you may not want to specify the base $0$ if you are parsing the numbers
  84 which may have leading zeroes as they can yield unexpected (to the user not
  85 familiar with C) results.
  86
  87
  88 \membersection{wxTextInputStream::Read8S}\label{wxtextinputstreamread8s}
  89
  90 \func{wxInt8}{Read8S}{\param{int}{ base = 10}}
  91
  92 Reads a single signed byte from the stream.
  93
  94 See \helpref{wxTextInputStream::Read8}{wxtextinputstreamread8} for the
  95 description of the {\it base} parameter.
  96
  97
  98 \membersection{wxTextInputStream::Read16}\label{wxtextinputstreamread16}
  99
 100 \func{wxUint16}{Read16}{\param{int}{ base = 10}}
 101
 102 Reads a unsigned 16 bit integer from the stream.
 103
 104 See \helpref{wxTextInputStream::Read8}{wxtextinputstreamread8} for the
 105 description of the {\it base} parameter.
 106
 107
 108 \membersection{wxTextInputStream::Read16S}\label{wxtextinputstreamread16s}
 109
 110 \func{wxInt16}{Read16S}{\param{int}{ base = 10}}
 111
 112 Reads a signed 16 bit integer from the stream.
 113
 114 See \helpref{wxTextInputStream::Read8}{wxtextinputstreamread8} for the
 115 description of the {\it base} parameter.
 116
 117
 118 \membersection{wxTextInputStream::Read32}\label{wxtextinputstreamread32}
 119
 120 \func{wxUint32}{Read32}{\param{int}{ base = 10}}
 121
 122 Reads a 32 bit unsigned integer from the stream.
 123
 124 See \helpref{wxTextInputStream::Read8}{wxtextinputstreamread8} for the
 125 description of the {\it base} parameter.
 126
 127
 128 \membersection{wxTextInputStream::Read32S}\label{wxtextinputstreamread32s}
 129
 130 \func{wxInt32}{Read32S}{\param{int}{ base = 10}}
 131
 132 Reads a 32 bit signed integer from the stream.
 133
 134 See \helpref{wxTextInputStream::Read8}{wxtextinputstreamread8} for the
 135 description of the {\it base} parameter.
 136
 137
 138 \membersection{wxTextInputStream::GetChar}\label{wxtextinputstreamgetchar}
 139
 140 \func{wxChar}{GetChar}{\void}
 141
 142 Reads a character, returns $0$ if there are no more characters in the stream.
 143
 144
 145 \membersection{wxTextInputStream::ReadDouble}\label{wxtextinputstreamreaddouble}
 146
 147 \func{double}{ReadDouble}{\void}
 148
 149 Reads a double (IEEE encoded) from the stream.
 150
 151
 152 \membersection{wxTextInputStream::ReadLine}\label{wxtextinputstreamreadline}
 153
 154 \func{wxString}{ReadLine}{\void}
 155
 156 Reads a line from the input stream and returns it (without the end of line
 157 character).
 158
 159
 160 \membersection{wxTextInputStream::ReadString}\label{wxtextinputstreamreadstring}
 161
 162 \func{wxString}{ReadString}{\void}
 163
 164 {\bf NB:} This method is deprecated, use \helpref{ReadLine}{wxtextinputstreamreadline}
 165 or \helpref{ReadWord}{wxtextinputstreamreadword} instead.
 166
 167 Same as \helpref{ReadLine}{wxtextinputstreamreadline}.
 168
 169
 170 \membersection{wxTextInputStream::ReadWord}\label{wxtextinputstreamreadword}
 171
 172 \func{wxString}{ReadWord}{\void}
 173
 174 Reads a word (a sequence of characters until the next separator) from the
 175 input stream.
 176
 177 \wxheading{See also}
 178
 179 \helpref{SetStringSeparators}{wxtextinputstreamsetstringseparators}
 180
 181
 182 \membersection{wxTextInputStream::SetStringSeparators}\label{wxtextinputstreamsetstringseparators}
 183
 184 \func{void}{SetStringSeparators}{\param{const wxString\& }{sep}}
 185
 186 Sets the characters which are used to define the word boundaries in
 187 \helpref{ReadWord}{wxtextinputstreamreadword}.
 188
 189 The default separators are the space and {\tt TAB} characters.
 190
 191 % ----------------------------------------------------------------------------
 192 % wxTextOutputStream
 193 % ----------------------------------------------------------------------------
 194
 195 \section{\class{wxTextOutputStream}}\label{wxtextoutputstream}
 196
 197 This class provides functions that write text datas using an output stream.
 198 So, you can write {\it text} floats, integers.
 199
 200 You can also simulate the C++ cout class:
 201
 202 \begin{verbatim}
 203   wxFFileOutputStream output( stderr );
 204   wxTextOutputStream cout( output );
 205
 206   cout << "This is a text line" << endl;
 207   cout << 1234;
 208   cout << 1.23456;
 209 \end{verbatim}
 210
 211 The wxTextOutputStream writes text files (or streams) on DOS, Macintosh
 212 and Unix in their native formats (concerning the line ending).
 213
 214 \wxheading{Include files}
 215
 216 <wx/txtstrm.h>
 217
 218 \wxheading{Library}
 219
 220 \helpref{wxBase}{librarieslist}
 221
 222 \latexignore{\rtfignore{\wxheading{Members}}}
 223
 224
 225 \membersection{wxTextOutputStream::wxTextOutputStream}\label{wxtextoutputstreamctor}
 226
 227 \func{}{wxTextOutputStream}{\param{wxOutputStream\&}{ stream}, \param{wxEOL}{ mode = wxEOL\_NATIVE}, \param{const wxMBConv\&}{ conv = wxConvAuto()}}
 228
 229 Constructs a text stream object associated to the given output stream.
 230
 231 \wxheading{Parameters}
 232
 233 \docparam{stream}{The output stream.}
 234
 235 \docparam{mode}{The end-of-line mode. One of {\bf wxEOL\_NATIVE}, {\bf wxEOL\_DOS}, {\bf wxEOL\_MAC} and {\bf wxEOL\_UNIX}.}
 236
 237 \docparam{conv}{{\it In Unicode build only:} The object used to convert
 238 Unicode text into ASCII characters written to the output stream.}
 239
 240
 241 \membersection{wxTextOutputStream::\destruct{wxTextOutputStream}}\label{wxtextoutputstreamdtor}
 242
 243 \func{}{\destruct{wxTextOutputStream}}{\void}
 244
 245 Destroys the wxTextOutputStream object.
 246
 247
 248 \membersection{wxTextOutputStream::GetMode}\label{wxtextoutputstreamgetmode}
 249
 250 \func{wxEOL}{GetMode}{\void}
 251
 252 Returns the end-of-line mode. One of {\bf wxEOL\_DOS}, {\bf wxEOL\_MAC} and {\bf wxEOL\_UNIX}.
 253
 254
 255 \membersection{wxTextOutputStream::PutChar}\label{wxtextoutputstreamputchar}
 256
 257 \func{void}{PutChar}{{\param wxChar }{c}}
 258
 259 Writes a character to the stream.
 260
 261
 262 \membersection{wxTextOutputStream::SetMode}\label{wxtextoutputstreamsetmode}
 263
 264 \func{void}{SetMode}{{\param wxEOL}{ mode = wxEOL\_NATIVE}}
 265
 266 Set the end-of-line mode. One of {\bf wxEOL\_NATIVE}, {\bf wxEOL\_DOS}, {\bf wxEOL\_MAC} and {\bf wxEOL\_UNIX}.
 267
 268
 269 \membersection{wxTextOutputStream::Write8}\label{wxtextoutputstreamwrite8}
 270
 271 \func{void}{Write8}{{\param wxUint8 }{i8}}
 272
 273 Writes the single byte {\it i8} to the stream.
 274
 275
 276 \membersection{wxTextOutputStream::Write16}\label{wxtextoutputstreamwrite16}
 277
 278 \func{void}{Write16}{{\param wxUint16 }{i16}}
 279
 280 Writes the 16 bit integer {\it i16} to the stream.
 281
 282
 283 \membersection{wxTextOutputStream::Write32}\label{wxtextoutputstreamwrite32}
 284
 285 \func{void}{Write32}{{\param wxUint32 }{i32}}
 286
 287 Writes the 32 bit integer {\it i32} to the stream.
 288
 289
 290 \membersection{wxTextOutputStream::WriteDouble}\label{wxtextoutputstreamwritedouble}
 291
 292 \func{virtual void}{WriteDouble}{{\param double }{f}}
 293
 294 Writes the double {\it f} to the stream using the IEEE format.
 295
 296
 297 \membersection{wxTextOutputStream::WriteString}\label{wxtextoutputstreamwritestring}
 298
 299 \func{virtual void}{WriteString}{{\param const wxString\& }{string}}
 300
 301 Writes {\it string} as a line. Depending on the end-of-line mode the end of
 302 line ('$\backslash$n') characters in the string are converted to the correct
 303 line ending terminator.
 304