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