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