Loading...
Searching...
No Matches
bsoncxx::v1::document::value Class Reference

`#include <bsoncxx/v1/document/value.hpp>`

## Description

A BSON document.

## Public Types

using | const_iterator = v1::document::view::const_iterator
| A const iterator over the elements of a view.
using | default_deleter_type = std::default_delete<std::uint8_t[]>
| The deleter used to free copied BSON bytes when a user-provided deleter is not specified.
using | deleter_type = std::function<void (std::uint8_t*)>
| The type of the deleter used to free the underlying BSON bytes.
using | iterator = const_iterator
| Equivalent to const_iterator.
using | noop_deleter_type = void( *)(std::uint8_t*)
| The type of a pointer to noop_deleter.
using | unique_ptr_type = std::unique_ptr<std::uint8_t[], deleter_type>
| The type of the unique pointer used to manage the underlying BSON bytes.

## Public Member Functions

| value ()
| Initialize as an empty document (or array).
| value (std::uint8_t *data)
| Initialize as owning data which will be freed with default_deleter_type.
template<typename Deleter, detail::enable_if_t< is_valid_deleter< Deleter >::value > * = nullptr>
| value (std::uint8_t *data, Deleter deleter)
| Initialize as owning data which will be freed with deleter.
| value (std::uint8_t *data, std::size_t length)
| Equivalent to value(std::uint8_t* data), but validates the embedded length against length.
template<typename Deleter, detail::enable_if_t< is_valid_deleter< Deleter >::value > * = nullptr>
| value (std::uint8_t *data, std::size_t length, Deleter deleter)
| Equivalent to value(std::uint8_t* data, Deleter deleter), but validates the embedded length against length.
template<typename T, detail::enable_if_t< has_to_bson< T >::value > * = nullptr>
| value (T const &v)
| Equivalent to to_bson(v, *this); after default-initialization.
| value (unique_ptr_type ptr)
| Initialize as owning ptr.
| value (unique_ptr_type ptr, std::size_t length)
| Equivalent to value(unique_ptr_type ptr), but validates the embedded length against length.
| value (v1::document::view view)
| Initialize with a copy of the BSON bytes referenced by view.
| value (value &&other) noexcept=default
| Move construction.
| value (value const &other)
| Copy construction.
| ~value ()=default
| Destroy this object.
const_iterator | begin () const
| Return a const iterator to the beginning of the range of BSON elements within this view.
const_iterator | cbegin () const
| Return a const iterator to the beginning of the range of BSON elements within this view.
const_iterator | cend () const
| Return a const iterator to the end of the range of BSON elements within this view.
std::uint8_t const * | data () const
| Return a pointer to the BSON bytes being represented.
bool | empty () const
| Return true when the BSON bytes represents an empty view:
const_iterator | end () const
| Return a const iterator to the end of the range of BSON elements within this view.
const_iterator | find (v1::stdx::string_view key) const
| Return a const iterator to the element within the represented BSON document whose key compares equal to key.
template<typename T, detail::enable_if_t< detail::conjunction< std::is_default_constructible< T >, has_from_bson< T > >::value > * = nullptr>
T | get () const
| Equivalent to T value; this->get(value); return value;.
template<typename T, detail::enable_if_t< has_from_bson< T >::value > * = nullptr>
void | get (T &v) const
| Equivalent to from_bson(v, this->view()).
deleter_type const & | get_deleter () const
| Return the current deleter.
std::size_t | length () const
| Return the length of the BSON bytes being represented.
| operator bool () const
| Return true when this view is valid.
| operator v1::document::view () const
| Implicitly convert to this->view().
template<typename T, detail::enable_if_t< has_to_bson< T >::value > * = nullptr>
value & | operator= (T const &v)
| Equivalent to *this = value{v}.
value & | operator= (v1::document::view view)
| Equivalent to this->reset(view).
value & | operator= (value &&other) noexcept=default
| Move assignment.
value & | operator= (value const &other)
| Copy assignment.
v1::element::view | operator[] (v1::stdx::string_view key) const
| Return the first element within the represented BSON document whose key compares equal to key.
unique_ptr_type | release ()
| Release ownership of the underlying BSON bytes.
void | reset (v1::document::view v)
| Replace the underlying BSON bytes with a copy of v.
void | reset (value v)
| Replace the underlying BSON bytes with v.
std::size_t | size () const
| Return the length of the BSON bytes being represented.
v1::document::view | view () const
| Return a view of the BSON bytes as a document.

## Static Public Member Functions

static void | noop_deleter (std::uint8_t *)
| The deleter used to avoid freeing preallocated storage representing an empty BSON document.

