wxWidgets/interface/wx/buffer.h

415 lines
12 KiB
C
Raw Normal View History

/////////////////////////////////////////////////////////////////////////////
// Name: buffer.h
// Purpose: interface of wxMemoryBuffer
// Author: wxWidgets team
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
wxScopedCharTypeBuffer<T> is a template class for storing characters.
Data are stored in reference-counted buffer. In other words, making a copy
of wxScopedCharTypeBuffer<T> will @em not make another copy of the stored
string data, it will still point to the same location in memory.
wxScopedCharTypeBuffer<T> supports two storage modes: owned and non-owned.
"Owned" data buffer (created with CreateOwned() or wxCharTypeBuffer<T>
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<T>
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<T> instead of wxScopedCharTypeBuffer<T>. On the other
hand, use wxScopedCharTypeBuffer<T> 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 <typename T>
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();
/**
Returns the internal pointer and resets the buffer.
It's the caller responsibility to deallocate the returned pointer using
@c free() function.
Notice that this method is dangerous because it can only be called on a
non-shared owning buffer. Calling it on any other kind of buffer object
will result in a crash after the pointer is freed, so avoid using it
unless absolutely necessary and you are absolutely certain that the
buffer is not shared.
*/
CharType* release() const;
/// 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<char> wxScopedCharBuffer;
/// Scoped wchar_t buffer.
typedef wxScopedCharTypeBuffer<wchar_t> wxScopedWCharBuffer;
/**
wxCharTypeBuffer<T> is a template class for storing characters.
The difference from wxScopedCharTypeBuffer<T> 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<T>'s -- in particular,
the data are reference-counted and copying the buffer is cheap.
wxScopedCharTypeBuffer<T> buffers can be converted into wxCharTypeBuffer<T>.
@tparam T
The type of the characters stored in this class.
@since 2.9.0
@nolibrary
@category{data}
*/
template <typename T>
class wxCharTypeBuffer : public wxScopedCharTypeBuffer<T>
{
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<T>::CreateOwned()
*/
wxCharTypeBuffer(const CharType *str = NULL, size_t len = wxNO_LEN);
/**
Creates (owned) buffer of size @a len.
@see wxScopedCharTypeBuffer<T>::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<T>& 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<T>& 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<T> for @c char type.
@nolibrary
@category{data}
*/
class wxCharBuffer : public wxCharTypeBuffer<char>
{
public:
typedef wxCharTypeBuffer<char> wxCharTypeBufferBase;
typedef wxScopedCharTypeBuffer<char> 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<T> for @c wchar_t type.
@nolibrary
@category{data}
*/
class wxWCharBuffer : public wxCharTypeBuffer<wchar_t>
{
public:
typedef wxCharTypeBuffer<wchar_t> wxCharTypeBufferBase;
typedef wxScopedCharTypeBuffer<wchar_t> wxScopedCharTypeBufferBase;
wxWCharBuffer(const wxCharTypeBufferBase& buf);
wxWCharBuffer(const wxScopedCharTypeBufferBase& buf);
wxWCharBuffer(const CharType *str = NULL);
wxWCharBuffer(size_t len);
wxWCharBuffer(const wxCStrData& cstr);
};
/**
@class wxMemoryBuffer
A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized
blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when
the object is destroyed.
@library{wxbase}
@category{data}
*/
class wxMemoryBuffer
{
public:
/**
Copy constructor, refcounting is used for performance, but wxMemoryBuffer
is not a copy-on-write structure so changes made to one buffer effect all
copies made from it.
@see @ref overview_refcount
*/
wxMemoryBuffer(const wxMemoryBuffer& src);
/**
Create a new buffer.
@param size
size of the new buffer, 1KiB by default.
*/
wxMemoryBuffer(size_t size = 1024);
/**
Append a single byte to the buffer.
@param data
New byte to append to the buffer.
*/
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
write data into the buffer, this new data will be appended to the
existing data.
@param sizeNeeded
Amount of extra space required in the buffer for
the append operation
*/
void* GetAppendBuf(size_t sizeNeeded);
/**
Returns the size of the buffer.
*/
size_t GetBufSize() const;
/**
Return a pointer to the data in the buffer.
*/
void* GetData() const;
/**
Returns the length of the valid data in the buffer.
*/
size_t GetDataLen() const;
/**
Ensure the buffer is big enough and return a pointer to the
buffer which can be used to directly write into the buffer
up to @a sizeNeeded bytes.
*/
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.
*/
void SetBufSize(size_t size);
/**
Sets the length of the data stored in the buffer.
Mainly useful for truncating existing data.
@param size
New length of the valid data in the buffer. This is
distinct from the allocated size
*/
void SetDataLen(size_t size);
/**
Update the length after completing a direct append, which
you must have used GetAppendBuf() to initialise.
@param sizeUsed
This is the amount of new data that has been
appended.
*/
void UngetAppendBuf(size_t sizeUsed);
/**
Update the buffer after completing a direct write, which
you must have used GetWriteBuf() to initialise.
@param sizeUsed
The amount of data written in to buffer
by the direct write
*/
void UngetWriteBuf(size_t sizeUsed);
};