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         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     @class wxDataInputStream
 126     @wxheader{datstrm.h}
 127
 128     This class provides functions that read binary data types in a
 129     portable way. Data can be read in either big-endian or little-endian
 130     format, little-endian being the default on all architectures.
 131
 132     If you want to read data from text files (or streams) use
 133     wxTextInputStream instead.
 134
 135     The  operator is overloaded and you can use this class like a standard C++
 136     iostream.
 137     Note, however, that the arguments are the fixed size types wxUint32, wxInt32 etc
 138     and on a typical 32-bit computer, none of these match to the "long" type
 139     (wxInt32
 140     is defined as signed int on 32-bit architectures) so that you cannot use long.
 141     To avoid
 142     problems (here and elsewhere), make use of the wxInt32, wxUint32, etc types.
 143
 144     For example:
 145
 146     @code
 147     wxFileInputStream input( "mytext.dat" );
 148       wxDataInputStream store( input );
 149       wxUint8 i1;
 150       float f2;
 151       wxString line;
 152
 153       store  i1;       // read a 8 bit integer.
 154       store  i1  f2; // read a 8 bit integer followed by float.
 155       store  line;     // read a text line
 156     @endcode
 157
 158     See also wxDataOutputStream.
 159
 160     @library{wxbase}
 161     @category{streams}
 162 */
 163 class wxDataInputStream
 164 {
 165 public:
 166     //@{
 167     /**
 168         )
 169         Constructs a datastream object from an input stream. Only read methods will
 170         be available. The second form is only available in Unicode build of wxWidgets.
 171
 172         @param stream
 173             The input stream.
 174         @param conv
 175             Charset conversion object object used to decode strings in Unicode
 176             mode (see ReadString()
 177             documentation for detailed description). Note that you must not destroy
 178             conv before you destroy this wxDataInputStream instance!
 179     */
 180     wxDataInputStream(wxInputStream& stream);
 181     wxDataInputStream(wxInputStream& stream);
 182     //@}
 183
 184     /**
 185         Destroys the wxDataInputStream object.
 186     */
 187     ~wxDataInputStream();
 188
 189     /**
 190         If @a be_order is @true, all data will be read in big-endian
 191         order, such as written by programs on a big endian architecture
 192         (e.g. Sparc) or written by Java-Streams (which always use
 193         big-endian order).
 194     */
 195     void BigEndianOrdered(bool be_order);
 196
 197     //@{
 198     /**
 199         Reads 16 bit unsigned integers from the stream in a specified buffer. the
 200         amount of 16 bit unsigned integer to read is specified by the @a size variable.
 201     */
 202     wxUint16 Read16();
 203     void Read16(wxUint16* buffer, size_t size);
 204     //@}
 205
 206     //@{
 207     /**
 208         Reads 32 bit unsigned integers from the stream in a specified buffer. the
 209         amount of
 210         32 bit unsigned integer to read is specified by the @a size variable.
 211     */
 212     wxUint32 Read32();
 213     void Read32(wxUint32* buffer, size_t size);
 214     //@}
 215
 216     //@{
 217     /**
 218         Reads 64 bit unsigned integers from the stream in a specified buffer. the
 219         amount of
 220         64 bit unsigned integer to read is specified by the @a size variable.
 221     */
 222     wxUint64 Read64();
 223     void Read64(wxUint64* buffer, size_t size);
 224     //@}
 225
 226     //@{
 227     /**
 228         Reads bytes from the stream in a specified buffer. The amount of
 229         bytes to read is specified by the @a size variable.
 230     */
 231     wxUint8 Read8();
 232     void Read8(wxUint8* buffer, size_t size);
 233     //@}
 234
 235     //@{
 236     /**
 237         Reads double data (IEEE encoded) from the stream in a specified buffer. the
 238         amount of
 239         double to read is specified by the @a size variable.
 240     */
 241     double ReadDouble();
 242     void ReadDouble(double* buffer, size_t size);
 243     //@}
 244
 245     /**
 246         Reads a string from a stream. Actually, this function first reads a long
 247         integer specifying the length of the string (without the last null character)
 248         and then reads the string.
 249         In Unicode build of wxWidgets, the fuction first reads multibyte (char*)
 250         string from the stream and then converts it to Unicode using the @e conv
 251         object passed to constructor and returns the result as wxString. You are
 252         responsible for using the same convertor as when writing the stream.
 253         See also wxDataOutputStream::WriteString.
 254     */
 255     wxString ReadString();
 256 };