## Friends

bool | operator!= (value const &lhs, value const &rhs)
| Compare equal when the BSON bytes represented by lhs and rhs compare equal.
bool | operator== (value const &lhs, value const &rhs)
| Compare equal when the BSON bytes represented by lhs and rhs compare equal.

## Member Typedef Documentation

## const_iterator

using bsoncxx::v1::document::value::const_iterator = v1::document::view::const_iterator

A const iterator over the elements of a view.

Note
  This iterator almost satisfies Cpp17ForwardIterator, but std::iterator_traits<T>::reference is defined as value_type, similar to std::vector<bool>::iterator and std::istreambuf_iterator<T>. Therefore, this iterator only fully satisfies Cpp17InputIterator.

## default_deleter_type

using bsoncxx::v1::document::value::default_deleter_type = std::default_delete<std::uint8_t[]>

The deleter used to free copied BSON bytes when a user-provided deleter is not specified.

## deleter_type

using bsoncxx::v1::document::value::deleter_type = std::function<void (std::uint8_t*)>

The type of the deleter used to free the underlying BSON bytes.

A deleter D that is wrapped by deleter_type must:

- be std::is_nothrow_destructible<D>,
- be std::is_nothrow_move_constructible<D>,
- not throw an exception when invoked with a std::uint8_t*.

These requirements are the same as those for a std::unique_ptr<T, D> deleter D, but do not include nothrow move assignability due to being wrapped by deleter_type.

Important
  Despite being a std::function<T>, deleter_type is assumed to behave like a C++23 std::move_only_function<T>. That is, it is assumed to be nothrow destructible, nothrow move constructible, and nothrow move assignable.

## iterator

using bsoncxx::v1::document::value::iterator = const_iterator

Equivalent to const_iterator.

## noop_deleter_type

using bsoncxx::v1::document::value::noop_deleter_type = void( *)(std::uint8_t*)

The type of a pointer to noop_deleter.

## unique_ptr_type

using bsoncxx::v1::document::value::unique_ptr_type = std::unique_ptr<std::uint8_t[], deleter_type>

The type of the unique pointer used to manage the underlying BSON bytes.

## Constructor & Destructor Documentation

## ~value()

bsoncxx::v1::document::value::~value | ( |  | ) |

default

Destroy this object.

## value() [1/11]

bsoncxx::v1::document::value::value | ( | value && | other | ) |

default noexcept

Move construction.

Postconditions:
  - this->data() == nullptr
  - this->get_deleter() is in a valid but unspecified state.

## value() [2/11]

bsoncxx::v1::document::value::value | ( | value const & | other | ) |

inline

Copy construction.

The copied value is allocated using operator new[] and the deleter is set to default_deleter_type.

## value() [3/11]

bsoncxx::v1::document::value::value | ( |  | ) |

inline

Initialize as an empty document (or array).

The value is equivalent to a default-initialized bsoncxx::v1::document::view and the deleter is set to bsoncxx::v1::document::value::noop_deleter.

Warning
  Modifying the pointed-to data after default construction is undefined behavior.

## value() [4/11]

template<typename Deleter, detail::enable_if_t< is_valid_deleter< Deleter >::value > * = nullptr>

bsoncxx::v1::document::value::value | ( | std::uint8_t * | data,
|  | Deleter | deleter )

inline

Initialize as owning data which will be freed with deleter.

Constraints:
  - Deleter must satisfy the requirements described by deleter_type.

Preconditions:
  - If data is not null, the size of the storage region pointed to by data must be greater than or equal to 5.
  - The embedded length must be less than or equal to the size of the storage region pointed to by data.
  - deleter must be capable of freeing the storage region pointed to by data.

## value() [5/11]

template<typename Deleter, detail::enable_if_t< is_valid_deleter< Deleter >::value > * = nullptr>

bsoncxx::v1::document::value::value | ( | std::uint8_t * | data,
|  | std::size_t | length,
|  | Deleter | deleter )

inline

Equivalent to value(std::uint8_t* data, Deleter deleter), but validates the embedded length against length.

Preconditions:
  - If data is not null, the size of the storage region pointed to by data must be greater than or equal to length.

Exceptions

  bsoncxx::v1::exception | with bsoncxx::v1::document::view::errc::invalid_length if `length` is less than 5 or less than this->size().

## value() [6/11]

bsoncxx::v1::document::value::value | ( | std::uint8_t * | data | ) |

inline explicit

Initialize as owning data which will be freed with default_deleter_type.

Preconditions:
  - If data is not null, the size of the storage region pointed to by data must be greater than or equal to 5.
  - The embedded length must be less than or equal to the size of the storage region pointed to by data.

