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 licence
   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(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         @see shrink()
 205      */
 206     bool extend(size_t len);
 207
 208     /**
 209         Shrinks the buffer to have size @a len and NUL-terminates the string
 210         at this length.
 211
 212         Can only be called on buffers that don't share data with another
 213         buffer (i.e. reference count of the data is 1).
 214
 215         @param len Length to shrink to. Must not be larger than current length.
 216
 217         @note The string is not reallocated to take less memory.
 218
 219         @since 2.9.0
 220
 221         @see extend()
 222      */
 223     bool shrink(size_t len);
 224 };
 225
 226 /**
 227     This is a specialization of wxCharTypeBuffer<T> for @c char type.
 228
 229     @nolibrary
 230     @category{data}
 231 */
 232 class wxCharBuffer : public wxCharTypeBuffer<char>
 233 {
 234 public:
 235     typedef wxCharTypeBuffer<char> wxCharTypeBufferBase;
 236     typedef wxScopedCharTypeBuffer<char> wxScopedCharTypeBufferBase;
 237
 238     wxCharBuffer(const wxCharTypeBufferBase& buf);
 239     wxCharBuffer(const wxScopedCharTypeBufferBase& buf);
 240     wxCharBuffer(const CharType *str = NULL);
 241     wxCharBuffer(size_t len);
 242     wxCharBuffer(const wxCStrData& cstr);
 243 };
 244
 245 /**
 246     This is a specialization of wxCharTypeBuffer<T> for @c wchar_t type.
 247
 248     @nolibrary
 249     @category{data}
 250 */
 251 class wxWCharBuffer : public wxCharTypeBuffer<wchar_t>
 252 {
 253 public:
 254     typedef wxCharTypeBuffer<wchar_t> wxCharTypeBufferBase;
 255     typedef wxScopedCharTypeBuffer<wchar_t> wxScopedCharTypeBufferBase;
 256
 257     wxWCharBuffer(const wxCharTypeBufferBase& buf);
 258     wxWCharBuffer(const wxScopedCharTypeBufferBase& buf);
 259     wxWCharBuffer(const CharType *str = NULL);
 260     wxWCharBuffer(size_t len);
 261     wxWCharBuffer(const wxCStrData& cstr);
 262 };
 263
 264 /**
 265     @class wxMemoryBuffer
 266
 267     A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized
 268     blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when
 269     the object is destroyed.
 270
 271     @library{wxbase}
 272     @category{data}
 273 */
 274 class wxMemoryBuffer
 275 {
 276 public:
 277     /**
 278         Copy constructor, refcounting is used for performance, but wxMemoryBuffer
 279         is not a copy-on-write structure so changes made to one buffer effect all
 280         copies made from it.
 281
 282         @see @ref overview_refcount
 283     */
 284     wxMemoryBuffer(const wxMemoryBuffer& src);
 285
 286     /**
 287         Create a new buffer.
 288
 289         @param size
 290             size of the new buffer, 1KiB by default.
 291     */
 292     wxMemoryBuffer(size_t size = 1024);
 293
 294     /**
 295         Append a single byte to the buffer.
 296
 297         @param data
 298             New byte to append to the buffer.
 299     */
 300     void AppendByte(char data);
 301
 302     /**
 303         Single call to append a data block to the buffer.
 304
 305         @param data
 306             Pointer to block to append to the buffer.
 307         @param len
 308             Length of data to append.
 309     */
 310     void AppendData(const void *data, size_t len);
 311
 312     /**
 313         Clear the buffer contents.
 314
 315         The buffer won't contain any data after this method is called.
 316
 317         @see IsEmpty()
 318
 319         @since 2.9.4
 320      */
 321     void Clear();
 322
 323     /**
 324         Ensure that the buffer is big enough and return a pointer to the start
 325         of the empty space in the buffer. This pointer can be used to directly
 326         write data into the buffer, this new data will be appended to the
 327         existing data.
 328
 329         @param sizeNeeded
 330             Amount of extra space required in the buffer for
 331             the append operation
 332     */
 333     void* GetAppendBuf(size_t sizeNeeded);
 334
 335     /**
 336         Returns the size of the buffer.
 337     */
 338     size_t GetBufSize() const;
 339
 340     /**
 341         Return a pointer to the data in the buffer.
 342     */
 343     void* GetData() const;
 344
 345     /**
 346         Returns the length of the valid data in the buffer.
 347     */
 348     size_t GetDataLen() const;
 349
 350     /**
 351         Ensure the buffer is big enough and return a pointer to the
 352         buffer which can be used to directly write into the buffer
 353         up to @a sizeNeeded bytes.
 354     */
 355     void* GetWriteBuf(size_t sizeNeeded);
 356
 357     /**
 358         Returns true if the buffer contains no data.
 359
 360         @see Clear()
 361
 362         @since 2.9.4
 363      */
 364     bool IsEmpty() const;
 365
 366     /**
 367         Ensures the buffer has at least @a size bytes available.
 368     */
 369     void SetBufSize(size_t size);
 370
 371     /**
 372         Sets the length of the data stored in the buffer.
 373         Mainly useful for truncating existing data.
 374
 375         @param size
 376             New length of the valid data in the buffer. This is
 377             distinct from the allocated size
 378     */
 379     void SetDataLen(size_t size);
 380
 381     /**
 382         Update the length after completing a direct append, which
 383         you must have used GetAppendBuf() to initialise.
 384
 385         @param sizeUsed
 386             This is the amount of new data that has been
 387             appended.
 388     */
 389     void UngetAppendBuf(size_t sizeUsed);
 390
 391     /**
 392         Update the buffer after completing a direct write, which
 393         you must have used GetWriteBuf() to initialise.
 394
 395         @param sizeUsed
 396             The amount of data written in to buffer
 397             by the direct write
 398     */
 399     void UngetWriteBuf(size_t sizeUsed);
 400 };
 401