interface/datstrm.h

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