#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 Member Functions
template<typename T , detail::requires_not_t< int, std::is_same< T, array::view > > = 0>
	value (const T &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 (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.

	value (std::uint8_t *data, std::size_t length, deleter_type dtor)
	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.

	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.

document::view::const_iterator	begin () const

document::view::const_iterator	cbegin () const

document::view::const_iterator	cend () const

const std::uint8_t *	data () const
	Access the raw bytes of the underlying document.

bool	empty () const
	Checks if the underlying document is empty, i.e. it is equivalent to the trivial document '{}'.

document::view::const_iterator	end () const

document::view::const_iterator	find (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, const bsoncxx::v_noabi::document::view& 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, const bsoncxx::v_noabi::document::view& doc)`.

std::size_t	length () const
	Gets the length of the underlying buffer.

	operator document::view () const noexcept
	Conversion operator that provides a view given a value.

element	operator[] (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 (document::view view)
	Replace the formerly-owned buffer with the new view. This will make a copy of the passed-in view.

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== (const value &lhs, const value &rhs)
	Compares two document values for (in)-equality.

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

Constructor & Destructor Documentation

◆ value() [1/4]

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

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.

Parameters

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

◆ value() [2/4]

bsoncxx::v_noabi::document::value::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.

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 ( 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 ( const T & 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).

Parameters

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

Member Function Documentation

◆ begin()

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

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

◆ cbegin()

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

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

◆ cend()

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

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

◆ data()

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

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

Checks if the underlying document is empty, i.e. it is equivalent to the trivial document '{}'.

Returns: true if the underlying document is empty.

◆ end()

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

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

◆ find()

document::view::const_iterator bsoncxx::v_noabi::document::value::find ( 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.

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, const bsoncxx::v_noabi::document::view& 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, const bsoncxx::v_noabi::document::view& 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

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 document::view()

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

inlinenoexcept

Conversion operator that provides a view given a value.

Returns: A view over the value.

◆ operator[]()

element bsoncxx::v_noabi::document::value::operator[] ( 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.

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 ( )

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.

◆ reset()

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

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

◆ view()

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

inlinenoexcept

Get a view over the document owned by this value.

Friends And Related Symbol Documentation

◆ operator!=()

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

◆ operator==()

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

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

bsoncxx/v_noabi/bsoncxx/document/value.hpp

Description

Public Member Functions

Related Symbols

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 document::view()

◆ operator[]()

◆ release()

◆ reset()

◆ view()

Friends And Related Symbol Documentation

◆ operator!=()

◆ operator==()