## value() [7/11]

bsoncxx::v1::document::value::value | ( | std::uint8_t * | data,
|  | std::size_t | length )

inline explicit

Equivalent to value(std::uint8_t* data), but validates the embedded length against length.

Preconditions:
  - If data is not null, the size of the storage region pointed to by data must be greater than or equal to length.

Exceptions

  bsoncxx::v1::exception | with bsoncxx::v1::document::view::errc::invalid_length if `length` is less than 5 or less than this->size().

## value() [8/11]

bsoncxx::v1::document::value::value | ( | unique_ptr_type | ptr | ) |

inline explicit

Initialize as owning ptr.

Preconditions:
  - If data is not null, the size of the storage region pointed to by data must be greater than or equal to 5.
  - The embedded length must be less than or equal to the size of the storage region pointed to by data.

## value() [9/11]

bsoncxx::v1::document::value::value | ( | unique_ptr_type | ptr,
|  | std::size_t | length )

inline explicit

Equivalent to value(unique_ptr_type ptr), but validates the embedded length against length.

Preconditions:
  - If ptr is not null, the size of the storage region pointed to by data must be greater than or equal to length.

Exceptions

  bsoncxx::v1::exception | with bsoncxx::v1::document::view::errc::invalid_length if `length` is less than 5 or less than this->size().

## value() [10/11]

bsoncxx::v1::document::value::value | ( | v1::document::view | view | ) |

inline explicit

Initialize with a copy of the BSON bytes referenced by view.

If view is equivalent to a default-initialized bsoncxx::v1::document::view, this value is equivalent to value().

If view is invalid, this value is equivalent to value{nullptr}.

Otherwise, the copied value is allocated using operator new[] and the deleter is set to default_deleter_type.

## value() [11/11]

template<typename T, detail::enable_if_t< has_to_bson< T >::value > * = nullptr>

bsoncxx::v1::document::value::value | ( | T const & | v | ) |

inline explicit

Equivalent to to_bson(v, *this); after default-initialization.

Constraints:
  - T is not bsoncxx::v1::document::value.
  - to_bson(v, *this) is a valid and unambiguous overload found by ADL.

## Member Function Documentation

## begin()

const_iterator bsoncxx::v1::document::value::begin | ( |  | ) | const

inline

Return a const iterator to the beginning of the range of BSON elements within this view.

If this view is invalid, returns an end iterator.

Exceptions

  bsoncxx::v1::exception | with bsoncxx::v1::document::view::errc::invalid_data if this operation failed due to invalid BSON bytes.

## cbegin()

const_iterator bsoncxx::v1::document::value::cbegin | ( |  | ) | const

inline

Return a const iterator to the beginning of the range of BSON elements within this view.

If this view is invalid, returns an end iterator.

Exceptions

  bsoncxx::v1::exception | with bsoncxx::v1::document::view::errc::invalid_data if this operation failed due to invalid BSON bytes.

## cend()

const_iterator bsoncxx::v1::document::value::cend | ( |  | ) | const

inline

Return a const iterator to the end of the range of BSON elements within this view.

## data()

std::uint8_t const * bsoncxx::v1::document::value::data | ( |  | ) | const

inline

Return a pointer to the BSON bytes being represented.

## empty()

bool bsoncxx::v1::document::value::empty | ( |  | ) | const

inline

Return true when the BSON bytes represents an empty view:

- data() is not null,
- size() is equal to 5, and
- the pointed-to BSON bytes are terminated with a null byte.

Note
  This does not return true when this view is invalid.

## end()

const_iterator bsoncxx::v1::document::value::end | ( |  | ) | const

inline

Return a const iterator to the end of the range of BSON elements within this view.

## find()

const_iterator bsoncxx::v1::document::value::find | ( | v1::stdx::string_view | key | ) | const

inline

Return a const iterator to the element within the represented BSON document whose key compares equal to key.

If this view is invalid or the requested field is not found, returns an end iterator.

Complexity
  Linear.

Exceptions

  bsoncxx::v1::exception | with bsoncxx::v1::document::view::errc::invalid_data if this operation failed due to invalid BSON bytes.

## get() [1/2]

template<typename T, detail::enable_if_t< detail::conjunction< std::is_default_constructible< T >, has_from_bson< T > >::value > * = nullptr>

T bsoncxx::v1::document::value::get | ( |  | ) | const

inline

Equivalent to T value; this->get(value); return value;.

Constraints:
  - T is not bsoncxx::v1::document::value.
  - T is default-constructible.
  - from_bson(v, this->view()) is a valid and unambiguous overload found by ADL.

