#include <bsoncxx/v_noabi/bsoncxx/builder/core.hpp>

Description

A low-level interface for constructing BSON documents and arrays.

Remarks: Generally it is recommended to use the classes in builder::basic or builder::stream instead of using this class directly. However, developers who wish to write their own abstractions may find this class useful.

Public Member Functions
	core (bool is_array)
	Constructs an empty BSON datum.

uint8_t *	append (binary_sub_type sub_type, uint32_t length)
	Appends a BSON binary datum by allocating space that the caller must fill with content.

core &	append (bool value)
	Appends a native boolean as a BSON boolean.

core &	append (bsoncxx::v_noabi::array::view view)
	Appends the given array view.

core &	append (bsoncxx::v_noabi::document::view view)
	Appends the given document view.

core &	append (decimal128 value)
	Appends a decimal128 object as a BSON Decimal128.

core &	append (double value)
	Appends a native double as a BSON double.

core &	append (oid const &value)
	Appends an oid as a BSON ObjectId.

core &	append (std::int32_t value)
	Appends a native int32_t as a BSON 32-bit signed integer.

core &	append (std::int64_t value)
	Appends a native int64_t as a BSON 64-bit signed integer.

core &	append (std::string str)
	Appends an STL string as a BSON UTF-8 string.

core &	append (stdx::string_view str)
	Appends a string view as a BSON UTF-8 string.

template<typename T>
core &	append (T *v)
	Appends a char* or char const*.

core &	append (types::b_array const &value)
	Appends a BSON array.

core &	append (types::b_binary const &value)
	Appends a BSON binary datum.

core &	append (types::b_bool const &value)
	Appends a BSON boolean.

core &	append (types::b_code const &value)
	Appends a BSON JavaScript code.

core &	append (types::b_codewscope const &value)
	Appends a BSON JavaScript code with scope.

core &	append (types::b_date const &value)
	Appends a BSON date.

core &	append (types::b_dbpointer const &value)
	Appends a BSON DBPointer.

core &	append (types::b_decimal128 const &value)
	Appends a BSON Decimal128.

core &	append (types::b_document const &value)
	Appends a BSON document.

core &	append (types::b_double const &value)
	Appends a BSON double.

core &	append (types::b_int32 const &value)
	Appends a BSON 32-bit signed integer.

core &	append (types::b_int64 const &value)
	Appends a BSON 64-bit signed integer.

core &	append (types::b_maxkey const &value)
	Appends a BSON max-key.

core &	append (types::b_minkey const &value)
	Appends a BSON min-key.

core &	append (types::b_null const &value)
	Appends a BSON null.

core &	append (types::b_oid const &value)
	Appends a BSON ObjectId.

core &	append (types::b_regex const &value)
	Appends a BSON regex.

core &	append (types::b_string const &value)
	Append a BSON UTF-8 string.

core &	append (types::b_symbol const &value)
	Appends a BSON symbol.

core &	append (types::b_timestamp const &value)
	Appends a BSON replication timestamp.

core &	append (types::b_undefined const &value)
	Appends a BSON undefined.

core &	append (types::bson_value::view const &value)
	Appends a BSON variant value.

void	clear ()
	Deletes the contents of the underlying BSON datum. After calling clear(), the state of this class will be the same as it was immediately after construction.

core &	close_array ()
	Closes the current sub-array within this BSON datum.

core &	close_binary ()
	Closes the current sub-binary within this BSON datum.

core &	close_document ()
	Closes the current sub-document within this BSON datum.

core &	concatenate (bsoncxx::v_noabi::document::view const &view)
	Appends the keys from a BSON document into this BSON datum.

bsoncxx::v_noabi::array::value	extract_array ()
	Transfers ownership of the underlying document to the caller.

bsoncxx::v_noabi::document::value	extract_document ()
	Transfers ownership of the underlying document to the caller.

core &	key_owned (std::string key)
	Appends a key passed as an STL string. Transfers ownership of the key to this class.

core &	key_view (stdx::string_view key)
	Appends a key passed as a non-owning stdx::string_view.

core &	open_array ()
	Opens a sub-array within this BSON datum.

core &	open_binary ()=delete
	A sub-binary must be opened by invoking bsoncxx::v_noabi::builder::basic::sub_binary::allocate()

core &	open_document ()
	Opens a sub-document within this BSON datum.

bsoncxx::v_noabi::array::view	view_array () const
	Gets a view over the array.

bsoncxx::v_noabi::document::view	view_document () const
	Gets a view over the document.

Constructor & Destructor Documentation

◆ core()

bsoncxx::v_noabi::builder::core::core ( bool is_array )

explicit

Constructs an empty BSON datum.

Parameters

is_array True if the top-level BSON datum should be an array.

Member Function Documentation

◆ append() [1/34]

