interface/wx/buffer.h

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