X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/buffer.h diff --git a/interface/wx/buffer.h b/interface/wx/buffer.h index 830330adfc..8ab9dce8aa 100644 --- a/interface/wx/buffer.h +++ b/interface/wx/buffer.h @@ -2,10 +2,264 @@ // Name: buffer.h // Purpose: interface of wxMemoryBuffer // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + +/** + wxScopedCharTypeBuffer is a template class for storing characters. + + Data are stored in reference-counted buffer. In other words, making a copy + of wxScopedCharTypeBuffer will @em not make another copy of the stored + string data, it will still point to the same location in memory. + + wxScopedCharTypeBuffer supports two storage modes: owned and non-owned. + "Owned" data buffer (created with CreateOwned() or wxCharTypeBuffer + derived class) owns the data and frees them when the last buffer pointing + to them is destroyed. + + "Non-owned" buffer (created with CreateNonOwned()), on the other hand, + references data owned by somebody else -- typical use is by + wxString::mb_str() or wxString::wc_str(), which may return non-owned buffer + pointing to wxString's internal store. + + Because of this, the validity of data stored in wxScopedCharTypeBuffer + is limited by the lifetime of the "parent" object that created the + buffer (e.g. the wxString on which mb_str() was called). + + If you need to preserve the data for longer, assign it to + wxCharTypeBuffer instead of wxScopedCharTypeBuffer. On the other + hand, use wxScopedCharTypeBuffer if the buffer is to be destroyed before + the "parent" object -- typical use would be creating it on the stack and + destroying when it goes out of scope (hence the class' name). + + @tparam T + The type of the characters stored in this class. + + @since 2.9.0 + + @nolibrary + @category{data} +*/ +template +class wxScopedCharTypeBuffer +{ +public: + /// Stored characters type. + typedef T CharType; + + /// Default constructor, creates NULL buffer. + wxScopedCharTypeBuffer(); + + /** + Creates non-owned buffer from string data @a str. + + The buffer's destructor will not destroy @a str. The returned buffer's + data is valid only as long as @a str is valid. + + @param str String data. + @param len If specified, length of the string, otherwise the string + is considered to be NUL-terminated. + */ + static const wxScopedCharTypeBuffer CreateNonOwned(const CharType *str, size_t len = wxNO_LEN); + + /** + Creates owned buffer from @a str and takes ownership of it. + + The buffer's destructor will free @a str when its reference count + reaches zero (initial count is 1). + + @param str String data. + @param len If specified, length of the string, otherwise the string + is considered to be NUL-terminated. + */ + static const wxScopedCharTypeBuffer CreateOwned(CharType *str, size_t len = wxNO_LEN); + + /** + Copy constructor. + + Increases reference count on the data, does @em not make wxStrdup() + copy of the data. + */ + wxScopedCharTypeBuffer(const wxScopedCharTypeBuffer& src); + + /// Assignment operator behaves in the same way as the copy constructor. + wxScopedCharTypeBuffer& operator=(const wxScopedCharTypeBuffer& src); + + /** + Destructor. Frees stored data if it is in "owned" mode and data's + reference count reaches zero. + */ + ~wxScopedCharTypeBuffer(); + + /// Resets the buffer to NULL, freeing the data if necessary. + void reset(); + + /// Returns pointer to the stored data. + CharType *data(); + + /// Returns const pointer to the stored data. + const CharType *data() const; + + /// Returns length of the string stored. + size_t length() const; + + /// Implicit conversion to C string. + operator const CharType *() const; + + /// Random access to the stored C string. + CharType operator[](size_t n) const; +}; + +/// Scoped char buffer. +typedef wxScopedCharTypeBuffer wxScopedCharBuffer; + +/// Scoped wchar_t buffer. +typedef wxScopedCharTypeBuffer wxScopedWCharBuffer; + +/** + wxCharTypeBuffer is a template class for storing characters. + + The difference from wxScopedCharTypeBuffer is that this class + doesn't have non-owned mode and the data stored in it are valid for + as long as the buffer instance exists. Other than that, this class' + behaviour is the same as wxScopedCharTypeBuffer's -- in particular, + the data are reference-counted and copying the buffer is cheap. + + wxScopedCharTypeBuffer buffers can be converted into wxCharTypeBuffer. + + @tparam T + The type of the characters stored in this class. + + @since 2.9.0 + + @nolibrary + @category{data} +*/ +template +class wxCharTypeBuffer : public wxScopedCharTypeBuffer +{ +public: + /** + Creates (owned) buffer from @a str and takes ownership of it. + + @param str String data. + @param len If specified, length of the string, otherwise the string + is considered to be NUL-terminated. + + @see wxScopedCharTypeBuffer::CreateOwned() + */ + wxCharTypeBuffer(const CharType *str = NULL, size_t len = wxNO_LEN); + + + /** + Creates (owned) buffer of size @a len. + + @see wxScopedCharTypeBuffer::CreateOwned() + */ + wxCharTypeBuffer(size_t len); + + /** + Copy constructor. + + Increases reference count on the data, does @em not make wxStrdup() + copy of the data. + */ + wxCharTypeBuffer(const wxCharTypeBuffer& src); + + /** + Makes a copy of scoped buffer @a src. + + If @a src is a non-owned buffer, a copy of its data is made using + wxStrdup(). If @a src is an owned buffer, this constructor behaves + in the usual way (reference count on buffer data is incremented). + */ + wxCharTypeBuffer(const wxScopedCharTypeBuffer& src); + + /** + Assigns @a str to this buffer and takes ownership of it (i.e.\ the + buffer becomes "owned"). + */ + wxCharTypeBuffer& operator=(const CharType *str); + + /// Assignment operator behaves in the same way as the copy constructor. + wxCharTypeBuffer& operator=(const wxCharTypeBuffer& src); + + /** + Assigns a scoped buffer to this buffer. + + If @a src is a non-owned buffer, a copy of its data is made using + wxStrdup(). If @a src is an owned buffer, the assignment behaves + in the usual way (reference count on buffer data is incremented). + */ + wxCharTypeBuffer& operator=(const wxScopedCharTypeBuffer& src); + + /** + Extends the buffer to have size @a len. + + Can only be called on buffers that don't share data with another + buffer (i.e. reference count of the data is 1). + + @see shrink() + */ + bool extend(size_t len); + + /** + Shrinks the buffer to have size @a len and NUL-terminates the string + at this length. + + Can only be called on buffers that don't share data with another + buffer (i.e. reference count of the data is 1). + + @param len Length to shrink to. Must not be larger than current length. + + @note The string is not reallocated to take less memory. + + @since 2.9.0 + + @see extend() + */ + bool shrink(size_t len); +}; + +/** + This is a specialization of wxCharTypeBuffer for @c char type. + + @nolibrary + @category{data} +*/ +class wxCharBuffer : public wxCharTypeBuffer +{ +public: + typedef wxCharTypeBuffer wxCharTypeBufferBase; + typedef wxScopedCharTypeBuffer wxScopedCharTypeBufferBase; + + wxCharBuffer(const wxCharTypeBufferBase& buf); + wxCharBuffer(const wxScopedCharTypeBufferBase& buf); + wxCharBuffer(const CharType *str = NULL); + wxCharBuffer(size_t len); + wxCharBuffer(const wxCStrData& cstr); +}; + +/** + This is a specialization of wxCharTypeBuffer for @c wchar_t type. + + @nolibrary + @category{data} +*/ +class wxWCharBuffer : public wxCharTypeBuffer +{ +public: + typedef wxCharTypeBuffer wxCharTypeBufferBase; + typedef wxScopedCharTypeBuffer wxScopedCharTypeBufferBase; + + wxWCharBuffer(const wxCharTypeBufferBase& buf); + wxWCharBuffer(const wxScopedCharTypeBufferBase& buf); + wxWCharBuffer(const CharType *str = NULL); + wxWCharBuffer(size_t len); + wxWCharBuffer(const wxCStrData& cstr); +}; + /** @class wxMemoryBuffer @@ -32,9 +286,9 @@ public: Create a new buffer. @param size - size of the new buffer. + size of the new buffer, 1KiB by default. */ - wxMemoryBuffer(size_t size); + wxMemoryBuffer(size_t size = 1024); /** Append a single byte to the buffer. @@ -44,6 +298,27 @@ public: */ void AppendByte(char data); + /** + Single call to append a data block to the buffer. + + @param data + Pointer to block to append to the buffer. + @param len + Length of data to append. + */ + void AppendData(const void *data, size_t len); + + /** + Clear the buffer contents. + + The buffer won't contain any data after this method is called. + + @see IsEmpty() + + @since 2.9.4 + */ + void Clear(); + /** Ensure that the buffer is big enough and return a pointer to the start of the empty space in the buffer. This pointer can be used to directly @@ -78,6 +353,15 @@ public: */ void* GetWriteBuf(size_t sizeNeeded); + /** + Returns true if the buffer contains no data. + + @see Clear() + + @since 2.9.4 + */ + bool IsEmpty() const; + /** Ensures the buffer has at least @a size bytes available. */