uint8_t * bsoncxx::v_noabi::builder::core::append	(	binary_sub_type	sub_type,
		uint32_t	length )

Appends a BSON binary datum by allocating space that the caller must fill with content.

Returns: A pointer to the allocated binary data block. The caller must write to every byte or discard the builder.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the binary fails to append.

◆ append() [2/34]

core & bsoncxx::v_noabi::builder::core::append ( bool value )

Appends a native boolean as a BSON boolean.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [3/34]

core & bsoncxx::v_noabi::builder::core::append ( bsoncxx::v_noabi::array::view view )

Appends the given array view.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [4/34]

core & bsoncxx::v_noabi::builder::core::append ( bsoncxx::v_noabi::document::view view )

Appends the given document view.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [5/34]

core & bsoncxx::v_noabi::builder::core::append ( decimal128 value )

Appends a decimal128 object as a BSON Decimal128.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [6/34]

core & bsoncxx::v_noabi::builder::core::append ( double value )

Appends a native double as a BSON double.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [7/34]

core & bsoncxx::v_noabi::builder::core::append ( oid const & value )

Appends an oid as a BSON ObjectId.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [8/34]

core & bsoncxx::v_noabi::builder::core::append ( std::int32_t value )

Appends a native int32_t as a BSON 32-bit signed integer.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [9/34]

core & bsoncxx::v_noabi::builder::core::append ( std::int64_t value )

Appends a native int64_t as a BSON 64-bit signed integer.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [10/34]

core & bsoncxx::v_noabi::builder::core::append ( std::string str )

Appends an STL string as a BSON UTF-8 string.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [11/34]

core & bsoncxx::v_noabi::builder::core::append ( stdx::string_view str )

Appends a string view as a BSON UTF-8 string.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [12/34]

template<typename T>

core & bsoncxx::v_noabi::builder::core::append ( T * v )

inline

Appends a char* or char const*.

We disable all other pointer types to prevent the surprising implicit conversion to bool.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [13/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_array const & value )

Appends a BSON array.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the array fails to append.

◆ append() [14/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_binary const & value )

Appends a BSON binary datum.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the binary fails to append.

◆ append() [15/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_bool const & value )

Appends a BSON boolean.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the boolean fails to append.

◆ append() [16/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_code const & value )

Appends a BSON JavaScript code.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the JavaScript code fails to append.

◆ append() [17/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_codewscope const & value )

Appends a BSON JavaScript code with scope.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the JavaScript code with scope fails to append.

◆ append() [18/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_date const & value )

Appends a BSON date.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the date fails to append.

◆ append() [19/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_dbpointer const & value )

Appends a BSON DBPointer.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the DBPointer fails to append.

◆ append() [20/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_decimal128 const & value )

Appends a BSON Decimal128.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the Decimal128 fails to append.

◆ append() [21/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_document const & value )

Appends a BSON document.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the document fails to append.

◆ append() [22/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_double const & value )

Appends a BSON double.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the double fails to append.

◆ append() [23/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_int32 const & value )

Appends a BSON 32-bit signed integer.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the 32-bit signed integer fails to append.

◆ append() [24/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_int64 const & value )

Appends a BSON 64-bit signed integer.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the 64-bit signed integer fails to append.

◆ append() [25/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_maxkey const & value )

Appends a BSON max-key.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the max-key fails to append.

◆ append() [26/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_minkey const & value )

Appends a BSON min-key.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the min-key fails to append.

◆ append() [27/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_null const & value )

Appends a BSON null.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if null fails to append.

◆ append() [28/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_oid const & value )

Appends a BSON ObjectId.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the ObjectId fails to append.

◆ append() [29/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_regex const & value )

Appends a BSON regex.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the regex fails to append.

◆ append() [30/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_string const & value )

Append a BSON UTF-8 string.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the string fails to append.

◆ append() [31/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_symbol const & value )

Appends a BSON symbol.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the symbol fails to append.

◆ append() [32/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_timestamp const & value )

Appends a BSON replication timestamp.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if the timestamp fails to append.

◆ append() [33/34]

core & bsoncxx::v_noabi::builder::core::append ( types::b_undefined const & value )

Appends a BSON undefined.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair. bsoncxx::v_noabi::exception if undefined fails to append.

◆ append() [34/34]

core & bsoncxx::v_noabi::builder::core::append ( types::bson_value::view const & value )

Appends a BSON variant value.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ clear()

void bsoncxx::v_noabi::builder::core::clear ( )

Deletes the contents of the underlying BSON datum. After calling clear(), the state of this class will be the same as it was immediately after construction.

◆ close_array()

core & bsoncxx::v_noabi::builder::core::close_array ( )

Closes the current sub-array within this BSON datum.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is not an open sub-array.

◆ close_binary()

core & bsoncxx::v_noabi::builder::core::close_binary ( )

Closes the current sub-binary within this BSON datum.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the binary contents were never allocated.

