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

#include <core.hpp>

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

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

core &	key_owned (std::string key)
	Appends a key passed as an STL string. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void	clear ()
	Deletes the contents of the underlying BSON datum. More...

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

Constructor & Destructor Documentation

◆ core()

bsoncxx::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/33]

core& bsoncxx::builder::core::append ( 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::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() [2/33]

core& bsoncxx::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::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/33]

core& bsoncxx::builder::core::append ( const oid & 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::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/33]

core& bsoncxx::builder::core::append ( const types::b_array & 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::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::exception if the array fails to append.

◆ append() [5/33]

core& bsoncxx::builder::core::append ( const types::b_binary & 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::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::exception if the binary fails to append.

◆ append() [6/33]

core& bsoncxx::builder::core::append ( const types::b_bool & 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::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::exception if the boolean fails to append.

◆ append() [7/33]

core& bsoncxx::builder::core::append ( const types::b_code & 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::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::exception if the JavaScript code fails to append.

◆ append() [8/33]

core& bsoncxx::builder::core::append ( const types::b_codewscope & 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::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::exception if the JavaScript code with scope fails to append.

◆ append() [9/33]

core& bsoncxx::builder::core::append ( const types::b_date & 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::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::exception if the date fails to append.

◆ append() [10/33]

core& bsoncxx::builder::core::append ( const types::b_dbpointer & 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::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::exception if the DBPointer fails to append.

◆ append() [11/33]

core& bsoncxx::builder::core::append ( const types::b_decimal128 & 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::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::exception if the Decimal128 fails to append.

◆ append() [12/33]

core& bsoncxx::builder::core::append ( const types::b_document & 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::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::exception if the document fails to append.

◆ append() [13/33]

core& bsoncxx::builder::core::append ( const types::b_double & 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::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::exception if the double fails to append.

◆ append() [14/33]

core& bsoncxx::builder::core::append ( const types::b_int32 & 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::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::exception if the 32-bit signed integer fails to append.

◆ append() [15/33]

core& bsoncxx::builder::core::append ( const types::b_int64 & 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::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::exception if the 64-bit signed integer fails to append.

◆ append() [16/33]

core& bsoncxx::builder::core::append ( const types::b_maxkey & 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::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::exception if the max-key fails to append.

◆ append() [17/33]

core& bsoncxx::builder::core::append ( const types::b_minkey & 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::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::exception if the min-key fails to append.

◆ append() [18/33]

core& bsoncxx::builder::core::append ( const types::b_null & 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::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::exception if null fails to append.

◆ append() [19/33]

core& bsoncxx::builder::core::append ( const types::b_oid & 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::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::exception if the ObjectId fails to append.

◆ append() [20/33]

core& bsoncxx::builder::core::append ( const types::b_regex & 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::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::exception if the regex fails to append.

◆ append() [21/33]

core& bsoncxx::builder::core::append ( const types::b_string & 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::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::exception if the string fails to append.

◆ append() [22/33]

core& bsoncxx::builder::core::append ( const types::b_symbol & 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::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::exception if the symbol fails to append.

◆ append() [23/33]

core& bsoncxx::builder::core::append ( const types::b_timestamp & 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::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::exception if the timestamp fails to append.

◆ append() [24/33]

core& bsoncxx::builder::core::append ( const types::b_undefined & 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::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::exception if undefined fails to append.

◆ append() [25/33]

core& bsoncxx::builder::core::append ( const types::bson_value::view & 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::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() [26/33]

core& bsoncxx::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::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() [27/33]

core& bsoncxx::builder::core::append ( 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::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() [28/33]

core& bsoncxx::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::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() [29/33]

core& bsoncxx::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::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() [30/33]

core& bsoncxx::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::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() [31/33]

core& bsoncxx::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::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() [32/33]

core& bsoncxx::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::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() [33/33]

template<typename T >

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

inline

Appends a char* or const char*.

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::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::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::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::exception if the current BSON datum is not an open sub-array.

◆ close_document()

core& bsoncxx::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::exception if the current BSON datum is not an open sub-document.

◆ concatenate()

core& bsoncxx::builder::core::concatenate ( const document::view & 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::exception if one of the keys fails to append.

◆ extract_array()

array::value bsoncxx::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::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()

document::value bsoncxx::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::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::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::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::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::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::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::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_document()

core& bsoncxx::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::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()

array::view bsoncxx::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::exception if the precondition is violated.

◆ view_document()

document::view bsoncxx::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::exception if the precondition is violated.

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

src/bsoncxx/builder/core.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ core()

Member Function Documentation

◆ append() [1/33]

◆ append() [2/33]

◆ append() [3/33]

◆ append() [4/33]

◆ append() [5/33]

◆ append() [6/33]

◆ append() [7/33]

◆ append() [8/33]

◆ append() [9/33]

◆ append() [10/33]

◆ append() [11/33]

◆ append() [12/33]

◆ append() [13/33]

◆ append() [14/33]

◆ append() [15/33]

◆ append() [16/33]

◆ append() [17/33]

◆ append() [18/33]

◆ append() [19/33]

◆ append() [20/33]

◆ append() [21/33]

◆ append() [22/33]

◆ append() [23/33]

◆ append() [24/33]

◆ append() [25/33]

◆ append() [26/33]

◆ append() [27/33]

◆ append() [28/33]

◆ append() [29/33]

◆ append() [30/33]

◆ append() [31/33]

◆ append() [32/33]

◆ append() [33/33]

◆ clear()

◆ close_array()

◆ close_document()

◆ concatenate()

◆ extract_array()

◆ extract_document()

◆ key_owned()

◆ key_view()

◆ open_array()

◆ open_document()

◆ view_array()

◆ view_document()