Loading...
Searching...
No Matches
mqtt::buffer_ref< T > Class Template Reference

`#include <buffer_ref.h>`

## Public Types

using | value_type = T
using | blob = std::basic_string<value_type>
using | pointer_type = std::shared_ptr<const blob>

## Public Member Functions

| buffer_ref ()=default
| buffer_ref (const buffer_ref &buf)=default
| buffer_ref (buffer_ref &&buf)=default
| buffer_ref (const blob &b)
| buffer_ref (blob &&b)
| buffer_ref (const pointer_type &p)
| buffer_ref (pointer_type &&p)
| buffer_ref (const value_type *buf, size_t n)
| buffer_ref (const char *buf)
buffer_ref & | operator= (const buffer_ref &rhs)=default
buffer_ref & | operator= (buffer_ref &&rhs)=default
buffer_ref & | operator= (const blob &b)
buffer_ref & | operator= (blob &&b)
buffer_ref & | operator= (const char *cstr)
template<typename OT>
buffer_ref & | operator= (const buffer_ref< OT > &rhs)
void | reset ()
| operator bool () const
bool | is_null () const
bool | empty () const
const value_type * | data () const
size_t | size () const
size_t | length () const
const blob & | str () const
const blob & | to_string () const
const char * | c_str () const
const pointer_type & | ptr () const
const value_type & | operator[] (size_t i) const

## 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

## value_type

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.

## blob

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.

## pointer_type

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.

## Constructor & Destructor Documentation

## buffer_ref() [1/9]

template<typename T>

mqtt::buffer_ref< T >::buffer_ref | ( |  | ) |

default

Default constructor creates a null reference.

## buffer_ref() [2/9]

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.

## buffer_ref() [3/9]

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.

## buffer_ref() [4/9]

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.

## buffer_ref() [5/9]

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.

## buffer_ref() [6/9]

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.

## buffer_ref() [7/9]

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.

## buffer_ref() [8/9]

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.

## buffer_ref() [9/9]

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

## operator=() [1/6]

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

## operator=() [2/6]

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.

## operator=() [3/6]

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.

## operator=() [4/6]

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.

## operator=() [5/6]

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

## operator=() [6/6]

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.

## reset()

template<typename T>

void mqtt::buffer_ref< T >::reset | ( |  | ) |

inline

Clears the reference to nil.

## operator bool()

template<typename T>

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

inline explicit

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.

## is_null()

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,

## empty()

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 the reference is null, false if the buffer contains data.

## data()

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.

## size()

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.

## length()

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.

## str()

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.

## to_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.

## c_str()

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.

## ptr()

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.

## operator[]()

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.

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

- buffer_ref.h