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

Description

A read-only BSON document that owns its underlying buffer.

When a document::value goes out of scope, the underlying buffer is freed. Generally this class should be used sparingly; document::view should be used instead wherever possible.

Public Types
using	const_iterator = v_noabi::document::view::const_iterator
	A const iterator over the contents of a document view.
using	deleter_type = void( )(std::uint8_t)
	The type of the deleter used to free the underlying BSON binary data.
using	iterator = const_iterator
	Equivalent to const_iterator.
using	unique_ptr_type = std::unique_ptr<std::uint8_t[], deleter_type>
	The type of the unique pointer used to manage the underlying BSON binary data.

Public Member Functions
	value (std::uint8_t *data, std::size_t length, deleter_type deleter)
	Constructs a value from a buffer.
template<typename T, detail::requires_not_t< int, std::is_same< T, array::view > > = 0>
	value (T const &t)
	Constructor used for serialization of user objects. This uses argument-dependent lookup to find the function declaration void to_bson(T& t, bsoncxx::v_noabi::document::value doc).
	value (unique_ptr_type ptr, std::size_t length)
	Constructs a value from a std::unique_ptr to a buffer. The ownership of the buffer is transferred to the constructed value.
	value (v_noabi::document::view view)
	Constructs a value from a view of a document. The data referenced by the document::view will be copied into a new buffer managed by the constructed value.
const_iterator	begin () const
const_iterator	cbegin () const
const_iterator	cend () const
std::uint8_t const *	data () const
	Access the raw bytes of the underlying document.
bool	empty () const
	Return true when this->length() == 5.
const_iterator	end () const
const_iterator	find (v1::stdx::string_view key) const
	Finds the first element of the document with the provided key. If there is no such element, the past-the-end iterator will be returned. The runtime of find() is linear in the length of the document. This method only searches the top-level document, and will not recurse to any subdocuments.
template<typename T>
T	get ()
	Constructs an object of type T from this document object. This method uses argument-dependent lookup to find the function declaration void from_bson(T& t, bsoncxx::v_noabi::document::view const& doc).
template<typename T>
void	get (T &t)
	Constructs an object of type T from this document object. This method uses argument-dependent lookup to find the function declaration void from_bson(T& t, bsoncxx::v_noabi::document::view const& doc).
std::size_t	length () const
	Gets the length of the underlying buffer.
	operator v1::document::value () &&
	Convert to the bsoncxx::v1 equivalent.
	operator v1::document::value () const &
	Convert to the bsoncxx::v1 equivalent.
	operator v_noabi::document::view () const noexcept
	Conversion operator that provides a view given a value.
template<typename T>
value &	operator= (T const &t)
	Assignment used for serialization of user objects. This uses argument-dependent lookup to find the function declaration void to_bson(T& t, bsoncxx::v_noabi::document::value doc).
v_noabi::document::element	operator[] (v1::stdx::string_view key) const
	Finds the first element of the document with the provided key. If there is no such element, the invalid document::element will be returned. The runtime of operator[] is linear in the length of the document.
unique_ptr_type	release ()
	Transfer ownership of the underlying buffer to the caller.
void	reset (v_noabi::document::view view)
	Replace the formerly-owned buffer with the new view. This will make a copy of the passed-in view.
std::size_t	size () const
	Gets the length of the underlying buffer.
v_noabi::document::view	view () const noexcept
	Get a view over the document owned by this value.

Related Symbols
(Note that these are not member symbols.)

bool	operator== (value const &lhs, value const &rhs)
	Compares two document values for (in)-equality.
bool	operator!= (value const &lhs, value const &rhs)
	Compares two document values for (in)-equality.

Member Typedef Documentation

◆ const_iterator

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

A const iterator over the contents of a document view.

This iterator type provides a const forward iterator interface to document view elements.

◆ deleter_type

using bsoncxx::v_noabi::document::value::deleter_type = void( *)(std::uint8_t*)

The type of the deleter used to free the underlying BSON binary data.

◆ iterator

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

Equivalent to const_iterator.

◆ unique_ptr_type

using bsoncxx::v_noabi::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 binary data.

