mqtt::buffer_ref< T > Class Template Reference

A reference object for holding immutable data buffers, with cheap copy semantics and lifetime management. More...

#include <buffer_ref.h>

Public Types
using	value_type = T
	The underlying type for the buffer. More...
using	blob = std::basic_string< value_type >
	The type for the buffer. More...
using	pointer_type = std::shared_ptr< const blob >
	The pointer we use. More...

Public Member Functions
	buffer_ref ()=default
	Default constructor creates a null reference.
	buffer_ref (const buffer_ref &buf)=default
	Copy constructor only copies a shared pointer. More...
	buffer_ref (buffer_ref &&buf)=default
	Move constructor only moves a shared pointer. More...
	buffer_ref (const blob &b)
	Creates a reference to a new buffer by copying data. More...
	buffer_ref (blob &&b)
	Creates a reference to a new buffer by moving a string into the buffer. More...
	buffer_ref (const pointer_type &p)
	Creates a reference to an existing buffer by copying the shared pointer. More...
	buffer_ref (pointer_type &&p)
	Creates a reference to an existing buffer by moving the shared pointer. More...
	buffer_ref (const value_type *buf, size_t n)
	Creates a reference to a new buffer containing a copy of the data. More...
	buffer_ref (const char *buf)
	Creates a reference to a new buffer containing a copy of the NUL-terminated char array. More...
buffer_ref &	operator= (const buffer_ref &rhs)=default
	Copy the reference to the buffer. More...
buffer_ref &	operator= (buffer_ref &&rhs)=default
	Move a reference to a buffer. More...
buffer_ref &	operator= (const blob &b)
	Copy a string into this object, creating a new buffer. More...
buffer_ref &	operator= (blob &&b)
	Move a string into this object, creating a new buffer. More...
buffer_ref &	operator= (const char *cstr)
	Copy a NUL-terminated C char array into a new buffer. More...
template<typename OT >
buffer_ref &	operator= (const buffer_ref< OT > &rhs)
	Copy another type of buffer reference to this one. More...
void	reset ()
	Clears the reference to nil.
	operator bool () const
	Determines if the reference is valid. More...
bool	is_null () const
	Determines if the reference is invalid. More...
bool	empty () const
	Determines if the buffer is empty. More...
const value_type *	data () const
	Gets a const pointer to the data buffer. More...
size_t	size () const
	Gets the size of the data buffer. More...
size_t	length () const
	Gets the size of the data buffer. More...
const blob &	str () const
	Gets the data buffer as a string. More...
const blob &	to_string () const
	Gets the data buffer as a string. More...
const char *	c_str () const
	Gets the data buffer as NUL-terminated C string. More...
const pointer_type &	ptr () const
	Gets a shared pointer to the (const) data buffer. More...
const value_type &	operator[] (size_t i) const
	Gets elemental access to the data buffer (read only) More...

Detailed Description

template<typename T>
class mqtt::buffer_ref< T >

A reference object for holding immutable data buffers, with cheap copy semantics and lifetime management.

Each object of this class contains a reference-counted pointer to an immutable data buffer. Objects can be copied freely and easily, even across threads, since all instances promise not to modify the contents of the buffer.

The buffer is immutable but the reference itself acts like a normal variable. It can be reassigned to point to a different buffer.

If no value has been assigned to a reference, then it is in a default "null" state. It is not safe to call any member functions on a null reference, other than to check if the object is null or empty.

* string_ref sr;
* if (!sr)
*   cout << "null reference" << endl;
* else
*   cout.write(sr.data(), sr.size());
* 

Member Typedef Documentation

template<typename T>

using mqtt::buffer_ref< T >::blob = std::basic_string<value_type>

The type for the buffer.

We use basic_string for compatibility with string data.

template<typename T>

using mqtt::buffer_ref< T >::pointer_type = std::shared_ptr<const blob>

The pointer we use.

Note that it is a pointer to a const blob.

template<typename T>

using mqtt::buffer_ref< T >::value_type = T

The underlying type for the buffer.

Normally byte-wide data (char or uint8_t) for Paho.

Constructor & Destructor Documentation

template<typename T>

mqtt::buffer_ref< T >::buffer_ref ( const buffer_ref< T > &  buf )

default

Copy constructor only copies a shared pointer.

Parameters

buf	Another buffer reference.

template<typename T>

mqtt::buffer_ref< T >::buffer_ref ( buffer_ref< T > &&  buf )

default

Move constructor only moves a shared pointer.

Parameters

buf	Another buffer reference.

template<typename T>

mqtt::buffer_ref< T >::buffer_ref ( const blob &  b )

inline

Creates a reference to a new buffer by copying data.

Parameters

b	A string from which to create a new buffer.

template<typename T>

mqtt::buffer_ref< T >::buffer_ref ( blob &&  b )

inline

Creates a reference to a new buffer by moving a string into the buffer.

Parameters

b	A string from which to create a new buffer.

template<typename T>

mqtt::buffer_ref< T >::buffer_ref ( const pointer_type &  p )

inline

Creates a reference to an existing buffer by copying the shared pointer.

