]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/datstrm.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / datstrm.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: datstrm.h
f09b5681 3// Purpose: interface of wxDataInputStream and wxDataOutputStream
23324ae1 4// Author: wxWidgets team
526954c5 5// Licence: wxWindows licence
23324ae1
FM
6/////////////////////////////////////////////////////////////////////////////
7
8/**
9 @class wxDataOutputStream
7c913512 10
f09b5681 11 This class provides functions that write binary data types in a portable
789ab840
VZ
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.
7c913512 25
f09b5681
BP
26 If you want to write data to text files (or streams) use wxTextOutputStream
27 instead.
7c913512 28
f09b5681
BP
29 The "<<" operator is overloaded and you can use this class like a standard
30 C++ iostream. See wxDataInputStream for its usage and caveats.
7c913512 31
23324ae1
FM
32 @library{wxbase}
33 @category{streams}
f09b5681
BP
34
35 @see wxDataInputStream
23324ae1 36*/
7c913512 37class wxDataOutputStream
23324ae1
FM
38{
39public:
23324ae1 40 /**
76e9224e
FM
41 Constructs a datastream object from an output stream.
42 Only write methods will be available.
3c4f71cc 43
7323ff1a 44 Note that the @a conv parameter is only available in Unicode builds of wxWidgets.
f09b5681
BP
45
46 @param stream
47 The output stream.
48 @param conv
d13b34d3 49 Charset conversion object used to encoding Unicode strings
f09b5681
BP
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,
107ea8f0 56 const wxMBConv& conv = wxConvUTF8);
23324ae1
FM
57
58 /**
59 Destroys the wxDataOutputStream object.
60 */
61 ~wxDataOutputStream();
62
63 /**
f09b5681
BP
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.
23324ae1
FM
68 */
69 void BigEndianOrdered(bool be_order);
be2a424d 70
10c2f98a
RR
71 /**
72 Returns the current text conversion class used for
73 writing strings.
74 */
75 wxMBConv *GetConv() const;
23324ae1 76
be2a424d 77 /**
10c2f98a
RR
78 Sets the text conversion class used for writing strings.
79 */
80 void SetConv( const wxMBConv &conv );
be2a424d 81
789ab840
VZ
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
f09b5681
BP
116 /**
117 Writes the single byte @a i8 to the stream.
118 */
119 void Write8(wxUint8 i8);
120 /**
be2a424d 121 Writes an array of bytes to the stream. The number of bytes to write is
f09b5681
BP
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);
23324ae1 130 /**
be2a424d 131 Writes an array of 16 bit unsigned integer to the stream. The number of
4cc4bfaf 132 16 bit unsigned integer to write is specified with the @a size variable.
23324ae1 133 */
4cc4bfaf 134 void Write16(const wxUint16* buffer, size_t size);
23324ae1 135
f09b5681
BP
136 /**
137 Writes the 32 bit unsigned integer @a i32 to the stream.
138 */
139 void Write32(wxUint32 i32);
23324ae1 140 /**
be2a424d 141 Writes an array of 32 bit unsigned integer to the stream. The number of
4cc4bfaf 142 32 bit unsigned integer to write is specified with the @a size variable.
23324ae1 143 */
4cc4bfaf 144 void Write32(const wxUint32* buffer, size_t size);
23324ae1 145
f09b5681
BP
146 /**
147 Writes the 64 bit unsigned integer @a i64 to the stream.
148 */
149 void Write64(wxUint64 i64);
23324ae1 150 /**
be2a424d 151 Writes an array of 64 bit unsigned integer to the stream. The number of
4cc4bfaf 152 64 bit unsigned integer to write is specified with the @a size variable.
23324ae1 153 */
4cc4bfaf 154 void Write64(const wxUint64* buffer, size_t size);
23324ae1 155
23324ae1 156 /**
789ab840
VZ
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.
23324ae1 182 */
337bbb7a 183 void WriteDouble(double d);
789ab840 184
23324ae1 185 /**
be2a424d
VZ
186 Writes an array of double to the stream. The number of doubles to write is
187 specified by the @a size variable.
23324ae1 188 */
4cc4bfaf 189 void WriteDouble(const double* buffer, size_t size);
23324ae1
FM
190
191 /**
f09b5681
BP
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.
23324ae1
FM
202 */
203 void WriteString(const wxString& string);
204};
205
206
e54c96f1 207
23324ae1
FM
208/**
209 @class wxDataInputStream
7c913512 210
f09b5681 211 This class provides functions that read binary data types in a portable
789ab840
VZ
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.
7c913512 216
f09b5681
BP
217 If you want to read data from text files (or streams) use wxTextInputStream
218 instead.
7c913512 219
f09b5681
BP
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.
7c913512 226
23324ae1 227 For example:
7c913512 228
23324ae1
FM
229 @code
230 wxFileInputStream input( "mytext.dat" );
f09b5681
BP
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
23324ae1 239 @endcode
7c913512 240
23324ae1
FM
241 @library{wxbase}
242 @category{streams}
f09b5681
BP
243
244 @see wxDataOutputStream
23324ae1 245*/
7c913512 246class wxDataInputStream
23324ae1
FM
247{
248public:
23324ae1 249 /**
76e9224e
FM
250 Constructs a datastream object from an input stream.
251 Only read methods will be available.
f09b5681 252
7323ff1a 253 Note that the @a conv parameter is only available in Unicode builds of wxWidgets.
3c4f71cc 254
7c913512 255 @param stream
4cc4bfaf 256 The input stream.
7c913512 257 @param conv
d13b34d3 258 Charset conversion object used to decode strings in Unicode
f09b5681
BP
259 mode (see ReadString() for a detailed description). Note that you
260 must not destroy @a conv before you destroy this wxDataInputStream
261 instance!
23324ae1 262 */
f09b5681 263 wxDataInputStream(wxInputStream& stream,
107ea8f0 264 const wxMBConv& conv = wxConvUTF8 );
23324ae1
FM
265
266 /**
267 Destroys the wxDataInputStream object.
268 */
269 ~wxDataInputStream();
270
271 /**
f09b5681
BP
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).
23324ae1
FM
275 */
276 void BigEndianOrdered(bool be_order);
277
10c2f98a
RR
278 /**
279 Returns the current text conversion class used for
280 reading strings.
281 */
282 wxMBConv *GetConv() const;
be2a424d 283
23324ae1 284 /**
f09b5681
BP
285 Reads a single byte from the stream.
286 */
287 wxUint8 Read8();
288 /**
be2a424d 289 Reads bytes from the stream in a specified buffer. The number of bytes
f09b5681
BP
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.
23324ae1
FM
296 */
297 wxUint16 Read16();
f09b5681
BP
298 /**
299 Reads 16 bit unsigned integers from the stream in a specified buffer.
be2a424d 300 The number of 16 bit unsigned integers to read is specified by the
f09b5681
BP
301 @a size variable.
302 */
4cc4bfaf 303 void Read16(wxUint16* buffer, size_t size);
23324ae1 304
23324ae1 305 /**
f09b5681 306 Reads a 32 bit unsigned integer from the stream.
23324ae1
FM
307 */
308 wxUint32 Read32();
f09b5681
BP
309 /**
310 Reads 32 bit unsigned integers from the stream in a specified buffer.
be2a424d 311 The number of 32 bit unsigned integers to read is specified by the
f09b5681
BP
312 @a size variable.
313 */
4cc4bfaf 314 void Read32(wxUint32* buffer, size_t size);
23324ae1 315
23324ae1 316 /**
f09b5681 317 Reads a 64 bit unsigned integer from the stream.
23324ae1
FM
318 */
319 wxUint64 Read64();
23324ae1 320 /**
f09b5681 321 Reads 64 bit unsigned integers from the stream in a specified buffer.
be2a424d 322 The number of 64 bit unsigned integers to read is specified by the
f09b5681 323 @a size variable.
23324ae1 324 */
f09b5681 325 void Read64(wxUint64* buffer, size_t size);
23324ae1 326
23324ae1 327 /**
789ab840
VZ
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.
23324ae1
FM
354 */
355 double ReadDouble();
789ab840 356
f09b5681 357 /**
789ab840 358 Reads double data from the stream in a specified buffer.
be2a424d
VZ
359
360 The number of doubles to read is specified by the @a size variable.
f09b5681 361 */
4cc4bfaf 362 void ReadDouble(double* buffer, size_t size);
23324ae1
FM
363
364 /**
f09b5681
BP
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
d13b34d3 372 wxString. You are responsible for using the same converter as when
f09b5681
BP
373 writing the stream.
374
375 @see wxDataOutputStream::WriteString()
23324ae1
FM
376 */
377 wxString ReadString();
10c2f98a 378
be2a424d 379 /**
10c2f98a
RR
380 Sets the text conversion class used for reading strings.
381 */
382 void SetConv( const wxMBConv &conv );
789ab840
VZ
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();
23324ae1 417};
e54c96f1 418