bsoncxx::v1::document::value Class Reference

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

Description

A BSON document.

Attention

This feature is experimental! It is not ready for use!

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.

Attention

This feature is experimental! It is not ready for use!

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 )

defaultnoexcept

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 )

inlineexplicit

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 )

inlineexplicit

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 )

inlineexplicit

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 )

inlineexplicit

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 )

inlineexplicit

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 )

inlineexplicit

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

inlineexplicit

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 )

defaultnoexcept

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