Note that it is up to the caller to insure that there are no mutable references to the buffer.

Parameters

p	A shared pointer to a string.

template<typename T>

mqtt::buffer_ref< T >::buffer_ref ( pointer_type &&  p )

inline

Creates a reference to an existing buffer by moving the shared pointer.

Note that it is up to the caller to insure that there are no mutable references to the buffer.

Parameters

p	A shared pointer to a string.

template<typename T>

mqtt::buffer_ref< T >::buffer_ref ( const value_type *  buf, size_t  n  )

inline

Creates a reference to a new buffer containing a copy of the data.

Parameters

buf	The memory to copy
n	The number of bytes to copy.

template<typename T>

mqtt::buffer_ref< T >::buffer_ref ( const char *  buf )

inline

Creates a reference to a new buffer containing a copy of the NUL-terminated char array.

Parameters

buf	A NUL-terminated char array (C string).

Member Function Documentation

template<typename T>

const char* mqtt::buffer_ref< T >::c_str ( ) const

inline

Gets the data buffer as NUL-terminated C string.

Note that the reference must be set to call this function.

Returns

The data buffer as a string.

template<typename T>

const value_type* mqtt::buffer_ref< T >::data ( ) const

inline

Gets a const pointer to the data buffer.

Returns

A pointer to the data buffer.

template<typename T>

bool mqtt::buffer_ref< T >::empty ( ) const

inline

Determines if the buffer is empty.

Returns

true if the buffer is empty or thr reference is null, false if the buffer contains data.

template<typename T>

bool mqtt::buffer_ref< T >::is_null ( ) const

inline

Determines if the reference is invalid.

If the reference is invalid then it is not safe to call any member functions other than is_null() and empty()

Returns

true if the reference is null, false if it is referring to a valid buffer,

template<typename T>

size_t mqtt::buffer_ref< T >::length ( ) const

inline

Gets the size of the data buffer.

Returns

The size of the data buffer.

template<typename T>

mqtt::buffer_ref< T >::operator bool ( ) const

inlineexplicit

Determines if the reference is valid.

If the reference is invalid then it is not safe to call any member functions other than is_null() and empty()

Returns

true if referring to a valid buffer, false if the reference (pointer) is null.

template<typename T>

buffer_ref& mqtt::buffer_ref< T >::operator= ( const buffer_ref< T > &  rhs )

default

Copy the reference to the buffer.

Parameters

rhs	Another buffer

Returns

A reference to this object

template<typename T>

buffer_ref& mqtt::buffer_ref< T >::operator= ( buffer_ref< T > &&  rhs )

default

Move a reference to a buffer.

Parameters

rhs	The other reference to move.

Returns

A reference to this object.

template<typename T>

buffer_ref& mqtt::buffer_ref< T >::operator= ( const blob &  b )

inline

Copy a string into this object, creating a new buffer.

Modifies the reference for this object, pointing it to a newly-created buffer. Other references to the old object remain unchanges, so this follows copy-on-write semantics.

Parameters

b	A new blob/string to copy.

Returns

A reference to this object.

template<typename T>

buffer_ref& mqtt::buffer_ref< T >::operator= ( blob &&  b )

inline

Move a string into this object, creating a new buffer.

Modifies the reference for this object, pointing it to a newly-created buffer. Other references to the old object remain unchanges, so this follows copy-on-write semantics.

Parameters

b	A new blob/string to move.

Returns

A reference to this object.

template<typename T>

buffer_ref& mqtt::buffer_ref< T >::operator= ( const char *  cstr )

inline

Copy a NUL-terminated C char array into a new buffer.

Parameters

cstr	A NUL-terminated C string.

Returns

A reference to this object

template<typename T>

template<typename OT >

buffer_ref& mqtt::buffer_ref< T >::operator= ( const buffer_ref< OT > &  rhs )

inline

Copy another type of buffer reference to this one.

This can copy a buffer of different types, provided that the size of the data elements are the same. This is typically used to convert from char to byte, where the data is the same, but the interpretation is different. Note that this copies the underlying buffer.

Parameters

rhs	A reference to a different type of buffer.

Returns

A reference to this object.

template<typename T>

const value_type& mqtt::buffer_ref< T >::operator[] ( size_t  i ) const

inline

Gets elemental access to the data buffer (read only)

Parameters

i	The index into the buffer.

Returns

The value at the specified index.

template<typename T>

const pointer_type& mqtt::buffer_ref< T >::ptr ( ) const

inline

Gets a shared pointer to the (const) data buffer.

Returns

A shared pointer to the (const) data buffer.

template<typename T>

size_t mqtt::buffer_ref< T >::size ( ) const

inline

Gets the size of the data buffer.

Returns

The size of the data buffer.

template<typename T>

const blob& mqtt::buffer_ref< T >::str ( ) const

inline

Gets the data buffer as a string.

Returns

The data buffer as a string.

template<typename T>

const blob& mqtt::buffer_ref< T >::to_string ( ) const

inline

Gets the data buffer as a string.

Returns

The data buffer as a string.

---

The documentation for this class was generated from the following file:

• src/mqtt/buffer_ref.h