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     wxScopedCharTypeBuffer<T> is a template class for storing characters.
  12
  13     Data are stored in reference-counted buffer. In other words, making a copy
  14     of wxScopedCharTypeBuffer<T> will @em not make another copy of the stored
  15     string data, it will still point to the same location in memory.
  16
  17     wxScopedCharTypeBuffer<T> supports two storage modes: owned and non-owned.
  18     "Owned" data buffer (created with CreateOwned() or wxCharTypeBuffer<T>
  19     derived class) owns the data and frees them when the last buffer pointing
  20     to them is destroyed.
  21
  22     "Non-owned" buffer (created with CreateNonOwned()), on the other hand,
  23     references data owned by somebody else -- typical use is by
  24     wxString::mb_str() or wxString::wc_str(), which may return non-owned buffer
  25     pointing to wxString's internal store.
  26
  27     Because of this, the validity of data stored in wxScopedCharTypeBuffer<T>
  28     is limited by the lifetime of the "parent" object that created the
  29     buffer (e.g. the wxString on which mb_str() was called).
  30
  31     If you need to preserve the data for longer, assign it to
  32     wxCharTypeBuffer<T> instead of wxScopedCharTypeBuffer<T>. On the other
  33     hand, use wxScopedCharTypeBuffer<T> if the buffer is to be destroyed before
  34     the "parent" object -- typical use would be creating it on the stack and
  35     destroying when it goes out of scope (hence the class' name).
  36
  37     @tparam T
  38         The type of the characters stored in this class.
  39
  40     @since 2.9.0
  41
  42     @nolibrary
  43     @category{data}
  44 */
  45 template <typename T>
  46 class wxScopedCharTypeBuffer
  47 {
  48 public:
  49     /// Stored characters type.
  50     typedef T CharType;
  51
  52     /// Default constructor, creates NULL buffer.
  53     wxScopedCharTypeBuffer();
  54
  55     /**
  56         Creates non-owned buffer from string data @a str.
  57
  58         The buffer's destructor will not destroy @a str. The returned buffer's
  59         data is valid only as long as @a str is valid.
  60
  61         @param str String data.
  62         @param len If specified, length of the string, otherwise the string
  63                    is considered to be NUL-terminated.
  64      */
  65     static const wxScopedCharTypeBuffer CreateNonOwned(const CharType *str, size_t len = wxNO_LEN);
  66
  67     /**
  68         Creates owned buffer from @a str and takes ownership of it.
  69
  70         The buffer's destructor will free @a str when its reference count
  71         reaches zero (initial count is 1).
  72
  73         @param str String data.
  74         @param len If specified, length of the string, otherwise the string
  75                    is considered to be NUL-terminated.
  76      */
  77     static const wxScopedCharTypeBuffer CreateOwned(const CharType *str, size_t len = wxNO_LEN);
  78
  79     /**
  80         Copy constructor.
  81
  82         Increases reference count on the data, does @em not make wxStrdup()
  83         copy of the data.
  84      */
  85     wxScopedCharTypeBuffer(const wxScopedCharTypeBuffer& src);
  86
  87     /// Assignment operator behaves in the same way as the copy constructor.
  88     wxScopedCharTypeBuffer& operator=(const wxScopedCharTypeBuffer& src);
  89
  90     /**
  91         Destructor. Frees stored data if it is in "owned" mode and data's
  92         reference count reaches zero.
  93      */
  94     ~wxScopedCharTypeBuffer();
  95
  96     /// Resets the buffer to NULL, freeing the data if necessary.
  97     void reset();
  98
  99     /// Returns pointer to the stored data.
 100     CharType *data();
 101
 102     /// Returns const pointer to the stored data.
 103     const CharType *data() const;
 104
 105     /// Returns length of the string stored.
 106     size_t length() const;
 107
 108     /// Implicit conversion to C string.
 109     operator const CharType *() const;
 110
 111     /// Random access to the stored C string.
 112     CharType operator[](size_t n) const;
 113 };
 114
 115 /// Scoped char buffer.
 116 typedef wxScopedCharTypeBuffer<char> wxScopedCharBuffer;
 117
 118 /// Scoped wchar_t buffer.
 119 typedef wxScopedCharTypeBuffer<wchar_t> wxScopedWCharBuffer;
 120
 121 /**
 122     wxCharTypeBuffer<T> is a template class for storing characters.
 123
 124     The difference from wxScopedCharTypeBuffer<T> is that this class
 125     doesn't have non-owned mode and the data stored in it are valid for
 126     as long as the buffer instance exists. Other than that, this class'
 127     behaviour is the same as wxScopedCharTypeBuffer<T>'s -- in particular,
 128     the data are reference-counted and copying the buffer is cheap.
 129
 130     wxScopedCharTypeBuffer<T> buffers can be converted into wxCharTypeBuffer<T>.
 131
 132     @tparam T
 133         The type of the characters stored in this class.
 134
 135     @since 2.9.0
 136
 137     @nolibrary
 138     @category{data}
 139 */
 140 template <typename T>
 141 class wxCharTypeBuffer : public wxScopedCharTypeBuffer<T>
 142 {
 143 public:
 144     /**
 145         Creates (owned) buffer from @a str and takes ownership of it.
 146
 147         @param str String data.
 148         @param len If specified, length of the string, otherwise the string
 149                    is considered to be NUL-terminated.
 150
 151         @see wxScopedCharTypeBuffer<T>::CreateOwned()
 152      */
 153     wxCharTypeBuffer(const CharType *str = NULL, size_t len = wxNO_LEN);
 154
 155
 156     /**
 157         Creates (owned) buffer of size @a len.
 158
 159         @see wxScopedCharTypeBuffer<T>::CreateOwned()
 160      */
 161     wxCharTypeBuffer(size_t len);
 162
 163     /**
 164         Copy constructor.
 165
 166         Increases reference count on the data, does @em not make wxStrdup()
 167         copy of the data.
 168      */
 169     wxCharTypeBuffer(const wxCharTypeBuffer& src);
 170
 171     /**
 172         Makes a copy of scoped buffer @a src.
 173
 174         If @a src is a non-owned buffer, a copy of its data is made using
 175         wxStrdup(). If @a src is an owned buffer, this constructor behaves
 176         in the usual way (reference count on buffer data is incremented).
 177      */
 178     wxCharTypeBuffer(const wxScopedCharTypeBuffer<T>& src);
 179
 180     /**
 181         Assigns @a str to this buffer and takes ownership of it (i.e. the
 182         buffer becomes "owned").
 183      */
 184     wxCharTypeBuffer& operator=(const CharType *str);
 185
 186     /// Assignment operator behaves in the same way as the copy constructor.
 187     wxCharTypeBuffer& operator=(const wxCharTypeBuffer& src);
 188
 189     /**
 190         Assigns a scoped buffer to this buffer.
 191
 192         If @a src is a non-owned buffer, a copy of its data is made using
 193         wxStrdup(). If @a src is an owned buffer, the assignment behaves
 194         in the usual way (reference count on buffer data is incremented).
 195      */
 196     wxCharTypeBuffer& operator=(const wxScopedCharTypeBuffer<T>& src);
 197
 198     /**
 199         Extends the buffer to have size @a len.
 200
 201         Can only be called on buffers that don't share data with another
 202         buffer (i.e. reference count of the data is 1).
 203      */
 204     bool extend(size_t len);
 205 };
 206
 207 /**
 208     This is a specialization of wxCharTypeBuffer<T> for @c char type.
 209
 210     @nolibrary
 211     @category{data}
 212 */
 213 class wxCharBuffer : public wxCharTypeBuffer<char>
 214 {
 215 public:
 216     typedef wxCharTypeBuffer<char> wxCharTypeBufferBase;
 217     typedef wxScopedCharTypeBuffer<char> wxScopedCharTypeBufferBase;
 218
 219     wxCharBuffer(const wxCharTypeBufferBase& buf);
 220     wxCharBuffer(const wxScopedCharTypeBufferBase& buf);
 221     wxCharBuffer(const CharType *str = NULL);
 222     wxCharBuffer(size_t len);
 223     wxCharBuffer(const wxCStrData& cstr);
 224 };
 225
 226 /**
 227     This is a specialization of wxCharTypeBuffer<T> for @c wchar_t type.
 228
 229     @nolibrary
 230     @category{data}
 231 */
 232 class wxWCharBuffer : public wxCharTypeBuffer<wchar_t>
 233 {
 234 public:
 235     typedef wxCharTypeBuffer<wchar_t> wxCharTypeBufferBase;
 236     typedef wxScopedCharTypeBuffer<wchar_t> wxScopedCharTypeBufferBase;
 237
 238     wxWCharBuffer(const wxCharTypeBufferBase& buf);
 239     wxWCharBuffer(const wxScopedCharTypeBufferBase& buf);
 240     wxWCharBuffer(const CharType *str = NULL);
 241     wxWCharBuffer(size_t len);
 242     wxWCharBuffer(const wxCStrData& cstr);
 243 };
 244
 245 /**
 246     @class wxMemoryBuffer
 247
 248     A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized
 249     blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when
 250     the object is destroyed.
 251
 252     @library{wxbase}
 253     @category{data}
 254 */
 255 class wxMemoryBuffer
 256 {
 257 public:
 258     /**
 259         Copy constructor, refcounting is used for performance, but wxMemoryBuffer
 260         is not a copy-on-write structure so changes made to one buffer effect all
 261         copies made from it.
 262
 263         @see @ref overview_refcount
 264     */
 265     wxMemoryBuffer(const wxMemoryBuffer& src);
 266
 267     /**
 268         Create a new buffer.
 269
 270         @param size
 271             size of the new buffer.
 272     */
 273     wxMemoryBuffer(size_t size = DefBufSize);
 274
 275     /**
 276         Append a single byte to the buffer.
 277
 278         @param data
 279             New byte to append to the buffer.
 280     */
 281     void AppendByte(char data);
 282
 283     /**
 284         Ensure that the buffer is big enough and return a pointer to the start
 285         of the empty space in the buffer. This pointer can be used to directly
 286         write data into the buffer, this new data will be appended to the
 287         existing data.
 288
 289         @param sizeNeeded
 290             Amount of extra space required in the buffer for
 291             the append operation
 292     */
 293     void* GetAppendBuf(size_t sizeNeeded);
 294
 295     /**
 296         Returns the size of the buffer.
 297     */
 298     size_t GetBufSize() const;
 299
 300     /**
 301         Return a pointer to the data in the buffer.
 302     */
 303     void* GetData() const;
 304
 305     /**
 306         Returns the length of the valid data in the buffer.
 307     */
 308     size_t GetDataLen() const;
 309
 310     /**
 311         Ensure the buffer is big enough and return a pointer to the
 312         buffer which can be used to directly write into the buffer
 313         up to @a sizeNeeded bytes.
 314     */
 315     void* GetWriteBuf(size_t sizeNeeded);
 316
 317     /**
 318         Ensures the buffer has at least @a size bytes available.
 319     */
 320     void SetBufSize(size_t size);
 321
 322     /**
 323         Sets the length of the data stored in the buffer.
 324         Mainly useful for truncating existing data.
 325
 326         @param size
 327             New length of the valid data in the buffer. This is
 328             distinct from the allocated size
 329     */
 330     void SetDataLen(size_t size);
 331
 332     /**
 333         Update the length after completing a direct append, which
 334         you must have used GetAppendBuf() to initialise.
 335
 336         @param sizeUsed
 337             This is the amount of new data that has been
 338             appended.
 339     */
 340     void UngetAppendBuf(size_t sizeUsed);
 341
 342     /**
 343         Update the buffer after completing a direct write, which
 344         you must have used GetWriteBuf() to initialise.
 345
 346         @param sizeUsed
 347             The amount of data written in to buffer
 348             by the direct write
 349     */
 350     void UngetWriteBuf(size_t sizeUsed);
 351 };
 352