Make storing non-trivial data in wxThreadSpecificInfo possible.

[wxWidgets.git] / interface / wx / buffer.h

diff --git a/interface/wx/buffer.h b/interface/wx/buffer.h
index d8766639b0b3e9affdf68bd698563f06764dfce3..8ab9dce8aade433b24a8b10ac6b22294225c6827 100644 (file)
--- a/interface/wx/buffer.h
+++ b/interface/wx/buffer.h
@@ -2,51 +2,229 @@
 // Name:        buffer.h
 // Purpose:     interface of wxMemoryBuffer
 // Author:      wxWidgets team
 // Name:        buffer.h
 // Purpose:     interface of wxMemoryBuffer
 // Author:      wxWidgets team

-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 
 /**

-    wxCharTypeBuffer<T> is a template class for storing characters.
+    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.

 
 

-    @todo provide better docs for this class
+    "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.
 
 
     @tparam T
         The type of the characters stored in this class.
 

+    @since 2.9.0
+

     @nolibrary
     @category{data}
 */
 template <typename T>
     @nolibrary
     @category{data}
 */
 template <typename T>

-class wxCharTypeBuffer
+class wxScopedCharTypeBuffer

 {
 public:
 {
 public:

+    /// Stored characters type.

     typedef T CharType;
 
     typedef T CharType;
 

-    wxCharTypeBuffer(const CharType *str = NULL);
+    /// 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<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);
     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);
     wxCharTypeBuffer(const wxCharTypeBuffer& src);

-    ~wxCharTypeBuffer();

 
 

-    void reset();
+    /**
+        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);
     wxCharTypeBuffer& operator=(const CharType *str);

+
+    /// Assignment operator behaves in the same way as the copy constructor.

     wxCharTypeBuffer& operator=(const wxCharTypeBuffer& src);
 
     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);
 
     bool extend(size_t len);
 

-    CharType *data();
-    const CharType *data() const;
-    operator const CharType *() const;
-    CharType operator[](size_t n) const;
+    /**
+        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.
 
 };
 
 /**
     This is a specialization of wxCharTypeBuffer<T> for @c char type.
 

-    @todo provide better docs for this class
-

     @nolibrary
     @category{data}
 */
     @nolibrary
     @category{data}
 */


@@ -54,8 +232,10 @@ class wxCharBuffer : public wxCharTypeBuffer<char>
 {
 public:
     typedef wxCharTypeBuffer<char> wxCharTypeBufferBase;
 {
 public:
     typedef wxCharTypeBuffer<char> wxCharTypeBufferBase;

+    typedef wxScopedCharTypeBuffer<char> wxScopedCharTypeBufferBase;

 
     wxCharBuffer(const wxCharTypeBufferBase& buf);
 
     wxCharBuffer(const wxCharTypeBufferBase& buf);

+    wxCharBuffer(const wxScopedCharTypeBufferBase& buf);

     wxCharBuffer(const CharType *str = NULL);
     wxCharBuffer(size_t len);
     wxCharBuffer(const wxCStrData& cstr);
     wxCharBuffer(const CharType *str = NULL);
     wxCharBuffer(size_t len);
     wxCharBuffer(const wxCStrData& cstr);


@@ -63,7 +243,6 @@ public:
 
 /**
     This is a specialization of wxCharTypeBuffer<T> for @c wchar_t type.
 
 /**
     This is a specialization of wxCharTypeBuffer<T> for @c wchar_t type.

-    This class is available only when <tt>wxUSE_WCHAR_T==1</tt>

 
     @nolibrary
     @category{data}
 
     @nolibrary
     @category{data}


@@ -72,8 +251,10 @@ class wxWCharBuffer : public wxCharTypeBuffer<wchar_t>
 {
 public:
     typedef wxCharTypeBuffer<wchar_t> wxCharTypeBufferBase;
 {
 public:
     typedef wxCharTypeBuffer<wchar_t> wxCharTypeBufferBase;

+    typedef wxScopedCharTypeBuffer<wchar_t> wxScopedCharTypeBufferBase;

 
     wxWCharBuffer(const wxCharTypeBufferBase& buf);
 
     wxWCharBuffer(const wxCharTypeBufferBase& buf);

+    wxWCharBuffer(const wxScopedCharTypeBufferBase& buf);

     wxWCharBuffer(const CharType *str = NULL);
     wxWCharBuffer(size_t len);
     wxWCharBuffer(const wxCStrData& cstr);
     wxWCharBuffer(const CharType *str = NULL);
     wxWCharBuffer(size_t len);
     wxWCharBuffer(const wxCStrData& cstr);


@@ -105,9 +286,9 @@ public:
         Create a new buffer.
 
         @param size
         Create a new buffer.
 
         @param size

-            size of the new buffer.
+            size of the new buffer, 1KiB by default.

     */
     */

-    wxMemoryBuffer(size_t size = DefBufSize);
+    wxMemoryBuffer(size_t size = 1024);

 
     /**
         Append a single byte to the buffer.
 
     /**
         Append a single byte to the buffer.


@@ -117,6 +298,27 @@ public:
     */
     void AppendByte(char data);
 
     */
     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
     /**
         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


@@ -151,6 +353,15 @@ public:
     */
     void* GetWriteBuf(size_t sizeNeeded);
 
     */
     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.
     */
     /**
         Ensures the buffer has at least @a size bytes available.
     */