]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/datstrm.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / interface / wx / datstrm.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: datstrm.h
3 // Purpose: interface of wxDataInputStream and wxDataOutputStream
4 // Author: wxWidgets team
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
7
8 /**
9 @class wxDataOutputStream
10
11 This class provides functions that write binary data types in a portable
12 way.
13
14 Data can be written in either big-endian or little-endian format,
15 little-endian being the default on all architectures but BigEndianOrdered()
16 can be used to change this. The default format for the floating point types
17 is 80 bit "extended precision" unless @c wxUSE_APPLE_IEEE was turned off
18 during the library compilation, in which case extended precision is not
19 available at all. You can call UseBasicPrecisions() to change this and
20 use the standard IEEE 754 32 bit single precision format for floats and
21 standard 64 bit double precision format for doubles. This is recommended
22 for the new code for better interoperability with other software that
23 typically uses standard IEEE 754 formats for its data, the use of extended
24 precision by default is solely due to backwards compatibility.
25
26 If you want to write data to text files (or streams) use wxTextOutputStream
27 instead.
28
29 The "<<" operator is overloaded and you can use this class like a standard
30 C++ iostream. See wxDataInputStream for its usage and caveats.
31
32 @library{wxbase}
33 @category{streams}
34
35 @see wxDataInputStream
36 */
37 class wxDataOutputStream
38 {
39 public:
40 /**
41 Constructs a datastream object from an output stream.
42 Only write methods will be available.
43
44 Note that the @a conv parameter is only available in Unicode builds of wxWidgets.
45
46 @param stream
47 The output stream.
48 @param conv
49 Charset conversion object used to encoding Unicode strings
50 before writing them to the stream in Unicode mode (see
51 WriteString() for a detailed description). Note that you must not
52 destroy @a conv before you destroy this wxDataOutputStream
53 instance! It is recommended to use the default value (UTF-8).
54 */
55 wxDataOutputStream(wxOutputStream& stream,
56 const wxMBConv& conv = wxConvUTF8);
57
58 /**
59 Destroys the wxDataOutputStream object.
60 */
61 ~wxDataOutputStream();
62
63 /**
64 If @a be_order is @true, all data will be written in big-endian order,
65 e.g. for reading on a Sparc or from Java-Streams (which always use
66 big-endian order), otherwise data will be written in little-endian
67 order.
68 */
69 void BigEndianOrdered(bool be_order);
70
71 /**
72 Returns the current text conversion class used for
73 writing strings.
74 */
75 wxMBConv *GetConv() const;
76
77 /**
78 Sets the text conversion class used for writing strings.
79 */
80 void SetConv( const wxMBConv &conv );
81
82 /**
83 Disables the use of extended precision format for floating point
84 numbers.
85
86 This method disables the use of 80 bit extended precision format for
87 the @c float and @c double values written to the stream, which is used
88 by default (unless @c wxUSE_APPLE_IEEE was set to @c 0 when building
89 the library, in which case the extended format support is not available
90 at all and this function does nothing).
91
92 After calling it, @c float values will be written out in one of IEEE
93 754 "basic formats", i.e. 32 bit single precision format for floats and
94 64 bit double precision format for doubles.
95
96 @since 2.9.5
97 */
98 void UseBasicPrecisions();
99
100 /**
101 Explicitly request the use of extended precision for floating point
102 numbers.
103
104 This function allows the application code to explicitly request the use
105 of 80 bit extended precision format for the floating point numbers.
106 This is the case by default but using this function explicitly ensures
107 that the compilation of code relying on producing the output stream
108 using extended precision would fail when using a version of wxWidgets
109 compiled with @c wxUSE_APPLE_IEEE==0 and so not supporting this format
110 at all.
111
112 @since 2.9.5
113 */
114 void UseExtendedPrecision();
115
116 /**
117 Writes the single byte @a i8 to the stream.
118 */
119 void Write8(wxUint8 i8);
120 /**
121 Writes an array of bytes to the stream. The number of bytes to write is
122 specified with the @a size variable.
123 */
124 void Write8(const wxUint8* buffer, size_t size);
125
126 /**
127 Writes the 16 bit unsigned integer @a i16 to the stream.
128 */
129 void Write16(wxUint16 i16);
130 /**
131 Writes an array of 16 bit unsigned integer to the stream. The number of
132 16 bit unsigned integer to write is specified with the @a size variable.
133 */
134 void Write16(const wxUint16* buffer, size_t size);
135
136 /**
137 Writes the 32 bit unsigned integer @a i32 to the stream.
138 */
139 void Write32(wxUint32 i32);
140 /**
141 Writes an array of 32 bit unsigned integer to the stream. The number of
142 32 bit unsigned integer to write is specified with the @a size variable.
143 */
144 void Write32(const wxUint32* buffer, size_t size);
145
146 /**
147 Writes the 64 bit unsigned integer @a i64 to the stream.
148 */
149 void Write64(wxUint64 i64);
150 /**
151 Writes an array of 64 bit unsigned integer to the stream. The number of
152 64 bit unsigned integer to write is specified with the @a size variable.
153 */
154 void Write64(const wxUint64* buffer, size_t size);
155
156 /**
157 Writes the float @a f to the stream.
158
159 If UseBasicPrecisions() had been called, the value is written out using
160 the standard IEEE 754 32 bit single precision format. Otherwise, this
161 method uses the same format as WriteDouble(), i.e. 80 bit extended
162 precision representation.
163
164 @since 2.9.5
165 */
166 void WriteFloat(float f);
167
168 /**
169 Writes an array of float to the stream. The number of floats to write is
170 specified by the @a size variable.
171
172 @since 2.9.5
173 */
174 void WriteFloat(const float* buffer, size_t size);
175
176 /**
177 Writes the double @a d to the stream.
178
179 The output format is either 80 bit extended precision or, if
180 UseBasicPrecisions() had been called, standard IEEE 754 64 bit double
181 precision.
182 */
183 void WriteDouble(double d);
184
185 /**
186 Writes an array of double to the stream. The number of doubles to write is
187 specified by the @a size variable.
188 */
189 void WriteDouble(const double* buffer, size_t size);
190
191 /**
192 Writes @a string to the stream. Actually, this method writes the size
193 of the string before writing @a string itself.
194
195 In ANSI build of wxWidgets, the string is written to the stream in
196 exactly same way it is represented in memory. In Unicode build,
197 however, the string is first converted to multibyte representation with
198 @e conv object passed to stream's constructor (consequently, ANSI
199 applications can read data written by Unicode application, as long as
200 they agree on encoding) and this representation is written to the
201 stream. UTF-8 is used by default.
202 */
203 void WriteString(const wxString& string);
204 };
205
206
207
208 /**
209 @class wxDataInputStream
210
211 This class provides functions that read binary data types in a portable
212 way.
213
214 Please see wxDataOutputStream for the discussion of the format expected by
215 this stream on input, notably for the floating point values.
216
217 If you want to read data from text files (or streams) use wxTextInputStream
218 instead.
219
220 The ">>" operator is overloaded and you can use this class like a standard
221 C++ iostream. Note, however, that the arguments are the fixed size types
222 wxUint32, wxInt32 etc and on a typical 32-bit computer, none of these match
223 to the "long" type (wxInt32 is defined as signed int on 32-bit
224 architectures) so that you cannot use long. To avoid problems (here and
225 elsewhere), make use of the wxInt32, wxUint32, etc types.
226
227 For example:
228
229 @code
230 wxFileInputStream input( "mytext.dat" );
231 wxDataInputStream store( input );
232 wxUint8 i1;
233 float f2;
234 wxString line;
235
236 store >> i1; // read a 8 bit integer.
237 store >> i1 >> f2; // read a 8 bit integer followed by float.
238 store >> line; // read a text line
239 @endcode
240
241 @library{wxbase}
242 @category{streams}
243
244 @see wxDataOutputStream
245 */
246 class wxDataInputStream
247 {
248 public:
249 /**
250 Constructs a datastream object from an input stream.
251 Only read methods will be available.
252
253 Note that the @a conv parameter is only available in Unicode builds of wxWidgets.
254
255 @param stream
256 The input stream.
257 @param conv
258 Charset conversion object used to decode strings in Unicode
259 mode (see ReadString() for a detailed description). Note that you
260 must not destroy @a conv before you destroy this wxDataInputStream
261 instance!
262 */
263 wxDataInputStream(wxInputStream& stream,
264 const wxMBConv& conv = wxConvUTF8 );
265
266 /**
267 Destroys the wxDataInputStream object.
268 */
269 ~wxDataInputStream();
270
271 /**
272 If @a be_order is @true, all data will be read in big-endian order,
273 such as written by programs on a big endian architecture (e.g. Sparc)
274 or written by Java-Streams (which always use big-endian order).
275 */
276 void BigEndianOrdered(bool be_order);
277
278 /**
279 Returns the current text conversion class used for
280 reading strings.
281 */
282 wxMBConv *GetConv() const;
283
284 /**
285 Reads a single byte from the stream.
286 */
287 wxUint8 Read8();
288 /**
289 Reads bytes from the stream in a specified buffer. The number of bytes
290 to read is specified by the @a size variable.
291 */
292 void Read8(wxUint8* buffer, size_t size);
293
294 /**
295 Reads a 16 bit unsigned integer from the stream.
296 */
297 wxUint16 Read16();
298 /**
299 Reads 16 bit unsigned integers from the stream in a specified buffer.
300 The number of 16 bit unsigned integers to read is specified by the
301 @a size variable.
302 */
303 void Read16(wxUint16* buffer, size_t size);
304
305 /**
306 Reads a 32 bit unsigned integer from the stream.
307 */
308 wxUint32 Read32();
309 /**
310 Reads 32 bit unsigned integers from the stream in a specified buffer.
311 The number of 32 bit unsigned integers to read is specified by the
312 @a size variable.
313 */
314 void Read32(wxUint32* buffer, size_t size);
315
316 /**
317 Reads a 64 bit unsigned integer from the stream.
318 */
319 wxUint64 Read64();
320 /**
321 Reads 64 bit unsigned integers from the stream in a specified buffer.
322 The number of 64 bit unsigned integers to read is specified by the
323 @a size variable.
324 */
325 void Read64(wxUint64* buffer, size_t size);
326
327 /**
328 Reads a float from the stream.
329
330 Notice that if UseBasicPrecisions() hadn't been called, this function
331 simply reads a double and truncates it to float as by default the same
332 (80 bit extended precision) representation is used for both float and
333 double values.
334
335 @since 2.9.5
336 */
337 float ReadFloat();
338
339 /**
340 Reads float data from the stream in a specified buffer.
341
342 The number of floats to read is specified by the @a size variable.
343
344 @since 2.9.5
345 */
346 void ReadFloat(float* buffer, size_t size);
347
348 /**
349 Reads a double from the stream.
350
351 The expected format is either 80 bit extended precision or, if
352 UseBasicPrecisions() had been called, standard IEEE 754 64 bit double
353 precision.
354 */
355 double ReadDouble();
356
357 /**
358 Reads double data from the stream in a specified buffer.
359
360 The number of doubles to read is specified by the @a size variable.
361 */
362 void ReadDouble(double* buffer, size_t size);
363
364 /**
365 Reads a string from a stream. Actually, this function first reads a
366 long integer specifying the length of the string (without the last null
367 character) and then reads the string.
368
369 In Unicode build of wxWidgets, the fuction first reads multibyte
370 (char*) string from the stream and then converts it to Unicode using
371 the @e conv object passed to constructor and returns the result as
372 wxString. You are responsible for using the same converter as when
373 writing the stream.
374
375 @see wxDataOutputStream::WriteString()
376 */
377 wxString ReadString();
378
379 /**
380 Sets the text conversion class used for reading strings.
381 */
382 void SetConv( const wxMBConv &conv );
383
384 /**
385 Disables the use of extended precision format for floating point
386 numbers.
387
388 This method disables the use of 80 bit extended precision format for
389 the @c float and @c double values read from the stream, which is used
390 by default (unless @c wxUSE_APPLE_IEEE was set to @c 0 when building
391 the library, in which case the extended format support is not available
392 at all and this function does nothing).
393
394 After calling it, @c float values will be expected to appear in one of
395 IEEE 754 "basic formats", i.e. 32 bit single precision format for
396 floats and 64 bit double precision format for doubles in the input.
397
398 @since 2.9.5
399 */
400 void UseBasicPrecisions();
401
402 /**
403 Explicitly request the use of extended precision for floating point
404 numbers.
405
406 This function allows the application code to explicitly request the use
407 of 80 bit extended precision format for the floating point numbers.
408 This is the case by default but using this function explicitly ensures
409 that the compilation of code relying on reading the input containing
410 numbers in extended precision format would fail when using a version of
411 wxWidgets compiled with @c wxUSE_APPLE_IEEE==0 and so not supporting
412 this format at all.
413
414 @since 2.9.5
415 */
416 void UseExtendedPrecision();
417 };
418