]> git.saurik.com Git - wxWidgets.git/blame - interface/txtstrm.h
Patch from Utensil Candel with large improvements to the samples documentation, and...
[wxWidgets.git] / interface / txtstrm.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: txtstrm.h
e54c96f1 3// Purpose: interface of wxTextInputStream
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
7977b62a
BP
9
10
23324ae1
FM
11/**
12 @class wxTextInputStream
13 @wxheader{txtstrm.h}
7c913512 14
7977b62a
BP
15 This class provides functions that reads text data using an input stream,
16 allowing you to read text, floats, and integers.
17
18 The wxTextInputStream correctly reads text files (or streams) in DOS,
19 Macintosh and Unix formats and reports a single newline char as a line
20 ending.
21
22 wxTextInputStream::operator>>() is overloaded and you can use this class
23 like a standard C++ iostream. Note, however, that the arguments are the
24 fixed size types wxUint32, wxInt32 etc and on a typical 32-bit computer,
25 none of these match to the "long" type (wxInt32 is defined as int on 32-bit
26 architectures) so that you cannot use long. To avoid problems (here and
27 elsewhere), make use of wxInt32, wxUint32 and similar types.
28
29 If you're scanning through a file using wxTextInputStream, you should check
30 for @c EOF @b before reading the next item (word / number), because
31 otherwise the last item may get lost. You should however be prepared to
32 receive an empty item (empty string / zero number) at the end of file,
33 especially on Windows systems. This is unavoidable because most (but not
34 all) files end with whitespace (i.e. usually a newline).
7c913512 35
23324ae1 36 For example:
7c913512 37
23324ae1
FM
38 @code
39 wxFileInputStream input( "mytext.txt" );
7977b62a
BP
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
23324ae1 48 @endcode
7c913512 49
23324ae1
FM
50 @library{wxbase}
51 @category{streams}
7c913512 52
7977b62a 53 @see wxTextOutputStream
23324ae1 54*/
7c913512 55class wxTextInputStream
23324ae1
FM
56{
57public:
58 /**
23324ae1 59 Constructs a text stream associated to the given input stream.
3c4f71cc 60
7c913512 61 @param stream
4cc4bfaf 62 The underlying input stream.
7c913512 63 @param sep
4cc4bfaf 64 The initial string separator characters.
7c913512 65 @param conv
7977b62a
BP
66 <b>In Unicode build only:</b> The encoding converter used to
67 convert the bytes in the underlying input stream to characters.
23324ae1
FM
68 */
69 wxTextInputStream(wxInputStream& stream,
7977b62a
BP
70 const wxString& sep = " \t",
71 const wxMBConv& conv = wxConvAuto());
23324ae1
FM
72
73 /**
7977b62a 74 Destructor.
23324ae1
FM
75 */
76 ~wxTextInputStream();
77
78 /**
7977b62a
BP
79 Reads a character, returns 0 if there are no more characters in the
80 stream.
23324ae1
FM
81 */
82 wxChar GetChar();
83
84 /**
85 Reads a unsigned 16 bit integer from the stream.
7977b62a
BP
86
87 See Read8() for the description of the @a base parameter.
23324ae1
FM
88 */
89 wxUint16 Read16(int base = 10);
90
91 /**
92 Reads a signed 16 bit integer from the stream.
7977b62a
BP
93
94 See Read8() for the description of the @a base parameter.
23324ae1
FM
95 */
96 wxInt16 Read16S(int base = 10);
97
98 /**
99 Reads a 32 bit unsigned integer from the stream.
7977b62a
BP
100
101 See Read8() for the description of the @a base parameter.
23324ae1
FM
102 */
103 wxUint32 Read32(int base = 10);
104
105 /**
106 Reads a 32 bit signed integer from the stream.
7977b62a
BP
107
108 See Read8() for the description of the @a base parameter.
23324ae1
FM
109 */
110 wxInt32 Read32S(int base = 10);
111
112 /**
7977b62a
BP
113 Reads a single unsigned byte from the stream, given in base @a base.
114
4cc4bfaf 115 The value of @a base must be comprised between 2 and 36, inclusive, or
7977b62a 116 be a special value 0 which means that the usual rules of C numbers are
23324ae1 117 applied: if the number starts with @c 0x it is considered to be in base
7977b62a
BP
118 16, if it starts with 0 - in base 8 and in base 10 otherwise. Note that
119 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
121 not familiar with C) results.
23324ae1
FM
122 */
123 wxUint8 Read8(int base = 10);
124
125 /**
126 Reads a single signed byte from the stream.
7977b62a
BP
127
128 See Read8() for the description of the @a base parameter.
23324ae1
FM
129 */
130 wxInt8 Read8S(int base = 10);
131
132 /**
133 Reads a double (IEEE encoded) from the stream.
134 */
135 double ReadDouble();
136
137 /**
7977b62a
BP
138 Reads a line from the input stream and returns it (without the end of
139 line character).
23324ae1
FM
140 */
141 wxString ReadLine();
142
143 /**
7977b62a
BP
144 @deprecated Use ReadLine() or ReadWord() instead.
145
23324ae1
FM
146 Same as ReadLine().
147 */
148 wxString ReadString();
149
150 /**
7977b62a
BP
151 Reads a word (a sequence of characters until the next separator) from
152 the input stream.
3c4f71cc 153
4cc4bfaf 154 @see SetStringSeparators()
23324ae1
FM
155 */
156 wxString ReadWord();
157
158 /**
7c913512 159 Sets the characters which are used to define the word boundaries in
23324ae1 160 ReadWord().
7977b62a
BP
161
162 The default separators are the @c space and @c TAB characters.
23324ae1
FM
163 */
164 void SetStringSeparators(const wxString& sep);
165};
166
167
7977b62a
BP
168/**
169 Specifies the end-of-line characters to use with wxTextOutputStream.
170*/
171typedef enum
172{
173 /**
174 Specifies wxTextOutputStream to use the native end-of-line characters.
175 */
176 wxEOL_NATIVE,
177
178 /**
179 Specifies wxTextOutputStream to use Unix end-of-line characters.
180 */
181 wxEOL_UNIX,
182
183 /**
184 Specifies wxTextOutputStream to use Mac end-of-line characters.
185 */
186 wxEOL_MAC,
187
188 /**
189 Specifies wxTextOutputStream to use DOS end-of-line characters.
190 */
191 wxEOL_DOS
192} wxEOL;
193
e54c96f1 194
23324ae1
FM
195/**
196 @class wxTextOutputStream
197 @wxheader{txtstrm.h}
7c913512 198
ca8cf4ff 199 This class provides functions that write text data using an output stream,
7977b62a 200 allowing you to write text, floats, and integers.
7c913512 201
ca8cf4ff 202 You can also simulate the C++ @c std::cout class:
7c913512 203
23324ae1
FM
204 @code
205 wxFFileOutputStream output( stderr );
7977b62a 206 wxTextOutputStream cout( output );
7c913512 207
7977b62a
BP
208 cout << "This is a text line" << endl;
209 cout << 1234;
210 cout << 1.23456;
23324ae1 211 @endcode
7c913512 212
7977b62a
BP
213 The wxTextOutputStream writes text files (or streams) on DOS, Macintosh and
214 Unix in their native formats (concerning the line ending).
7c913512 215
23324ae1
FM
216 @library{wxbase}
217 @category{streams}
7977b62a
BP
218
219 @see wxTextInputStream
23324ae1 220*/
7c913512 221class wxTextOutputStream
23324ae1
FM
222{
223public:
224 /**
23324ae1 225 Constructs a text stream object associated to the given output stream.
3c4f71cc 226
7c913512 227 @param stream
4cc4bfaf 228 The output stream.
7c913512 229 @param mode
7977b62a
BP
230 The end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS,
231 ::wxEOL_MAC and ::wxEOL_UNIX.
7c913512 232 @param conv
7977b62a 233 <b>In Unicode build only:</b> The object used to convert
4cc4bfaf 234 Unicode text into ASCII characters written to the output stream.
23324ae1
FM
235 */
236 wxTextOutputStream(wxOutputStream& stream,
7977b62a
BP
237 wxEOL mode = wxEOL_NATIVE,
238 const wxMBConv& conv = wxConvAuto());
23324ae1
FM
239
240 /**
241 Destroys the wxTextOutputStream object.
ca8cf4ff
VZ
242
243 Also calls Flush().
23324ae1
FM
244 */
245 ~wxTextOutputStream();
246
ca8cf4ff
VZ
247 /**
248 Flushes the stream.
249
250 This method should be called when using stateful encodings (currently
251 the only example of such encoding in wxWidgets is wxMBConvUTF7) to
252 write the end of the encoded data to the stream.
253
254 @since 2.9.0
255 */
256 void Flush();
257
23324ae1 258 /**
7977b62a
BP
259 Returns the end-of-line mode. One of ::wxEOL_DOS, ::wxEOL_MAC and
260 ::wxEOL_UNIX.
23324ae1
FM
261 */
262 wxEOL GetMode();
263
264 /**
265 Writes a character to the stream.
266 */
267 void PutChar(wxChar c);
268
269 /**
7977b62a
BP
270 Set the end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS,
271 ::wxEOL_MAC and ::wxEOL_UNIX.
23324ae1
FM
272 */
273 void SetMode(wxEOL mode = wxEOL_NATIVE);
274
275 /**
4cc4bfaf 276 Writes the 16 bit integer @a i16 to the stream.
23324ae1
FM
277 */
278 void Write16(wxUint16 i16);
279
280 /**
4cc4bfaf 281 Writes the 32 bit integer @a i32 to the stream.
23324ae1
FM
282 */
283 void Write32(wxUint32 i32);
284
285 /**
4cc4bfaf 286 Writes the single byte @a i8 to the stream.
23324ae1
FM
287 */
288 void Write8(wxUint8 i8);
289
290 /**
4cc4bfaf 291 Writes the double @a f to the stream using the IEEE format.
23324ae1
FM
292 */
293 virtual void WriteDouble(double f);
294
295 /**
4cc4bfaf 296 Writes @a string as a line. Depending on the end-of-line mode the end of
7977b62a
BP
297 line ('\\n') characters in the string are converted to the correct line
298 ending terminator.
23324ae1
FM
299 */
300 virtual void WriteString(const wxString& string);
301};
e54c96f1 302