interface/wx/buffer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        buffer.h
   3 // Purpose:     interface of wxMemoryBuffer
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     wxCharTypeBuffer<T> is a template class for storing characters.
  12
  13     @todo provide better docs for this class
  14
  15     @tparam T
  16         The type of the characters stored in this class.
  17
  18     @nolibrary
  19     @category{data}
  20 */
  21 template <typename T>
  22 class wxCharTypeBuffer
  23 {
  24 public:
  25     typedef T CharType;
  26
  27     wxCharTypeBuffer(const CharType *str = NULL);
  28     wxCharTypeBuffer(size_t len);
  29     wxCharTypeBuffer(const wxCharTypeBuffer& src);
  30     ~wxCharTypeBuffer();
  31
  32     void reset();
  33
  34     wxCharTypeBuffer& operator=(const CharType *str);
  35     wxCharTypeBuffer& operator=(const wxCharTypeBuffer& src);
  36
  37     bool extend(size_t len);
  38
  39     CharType *data();
  40     const CharType *data() const;
  41     operator const CharType *() const;
  42     CharType operator[](size_t n) const;
  43 };
  44
  45 /**
  46     This is a specialization of wxCharTypeBuffer<T> for @c char type.
  47
  48     @todo provide better docs for this class
  49
  50     @nolibrary
  51     @category{data}
  52 */
  53 class wxCharBuffer : public wxCharTypeBuffer<char>
  54 {
  55 public:
  56     typedef wxCharTypeBuffer<char> wxCharTypeBufferBase;
  57
  58     wxCharBuffer(const wxCharTypeBufferBase& buf);
  59     wxCharBuffer(const CharType *str = NULL);
  60     wxCharBuffer(size_t len);
  61     wxCharBuffer(const wxCStrData& cstr);
  62 };
  63
  64 /**
  65     This is a specialization of wxCharTypeBuffer<T> for @c wchar_t type.
  66     This class is available only when <tt>wxUSE_WCHAR_T==1</tt>
  67
  68     @nolibrary
  69     @category{data}
  70 */
  71 class wxWCharBuffer : public wxCharTypeBuffer<wchar_t>
  72 {
  73 public:
  74     typedef wxCharTypeBuffer<wchar_t> wxCharTypeBufferBase;
  75
  76     wxWCharBuffer(const wxCharTypeBufferBase& buf);
  77     wxWCharBuffer(const CharType *str = NULL);
  78     wxWCharBuffer(size_t len);
  79     wxWCharBuffer(const wxCStrData& cstr);
  80 };
  81
  82 /**
  83     @class wxMemoryBuffer
  84
  85     A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized
  86     blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when
  87     the object is destroyed.
  88
  89     @library{wxbase}
  90     @category{data}
  91 */
  92 class wxMemoryBuffer
  93 {
  94 public:
  95     /**
  96         Copy constructor, refcounting is used for performance, but wxMemoryBuffer
  97         is not a copy-on-write structure so changes made to one buffer effect all
  98         copies made from it.
  99
 100         @see @ref overview_refcount
 101     */
 102     wxMemoryBuffer(const wxMemoryBuffer& src);
 103
 104     /**
 105         Create a new buffer.
 106
 107         @param size
 108             size of the new buffer.
 109     */
 110     wxMemoryBuffer(size_t size = DefBufSize);
 111
 112     /**
 113         Append a single byte to the buffer.
 114
 115         @param data
 116             New byte to append to the buffer.
 117     */
 118     void AppendByte(char data);
 119
 120     /**
 121         Ensure that the buffer is big enough and return a pointer to the start
 122         of the empty space in the buffer. This pointer can be used to directly
 123         write data into the buffer, this new data will be appended to the
 124         existing data.
 125
 126         @param sizeNeeded
 127             Amount of extra space required in the buffer for
 128             the append operation
 129     */
 130     void* GetAppendBuf(size_t sizeNeeded);
 131
 132     /**
 133         Returns the size of the buffer.
 134     */
 135     size_t GetBufSize() const;
 136
 137     /**
 138         Return a pointer to the data in the buffer.
 139     */
 140     void* GetData() const;
 141
 142     /**
 143         Returns the length of the valid data in the buffer.
 144     */
 145     size_t GetDataLen() const;
 146
 147     /**
 148         Ensure the buffer is big enough and return a pointer to the
 149         buffer which can be used to directly write into the buffer
 150         up to @a sizeNeeded bytes.
 151     */
 152     void* GetWriteBuf(size_t sizeNeeded);
 153
 154     /**
 155         Ensures the buffer has at least @a size bytes available.
 156     */
 157     void SetBufSize(size_t size);
 158
 159     /**
 160         Sets the length of the data stored in the buffer.
 161         Mainly useful for truncating existing data.
 162
 163         @param size
 164             New length of the valid data in the buffer. This is
 165             distinct from the allocated size
 166     */
 167     void SetDataLen(size_t size);
 168
 169     /**
 170         Update the length after completing a direct append, which
 171         you must have used GetAppendBuf() to initialise.
 172
 173         @param sizeUsed
 174             This is the amount of new data that has been
 175             appended.
 176     */
 177     void UngetAppendBuf(size_t sizeUsed);
 178
 179     /**
 180         Update the buffer after completing a direct write, which
 181         you must have used GetWriteBuf() to initialise.
 182
 183         @param sizeUsed
 184             The amount of data written in to buffer
 185             by the direct write
 186     */
 187     void UngetWriteBuf(size_t sizeUsed);
 188 };
 189