## get() [2/2]

template<typename T, detail::enable_if_t< has_from_bson< T >::value > * = nullptr>

void bsoncxx::v1::document::value::get | ( | T & | v | ) | const

inline

Equivalent to from_bson(v, this->view()).

Constraints:
  - T is not bsoncxx::v1::document::value.
  - from_bson(v, this->view()) is a valid and unambiguous overload found by ADL.

## get_deleter()

deleter_type const & bsoncxx::v1::document::value::get_deleter | ( |  | ) | const

inline

Return the current deleter.

## length()

std::size_t bsoncxx::v1::document::value::length | ( |  | ) | const

inline

Return the length of the BSON bytes being represented.

If this->data() is null, returns 0.

Note
  This returns the embedded length as indicated by the pointed-to BSON bytes. The result is always within the range [0, INT32_MAX] when preconditions are satisfied.

## noop_deleter()

void bsoncxx::v1::document::value::noop_deleter | ( | std::uint8_t * |  | ) |

static

The deleter used to avoid freeing preallocated storage representing an empty BSON document.

## operator bool()

bsoncxx::v1::document::value::operator bool | ( |  | ) | const

inline explicit

Return true when this view is valid.

Note
  This does not validate the BSON bytes being represented.

## operator v1::document::view()

bsoncxx::v1::document::value::operator v1::document::view | ( |  | ) | const

inline

Implicitly convert to this->view().

## operator=() [1/4]

template<typename T, detail::enable_if_t< has_to_bson< T >::value > * = nullptr>

value & bsoncxx::v1::document::value::operator= | ( | T const & | v | ) |

inline

Equivalent to *this = value{v}.

Constraints:
  - T is not bsoncxx::v1::document::value.
  - to_bson(v, *this) is a valid and unambiguous overload found by ADL.

## operator=() [2/4]

value & bsoncxx::v1::document::value::operator= | ( | v1::document::view | view | ) |

inline

Equivalent to this->reset(view).

## operator=() [3/4]

value & bsoncxx::v1::document::value::operator= | ( | value && | other | ) |

default noexcept

Move assignment.

Postconditions:
  - this->data() == nullptr
  - this->get_deleter() is in a valid but unspecified state.

## operator=() [4/4]

value & bsoncxx::v1::document::value::operator= | ( | value const & | other | ) |

inline

Copy assignment.

The copied value is allocated using operator new[] and the deleter is set to default_deleter_type.

## operator[]()

v1::element::view bsoncxx::v1::document::value::operator[] | ( | v1::stdx::string_view | key | ) | const

inline

Return the first element within the represented BSON document whose key compares equal to key.

Returns
  An invalid element if this view is invalid or the requested field is not found.

Complexity
  Linear.

Exceptions

  bsoncxx::v1::exception | with bsoncxx::v1::document::view::errc::invalid_data if this operation failed due to invalid BSON bytes.

## release()

unique_ptr_type bsoncxx::v1::document::value::release | ( |  | ) |

inline

Release ownership of the underlying BSON bytes.

## reset() [1/2]

void bsoncxx::v1::document::value::reset | ( | v1::document::view | v | ) |

inline

Replace the underlying BSON bytes with a copy of v.

If v is invalid, reset to a default-initialized value.

The copied value is allocated using operator new[] and the deleter is set to default_deleter_type.

## reset() [2/2]

void bsoncxx::v1::document::value::reset | ( | value | v | ) |

inline

Replace the underlying BSON bytes with v.

## size()

std::size_t bsoncxx::v1::document::value::size | ( |  | ) | const

inline

Return the length of the BSON bytes being represented.

If this->data() is null, returns 0.

Note
  This returns the embedded length as indicated by the pointed-to BSON bytes. The result is always within the range [0, INT32_MAX] when preconditions are satisfied.

## view()

v1::document::view bsoncxx::v1::document::value::view | ( |  | ) | const

inline

Return a view of the BSON bytes as a document.

## Friends And Related Symbol Documentation

## operator!=

bool operator!= | ( | value const & | lhs,
|  | value const & | rhs )

friend

Compare equal when the BSON bytes represented by lhs and rhs compare equal.

An invalid view only compares equal to another invalid view. The underlying BSON bytes (if any) is ignored for an invalid document.

## operator==

bool operator== | ( | value const & | lhs,
|  | value const & | rhs )

friend

Compare equal when the BSON bytes represented by lhs and rhs compare equal.

An invalid view only compares equal to another invalid view. The underlying BSON bytes (if any) is ignored for an invalid document.

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

- bsoncxx/v1/document/value.hpp