◆ close_document()

core & bsoncxx::v_noabi::builder::core::close_document ( )

Closes the current sub-document within this BSON datum.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is not an open sub-document.

◆ concatenate()

core & bsoncxx::v_noabi::builder::core::concatenate ( bsoncxx::v_noabi::document::view const & view )

Appends the keys from a BSON document into this BSON datum.

Note: If this BSON datum is a document, the original keys from view are kept. Otherwise (if this BSON datum is an array), the original keys from view are discarded.; This can be used with an array::view as well by converting it to a document::view first.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if one of the keys fails to append.

◆ extract_array()

bsoncxx::v_noabi::array::value bsoncxx::v_noabi::builder::core::extract_array ( )

Transfers ownership of the underlying document to the caller.

Returns: A document::value with ownership of the document.

Precondition: The top-level BSON datum should be an array that does not contain any open sub-documents or open sub-arrays.

Exceptions

bsoncxx::v_noabi::exception if the precondition is violated.

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

◆ extract_document()

bsoncxx::v_noabi::document::value bsoncxx::v_noabi::builder::core::extract_document ( )

Transfers ownership of the underlying document to the caller.

Returns: A document::value with ownership of the document.

Precondition: The top-level BSON datum should be a document that is not waiting for a key to be appended to start a new key/value pair, and does not contain any open sub-documents or open sub-arrays.

Exceptions

bsoncxx::v_noabi::exception if the precondition is violated.

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

◆ key_owned()

core & bsoncxx::v_noabi::builder::core::key_owned ( std::string key )

Appends a key passed as an STL string. Transfers ownership of the key to this class.

Parameters

key	A string key.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is an array or if the previous value appended to the builder was a key.

◆ key_view()

core & bsoncxx::v_noabi::builder::core::key_view ( stdx::string_view key )

Appends a key passed as a non-owning stdx::string_view.

Remarks: Use key_owned() unless you know what you are doing.

Warning: The caller must ensure that the lifetime of the backing string extends until the next value is appended.

Parameters

key	A null-terminated array of characters.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is an array or if the previous value appended to the builder was also a key.

◆ open_array()

core & bsoncxx::v_noabi::builder::core::open_array ( )

Opens a sub-array within this BSON datum.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ open_binary()

core & bsoncxx::v_noabi::builder::core::open_binary ( )

delete

A sub-binary must be opened by invoking bsoncxx::v_noabi::builder::basic::sub_binary::allocate()

◆ open_document()

core & bsoncxx::v_noabi::builder::core::open_document ( )

Opens a sub-document within this BSON datum.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Exceptions

bsoncxx::v_noabi::exception if the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ view_array()

bsoncxx::v_noabi::array::view bsoncxx::v_noabi::builder::core::view_array ( ) const

Gets a view over the array.

Returns: An array::view of the internal BSON.

Precondition: The top-level BSON datum should be an array that does not contain any open sub-documents or open sub-arrays.

Exceptions

bsoncxx::v_noabi::exception if the precondition is violated.

◆ view_document()

bsoncxx::v_noabi::document::view bsoncxx::v_noabi::builder::core::view_document ( ) const

Gets a view over the document.

Returns: A document::view of the internal BSON.

Precondition: The top-level BSON datum should be a document that is not waiting for a key to be appended to start a new key/value pair, and does contain any open sub-documents or open sub-arrays.

Exceptions

bsoncxx::v_noabi::exception if the precondition is violated.

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

bsoncxx/v_noabi/bsoncxx/builder/core.hpp

Description

Public Member Functions

Constructor & Destructor Documentation

◆ core()

Member Function Documentation

◆ append() [1/34]

◆ append() [2/34]

◆ append() [3/34]

◆ append() [4/34]

◆ append() [5/34]

◆ append() [6/34]

◆ append() [7/34]

◆ append() [8/34]

◆ append() [9/34]

◆ append() [10/34]

◆ append() [11/34]

◆ append() [12/34]

◆ append() [13/34]

◆ append() [14/34]

◆ append() [15/34]

◆ append() [16/34]

◆ append() [17/34]

◆ append() [18/34]

◆ append() [19/34]

◆ append() [20/34]

◆ append() [21/34]

◆ append() [22/34]

◆ append() [23/34]

◆ append() [24/34]

◆ append() [25/34]

◆ append() [26/34]

◆ append() [27/34]

◆ append() [28/34]

◆ append() [29/34]

◆ append() [30/34]

◆ append() [31/34]

◆ append() [32/34]

◆ append() [33/34]

◆ append() [34/34]

◆ clear()

◆ close_array()

◆ close_binary()

◆ close_document()

◆ concatenate()

◆ extract_array()

◆ extract_document()

◆ key_owned()

◆ key_view()

◆ open_array()

◆ open_binary()

◆ open_document()

◆ view_array()

◆ view_document()