MongoDB C++ Driver  mongocxx-3.7.0
Public Member Functions | List of all members
bsoncxx::document::value Class Reference

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

#include <value.hpp>

Public Member Functions

 value (std::uint8_t *data, std::size_t length, deleter_type dtor)
 Constructs a value from a buffer. More...
 
 value (unique_ptr_type ptr, std::size_t length)
 Constructs a value from a std::unique_ptr to a buffer. More...
 
 value (document::view view)
 Constructs a value from a view of a document. More...
 
template<typename T , typename std::enable_if<!std::is_same< T, typename array::view >::value, int >::type = 0>
 value (const T &t)
 Constructor used for serialization of user objects. More...
 
document::view::const_iterator cbegin () const
 
document::view::const_iterator cend () const
 
document::view::const_iterator begin () const
 
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. More...
 
element operator[] (stdx::string_view key) const
 Finds the first element of the document with the provided key. More...
 
const std::uint8_t * data () const
 Access the raw bytes of the underlying document. More...
 
std::size_t length () const
 Gets the length of the underlying buffer. More...
 
bool empty () const
 Checks if the underlying document is empty, i.e. More...
 
document::view view () const noexcept
 Get a view over the document owned by this value.
 
 operator document::view () const noexcept
 Conversion operator that provides a view given a value. More...
 
template<typename T >
get ()
 Constructs an object of type T from this document object. More...
 
template<typename T >
void get (T &t)
 Constructs an object of type T from this document object. More...
 
unique_ptr_type release ()
 Transfer ownership of the underlying buffer to the caller. More...
 
void reset (document::view view)
 Replace the formerly-owned buffer with the new view. More...
 

Related Functions

(Note that these are not member functions.)

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

Detailed 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.

Constructor & Destructor Documentation

◆ value() [1/4]

bsoncxx::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
dataA pointer to a buffer containing a valid BSON document.
lengthThe length of the document.
dtorA user provided deleter.

◆ value() [2/4]

bsoncxx::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
ptrA pointer to a buffer containing a valid BSON document.
lengthThe length of the document.

◆ value() [3/4]

bsoncxx::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
viewA view of another document to copy.

◆ value() [4/4]

template<typename T , typename std::enable_if<!std::is_same< T, typename array::view >::value, int >::type = 0>
bsoncxx::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::document::value doc).

Parameters
tA user-defined object to serialize into a BSON object.

Member Function Documentation

◆ begin()

document::view::const_iterator bsoncxx::document::value::begin ( ) const
Returns
A const_iterator to the first element of the document.

◆ cbegin()

document::view::const_iterator bsoncxx::document::value::cbegin ( ) const
Returns
A const_iterator to the first element of the document.

◆ cend()

document::view::const_iterator bsoncxx::document::value::cend ( ) const
Returns
A const_iterator to the past-the-end element of the document.

◆ data()

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

Access the raw bytes of the underlying document.

Returns
A pointer to the value's buffer.

◆ empty()

bool bsoncxx::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::document::value::end ( ) const
Returns
A const_iterator to the past-the-end element of the document.

◆ find()

document::view::const_iterator bsoncxx::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
keyThe 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::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::document::view& doc).

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

◆ get() [2/2]

template<typename T >
void bsoncxx::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::document::view& doc).

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

◆ length()

std::size_t bsoncxx::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::document::value::operator document::view ( ) const
noexcept

Conversion operator that provides a view given a value.

Returns
A view over the value.

◆ operator[]()

element bsoncxx::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
keyThe key to search for.
Returns
The matching element, if found, or the invalid element.

◆ release()

unique_ptr_type bsoncxx::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::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.


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