]> git.saurik.com Git - wxWidgets.git/blame - interface/datstrm.h
remove misleading documentation of minPage in GetPageInfo() (see ticket #9502)
[wxWidgets.git] / interface / datstrm.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: datstrm.h
f09b5681 3// Purpose: interface of wxDataInputStream and wxDataOutputStream
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxDataOutputStream
11 @wxheader{datstrm.h}
7c913512 12
f09b5681
BP
13 This class provides functions that write binary data types in a portable
14 way. Data can be written in either big-endian or little-endian format,
15 little-endian being the default on all architectures.
7c913512 16
f09b5681
BP
17 If you want to write data to text files (or streams) use wxTextOutputStream
18 instead.
7c913512 19
f09b5681
BP
20 The "<<" operator is overloaded and you can use this class like a standard
21 C++ iostream. See wxDataInputStream for its usage and caveats.
7c913512 22
23324ae1
FM
23 @library{wxbase}
24 @category{streams}
f09b5681
BP
25
26 @see wxDataInputStream
23324ae1 27*/
7c913512 28class wxDataOutputStream
23324ae1
FM
29{
30public:
23324ae1 31 /**
f09b5681
BP
32 Constructs a datastream object from an output stream. Only write
33 methods will be available.
3c4f71cc 34
7c913512 35 @param stream
4cc4bfaf 36 The output stream.
23324ae1
FM
37 */
38 wxDataOutputStream(wxOutputStream& stream);
f09b5681
BP
39 /**
40 Constructs a datastream object from an output stream. Only write
41 methods will be available. This constructor is only available in
42 Unicode builds of wxWidgets.
43
44 @param stream
45 The output stream.
46 @param conv
47 Charset conversion object object used to encoding Unicode strings
48 before writing them to the stream in Unicode mode (see
49 WriteString() for a detailed description). Note that you must not
50 destroy @a conv before you destroy this wxDataOutputStream
51 instance! It is recommended to use the default value (UTF-8).
52 */
53 wxDataOutputStream(wxOutputStream& stream,
54 const wxMBConv& conv = wxConvAuto());
23324ae1
FM
55
56 /**
57 Destroys the wxDataOutputStream object.
58 */
59 ~wxDataOutputStream();
60
61 /**
f09b5681
BP
62 If @a be_order is @true, all data will be written in big-endian order,
63 e.g. for reading on a Sparc or from Java-Streams (which always use
64 big-endian order), otherwise data will be written in little-endian
65 order.
23324ae1
FM
66 */
67 void BigEndianOrdered(bool be_order);
68
f09b5681
BP
69 /**
70 Writes the single byte @a i8 to the stream.
71 */
72 void Write8(wxUint8 i8);
73 /**
74 Writes an array of bytes to the stream. The amount of bytes to write is
75 specified with the @a size variable.
76 */
77 void Write8(const wxUint8* buffer, size_t size);
78
79 /**
80 Writes the 16 bit unsigned integer @a i16 to the stream.
81 */
82 void Write16(wxUint16 i16);
23324ae1
FM
83 /**
84 Writes an array of 16 bit unsigned integer to the stream. The amount of
4cc4bfaf 85 16 bit unsigned integer to write is specified with the @a size variable.
23324ae1 86 */
4cc4bfaf 87 void Write16(const wxUint16* buffer, size_t size);
23324ae1 88
f09b5681
BP
89 /**
90 Writes the 32 bit unsigned integer @a i32 to the stream.
91 */
92 void Write32(wxUint32 i32);
23324ae1
FM
93 /**
94 Writes an array of 32 bit unsigned integer to the stream. The amount of
4cc4bfaf 95 32 bit unsigned integer to write is specified with the @a size variable.
23324ae1 96 */
4cc4bfaf 97 void Write32(const wxUint32* buffer, size_t size);
23324ae1 98
f09b5681
BP
99 /**
100 Writes the 64 bit unsigned integer @a i64 to the stream.
101 */
102 void Write64(wxUint64 i64);
23324ae1
FM
103 /**
104 Writes an array of 64 bit unsigned integer to the stream. The amount of
4cc4bfaf 105 64 bit unsigned integer to write is specified with the @a size variable.
23324ae1 106 */
4cc4bfaf 107 void Write64(const wxUint64* buffer, size_t size);
23324ae1 108
23324ae1 109 /**
f09b5681 110 Writes the double @a f to the stream using the IEEE format.
23324ae1 111 */
f09b5681 112 void WriteDouble(double f);
23324ae1
FM
113 /**
114 Writes an array of double to the stream. The amount of double to write is
4cc4bfaf 115 specified with the @a size variable.
23324ae1 116 */
4cc4bfaf 117 void WriteDouble(const double* buffer, size_t size);
23324ae1
FM
118
119 /**
f09b5681
BP
120 Writes @a string to the stream. Actually, this method writes the size
121 of the string before writing @a string itself.
122
123 In ANSI build of wxWidgets, the string is written to the stream in
124 exactly same way it is represented in memory. In Unicode build,
125 however, the string is first converted to multibyte representation with
126 @e conv object passed to stream's constructor (consequently, ANSI
127 applications can read data written by Unicode application, as long as
128 they agree on encoding) and this representation is written to the
129 stream. UTF-8 is used by default.
23324ae1
FM
130 */
131 void WriteString(const wxString& string);
132};
133
134
e54c96f1 135
23324ae1
FM
136/**
137 @class wxDataInputStream
138 @wxheader{datstrm.h}
7c913512 139
f09b5681
BP
140 This class provides functions that read binary data types in a portable
141 way. Data can be read in either big-endian or little-endian format,
142 little-endian being the default on all architectures.
7c913512 143
f09b5681
BP
144 If you want to read data from text files (or streams) use wxTextInputStream
145 instead.
7c913512 146
f09b5681
BP
147 The ">>" operator is overloaded and you can use this class like a standard
148 C++ iostream. Note, however, that the arguments are the fixed size types
149 wxUint32, wxInt32 etc and on a typical 32-bit computer, none of these match
150 to the "long" type (wxInt32 is defined as signed int on 32-bit
151 architectures) so that you cannot use long. To avoid problems (here and
152 elsewhere), make use of the wxInt32, wxUint32, etc types.
7c913512 153
23324ae1 154 For example:
7c913512 155
23324ae1
FM
156 @code
157 wxFileInputStream input( "mytext.dat" );
f09b5681
BP
158 wxDataInputStream store( input );
159 wxUint8 i1;
160 float f2;
161 wxString line;
162
163 store >> i1; // read a 8 bit integer.
164 store >> i1 >> f2; // read a 8 bit integer followed by float.
165 store >> line; // read a text line
23324ae1 166 @endcode
7c913512 167
23324ae1
FM
168 @library{wxbase}
169 @category{streams}
f09b5681
BP
170
171 @see wxDataOutputStream
23324ae1 172*/
7c913512 173class wxDataInputStream
23324ae1
FM
174{
175public:
23324ae1 176 /**
f09b5681
BP
177 Constructs a datastream object from an input stream. Only read methods
178 will be available.
179
180 @param stream
181 The input stream.
182 */
183 wxDataInputStream(wxInputStream& stream);
184 /**
185 Constructs a datastream object from an input stream. Only read methods
186 will be available. This constructor is only available in Unicode builds
187 of wxWidgets.
3c4f71cc 188
7c913512 189 @param stream
4cc4bfaf 190 The input stream.
7c913512 191 @param conv
4cc4bfaf 192 Charset conversion object object used to decode strings in Unicode
f09b5681
BP
193 mode (see ReadString() for a detailed description). Note that you
194 must not destroy @a conv before you destroy this wxDataInputStream
195 instance!
23324ae1 196 */
f09b5681
BP
197 wxDataInputStream(wxInputStream& stream,
198 const wxMBConv& conv = wxConvAuto());
23324ae1
FM
199
200 /**
201 Destroys the wxDataInputStream object.
202 */
203 ~wxDataInputStream();
204
205 /**
f09b5681
BP
206 If @a be_order is @true, all data will be read in big-endian order,
207 such as written by programs on a big endian architecture (e.g. Sparc)
208 or written by Java-Streams (which always use big-endian order).
23324ae1
FM
209 */
210 void BigEndianOrdered(bool be_order);
211
23324ae1 212 /**
f09b5681
BP
213 Reads a single byte from the stream.
214 */
215 wxUint8 Read8();
216 /**
217 Reads bytes from the stream in a specified buffer. The amount of bytes
218 to read is specified by the @a size variable.
219 */
220 void Read8(wxUint8* buffer, size_t size);
221
222 /**
223 Reads a 16 bit unsigned integer from the stream.
23324ae1
FM
224 */
225 wxUint16 Read16();
f09b5681
BP
226 /**
227 Reads 16 bit unsigned integers from the stream in a specified buffer.
228 The amount of 16 bit unsigned integers to read is specified by the
229 @a size variable.
230 */
4cc4bfaf 231 void Read16(wxUint16* buffer, size_t size);
23324ae1 232
23324ae1 233 /**
f09b5681 234 Reads a 32 bit unsigned integer from the stream.
23324ae1
FM
235 */
236 wxUint32 Read32();
f09b5681
BP
237 /**
238 Reads 32 bit unsigned integers from the stream in a specified buffer.
239 The amount of 32 bit unsigned integers to read is specified by the
240 @a size variable.
241 */
4cc4bfaf 242 void Read32(wxUint32* buffer, size_t size);
23324ae1 243
23324ae1 244 /**
f09b5681 245 Reads a 64 bit unsigned integer from the stream.
23324ae1
FM
246 */
247 wxUint64 Read64();
23324ae1 248 /**
f09b5681
BP
249 Reads 64 bit unsigned integers from the stream in a specified buffer.
250 The amount of 64 bit unsigned integers to read is specified by the
251 @a size variable.
23324ae1 252 */
f09b5681 253 void Read64(wxUint64* buffer, size_t size);
23324ae1 254
23324ae1 255 /**
f09b5681 256 Reads a double (IEEE encoded) from the stream.
23324ae1
FM
257 */
258 double ReadDouble();
f09b5681
BP
259 /**
260 Reads double data (IEEE encoded) from the stream in a specified buffer.
261 The amount of doubles to read is specified by the @a size variable.
262 */
4cc4bfaf 263 void ReadDouble(double* buffer, size_t size);
23324ae1
FM
264
265 /**
f09b5681
BP
266 Reads a string from a stream. Actually, this function first reads a
267 long integer specifying the length of the string (without the last null
268 character) and then reads the string.
269
270 In Unicode build of wxWidgets, the fuction first reads multibyte
271 (char*) string from the stream and then converts it to Unicode using
272 the @e conv object passed to constructor and returns the result as
273 wxString. You are responsible for using the same convertor as when
274 writing the stream.
275
276 @see wxDataOutputStream::WriteString()
23324ae1
FM
277 */
278 wxString ReadString();
279};
e54c96f1 280