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