interface/datstrm.h

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