wxWidgets: wxScopedCharTypeBuffer< T > Class Template Reference

| Version: 3.2.2

Public Types | Public Member Functions | Static Public Member Functions | List of all members
wxScopedCharTypeBuffer< T > Class Template Reference
Class List by Category » Data Structures

`#include <wx/buffer.h>`

Inheritance diagram for wxScopedCharTypeBuffer< T >:
[legend]

## Detailed Description

### template<typename T>
class wxScopedCharTypeBuffer< T >

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 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).

Template Parameters

  T | The type of the characters stored in this class.

Since
  2.9.0

##

Library: None; this class implementation is entirely header-based.
Category: Data Structures

## Public Types
typedef T | CharType
| Stored characters type. More...

## Public Member Functions
| wxScopedCharTypeBuffer ()
| Default constructor, creates NULL buffer. More...
| wxScopedCharTypeBuffer (const wxScopedCharTypeBuffer &src)
| Copy constructor. More...
wxScopedCharTypeBuffer & | operator= (const wxScopedCharTypeBuffer &src)
| Assignment operator behaves in the same way as the copy constructor. More...
| ~wxScopedCharTypeBuffer ()
| Destructor. More...
CharType * | release () const
| Returns the internal pointer and resets the buffer. More...
void | reset ()
| Resets the buffer to NULL, freeing the data if necessary. More...
CharType * | data ()
| Returns pointer to the stored data. More...
const CharType * | data () const
| Returns const pointer to the stored data. More...
size_t | length () const
| Returns length of the string stored. More...
| operator const CharType * () const
| Implicit conversion to C string. More...
CharType | operator[] (size_t n) const
| Random access to the stored C string. More...

## Static Public Member Functions
static const wxScopedCharTypeBuffer | CreateNonOwned (const CharType *str, size_t len=wxNO_LEN)
| Creates non-owned buffer from string data str. More...
static const wxScopedCharTypeBuffer | CreateOwned (CharType *str, size_t len=wxNO_LEN)
| Creates owned buffer from str and takes ownership of it. More...

## Member Typedef Documentation

## ◆ CharType

template<typename T >

typedef T wxScopedCharTypeBuffer< T >::CharType

Stored characters type.

## Constructor & Destructor Documentation

## ◆ wxScopedCharTypeBuffer() [1/2]

template<typename T >

wxScopedCharTypeBuffer< T >::wxScopedCharTypeBuffer | ( |  | ) |

Default constructor, creates NULL buffer.

## ◆ wxScopedCharTypeBuffer() [2/2]

template<typename T >

wxScopedCharTypeBuffer< T >::wxScopedCharTypeBuffer | ( | const wxScopedCharTypeBuffer< T > & | src | ) |

Copy constructor.

Increases reference count on the data, does not make wxStrdup() copy of the data.

## ◆ ~wxScopedCharTypeBuffer()

template<typename T >

wxScopedCharTypeBuffer< T >::~wxScopedCharTypeBuffer | ( |  | ) |

Destructor.

Frees stored data if it is in "owned" mode and data's reference count reaches zero.

## Member Function Documentation

## ◆ CreateNonOwned()

template<typename T >

static const wxScopedCharTypeBuffer wxScopedCharTypeBuffer< T >::CreateNonOwned | ( | const CharType * | str,
|  | size_t | len = `wxNO_LEN`
| ) |  |
| static

Creates non-owned buffer from string data str.

The buffer's destructor will not destroy str. The returned buffer's data is valid only as long as str is valid.

Parameters

  str | String data.
  len | If specified, length of the string, otherwise the string is considered to be NUL-terminated.

## ◆ CreateOwned()

template<typename T >

static const wxScopedCharTypeBuffer wxScopedCharTypeBuffer< T >::CreateOwned | ( | CharType * | str,
|  | size_t | len = `wxNO_LEN`
| ) |  |
| static

Creates owned buffer from str and takes ownership of it.

The buffer's destructor will free str when its reference count reaches zero (initial count is 1).

Parameters

  str | String data.
  len | If specified, length of the string, otherwise the string is considered to be NUL-terminated.

## ◆ data() [1/2]

template<typename T >

CharType* wxScopedCharTypeBuffer< T >::data | ( |  | ) |

Returns pointer to the stored data.

## ◆ data() [2/2]

template<typename T >

const CharType* wxScopedCharTypeBuffer< T >::data | ( |  | ) | const

Returns const pointer to the stored data.

## ◆ length()

template<typename T >

size_t wxScopedCharTypeBuffer< T >::length | ( |  | ) | const

Returns length of the string stored.

## ◆ operator const CharType *()

template<typename T >

wxScopedCharTypeBuffer< T >::operator const CharType * | ( |  | ) | const

Implicit conversion to C string.

## ◆ operator=()

template<typename T >

wxScopedCharTypeBuffer& wxScopedCharTypeBuffer< T >::operator= | ( | const wxScopedCharTypeBuffer< T > & | src | ) |

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

## ◆ operator[]()

template<typename T >

CharType wxScopedCharTypeBuffer< T >::operator[] | ( | size_t | n | ) | const

Random access to the stored C string.

## ◆ release()

template<typename T >

CharType* wxScopedCharTypeBuffer< T >::release | ( |  | ) | const

Returns the internal pointer and resets the buffer.

It's the caller responsibility to deallocate the returned pointer using `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.

## ◆ reset()

template<typename T >

void wxScopedCharTypeBuffer< T >::reset | ( |  | ) |

Resets the buffer to NULL, freeing the data if necessary.