Constructor & Destructor Documentation

◆ value() [1/4]

bsoncxx::v_noabi::document::value::value	(	std::uint8_t *	data,
		std::size_t	length,
		deleter_type	deleter )

inline

Constructs a value from a buffer.

This constructor transfers ownership of the buffer to the resulting value. A user-provided deleter is used to destroy the buffer.

Warning: For backward compatibility, length is NOT validated. When length is inconsistent with the embedded length as indicated by the BSON bytes, the BSON bytes may be parsed as "invalid" despite the BSON bytes themselves being valid.

Parameters

data	A pointer to a buffer containing a valid BSON document.
length	The length of the document.
deleter	A user provided deleter.

◆ value() [2/4]

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

inline

Constructs a value from a std::unique_ptr to a buffer. The ownership of the buffer is transferred to the constructed value.

Warning: For backward compatibility, length is NOT validated. When length is inconsistent with the embedded length as indicated by the BSON bytes, the BSON bytes may be parsed as "invalid" despite the BSON bytes themselves being valid.

Parameters

ptr	A pointer to a buffer containing a valid BSON document.
length	The length of the document.

◆ value() [3/4]

bsoncxx::v_noabi::document::value::value ( v_noabi::document::view view )

explicit

Constructs a value from a view of a document. The data referenced by the document::view will be copied into a new buffer managed by the constructed value.

Parameters

view	A view of another document to copy.

◆ value() [4/4]

template<typename T, detail::requires_not_t< int, std::is_same< T, array::view > > = 0>

bsoncxx::v_noabi::document::value::value ( T const & t )

inlineexplicit

Constructor used for serialization of user objects. This uses argument-dependent lookup to find the function declaration void to_bson(T& t, bsoncxx::v_noabi::document::value doc).

Constraints:

T is not bsoncxx::v_noabi::array::view.

Parameters

t	A user-defined object to serialize into a BSON object.

Member Function Documentation

◆ begin()

const_iterator bsoncxx::v_noabi::document::value::begin ( ) const

inline

Returns: A const_iterator to the first element of the document.

◆ cbegin()

const_iterator bsoncxx::v_noabi::document::value::cbegin ( ) const

inline

Returns: A const_iterator to the first element of the document.

◆ cend()

const_iterator bsoncxx::v_noabi::document::value::cend ( ) const

inline

Returns: A const_iterator to the past-the-end element of the document.

◆ data()

std::uint8_t const * bsoncxx::v_noabi::document::value::data ( ) const

inline

Access the raw bytes of the underlying document.

Returns: A pointer to the value's buffer.

◆ empty()

bool bsoncxx::v_noabi::document::value::empty ( ) const

inline

Return true when this->length() == 5.

Warning: For backward compatibility, this function does NOT check if the underlying BSON bytes represent a valid empty document.

◆ end()

const_iterator bsoncxx::v_noabi::document::value::end ( ) const

inline

Returns: A const_iterator to the past-the-end element of the document.

◆ find()

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

inline

Finds the first element of the document with the provided key. If there is no such element, the past-the-end iterator will be returned. The runtime of find() is linear in the length of the document. This method only searches the top-level document, and will not recurse to any subdocuments.

Remarks: In BSON, keys are not required to be unique. If there are multiple elements with a matching key in the document, the first matching element from the start will be returned.

Parameters

key	The key to search for.

Returns: An iterator to the matching element, if found, or the past-the-end iterator.

◆ get() [1/2]

template<typename T>

T bsoncxx::v_noabi::document::value::get ( )

inline

Constructs an object of type T from this document object. This method uses argument-dependent lookup to find the function declaration void from_bson(T& t, bsoncxx::v_noabi::document::view const& doc).

Note: Type T must be default-constructible. Otherwise, use void get(T& t).

◆ get() [2/2]

template<typename T>

void bsoncxx::v_noabi::document::value::get ( T & t )

inline

Constructs an object of type T from this document object. This method uses argument-dependent lookup to find the function declaration void from_bson(T& t, bsoncxx::v_noabi::document::view const& doc).

Parameters

t	The object to construct. The contents of the document object will be deserialized into t.

◆ length()

std::size_t bsoncxx::v_noabi::document::value::length ( ) const

inline

Gets the length of the underlying buffer.

Remarks: This is not the number of elements in the document. To compute the number of elements, use std::distance.

Returns: The length of the document, in bytes.

◆ operator v1::document::value() [1/2]

bsoncxx::v_noabi::document::value::operator v1::document::value ( ) &&

inlineexplicit

Convert to the bsoncxx::v1 equivalent.

Preconditions:

If this->data() is not null, the size of the storage region pointed to by data must be greater than or equal to 5.
The "total number of bytes comprising the document" as indicated by the BSON bytes pointed-to by this->data() must be less than or equal to the size of the storage region pointed to by data.

Note: this->size() is ignored.

◆ operator v1::document::value() [2/2]

bsoncxx::v_noabi::document::value::operator v1::document::value ( ) const &

inlineexplicit

Convert to the bsoncxx::v1 equivalent.

Preconditions:

If this->data() is not null, the size of the storage region pointed to by data must be greater than or equal to 5.
The "total number of bytes comprising the document" as indicated by the BSON bytes pointed-to by this->data() must be less than or equal to the size of the storage region pointed to by data.

Note: this->size() is ignored.

◆ operator v_noabi::document::view()

bsoncxx::v_noabi::document::value::operator v_noabi::document::view ( ) const

inlinenoexcept

Conversion operator that provides a view given a value.

Returns: A view over the value.

◆ operator=()

template<typename T>

value & bsoncxx::v_noabi::document::value::operator= ( T const & t )

inline

Assignment used for serialization of user objects. This uses argument-dependent lookup to find the function declaration void to_bson(T& t, bsoncxx::v_noabi::document::value doc).

Note: T is not constrained!

Parameters

t	A user-defined object to serialize into a BSON object.

◆ operator[]()

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

inline

Finds the first element of the document with the provided key. If there is no such element, the invalid document::element will be returned. The runtime of operator[] is linear in the length of the document.

Parameters

key	The key to search for.

Returns: The matching element, if found, or the invalid element.

◆ release()

unique_ptr_type bsoncxx::v_noabi::document::value::release ( )

inline

Transfer ownership of the underlying buffer to the caller.

Warning: After calling release() it is illegal to call any methods on this class, unless it is subsequently moved into.

Returns: A std::unique_ptr with ownership of the buffer. If the pointer is null, the deleter may also be null.

◆ reset()

void bsoncxx::v_noabi::document::value::reset ( v_noabi::document::view view )

inline

Replace the formerly-owned buffer with the new view. This will make a copy of the passed-in view.

◆ size()

std::size_t bsoncxx::v_noabi::document::value::size ( ) const

inline

Gets the length of the underlying buffer.

Remarks: This is not the number of elements in the document. To compute the number of elements, use std::distance.

Returns: The length of the document, in bytes.

◆ view()

v_noabi::document::view bsoncxx::v_noabi::document::value::view ( ) const

inlinenoexcept

Get a view over the document owned by this value.

◆ operator!=()

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

Compares two document values for (in)-equality.

◆ operator==()

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

Compares two document values for (in)-equality.

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

bsoncxx/v_noabi/bsoncxx/document/value.hpp

MongoDB C++ Driver 4.2.0

Description

Public Types

Public Member Functions

Related Symbols

Member Typedef Documentation

◆ const_iterator

◆ deleter_type

◆ iterator

◆ unique_ptr_type

Constructor & Destructor Documentation

◆ value() [1/4]

◆ value() [2/4]

◆ value() [3/4]

◆ value() [4/4]

Member Function Documentation

◆ begin()

◆ cbegin()

◆ cend()

◆ data()

◆ empty()

◆ end()

◆ find()

◆ get() [1/2]

◆ get() [2/2]

◆ length()

◆ operator v1::document::value() [1/2]

◆ operator v1::document::value() [2/2]

◆ operator v_noabi::document::view()

◆ operator=()

◆ operator[]()

◆ release()

◆ reset()

◆ size()

◆ view()

Friends And Related Symbol Documentation

◆ operator!=()

◆ operator==()