MongoDB C++ Driver  mongocxx-3.4.0
Public Member Functions | List of all members
bsoncxx::builder::core Class Reference

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...
 
corekey_view (stdx::string_view key)
 Appends a key passed as a non-owning stdx::string_view. More...
 
corekey_owned (std::string key)
 Appends a key passed as an STL string. More...
 
coreopen_document ()
 Opens a sub-document within this BSON datum. More...
 
coreopen_array ()
 Opens a sub-array within this BSON datum. More...
 
coreclose_document ()
 Closes the current sub-document within this BSON datum. More...
 
coreclose_array ()
 Closes the current sub-array within this BSON datum. More...
 
coreconcatenate (const document::view &view)
 Appends the keys from a BSON document into this BSON datum. More...
 
coreappend (const types::b_double &value)
 Appends a BSON double. More...
 
coreappend (const types::b_utf8 &value)
 Append a BSON UTF-8 string. More...
 
coreappend (const types::b_document &value)
 Appends a BSON document. More...
 
coreappend (const types::b_array &value)
 Appends a BSON array. More...
 
coreappend (const types::b_binary &value)
 Appends a BSON binary datum. More...
 
coreappend (const types::b_undefined &value)
 Appends a BSON undefined. More...
 
coreappend (const types::b_oid &value)
 Appends a BSON ObjectId. More...
 
coreappend (const types::b_bool &value)
 Appends a BSON boolean. More...
 
coreappend (const types::b_date &value)
 Appends a BSON date. More...
 
coreappend (const types::b_null &value)
 Appends a BSON null. More...
 
coreappend (const types::b_regex &value)
 Appends a BSON regex. More...
 
coreappend (const types::b_dbpointer &value)
 Appends a BSON DBPointer. More...
 
coreappend (const types::b_code &value)
 Appends a BSON JavaScript code. More...
 
coreappend (const types::b_symbol &value)
 Appends a BSON symbol. More...
 
coreappend (const types::b_codewscope &value)
 Appends a BSON JavaScript code with scope. More...
 
coreappend (const types::b_int32 &value)
 Appends a BSON 32-bit signed integer. More...
 
coreappend (const types::b_timestamp &value)
 Appends a BSON replication timestamp. More...
 
coreappend (const types::b_int64 &value)
 Appends a BSON 64-bit signed integer. More...
 
coreappend (const types::b_decimal128 &value)
 Appends a BSON Decimal128. More...
 
coreappend (const types::b_minkey &value)
 Appends a BSON min-key. More...
 
coreappend (const types::b_maxkey &value)
 Appends a BSON max-key. More...
 
coreappend (const types::value &value)
 Appends a BSON variant value. More...
 
coreappend (std::string str)
 Appends an STL string as a BSON UTF-8 string. More...
 
coreappend (stdx::string_view str)
 Appends a string view as a BSON UTF-8 string. More...
 
template<typename T >
coreappend (T *v)
 Appends a char* or const char*. More...
 
coreappend (bool value)
 Appends a native boolean as a BSON boolean. More...
 
coreappend (double value)
 Appends a native double as a BSON double. More...
 
coreappend (std::int32_t value)
 Appends a native int32_t as a BSON 32-bit signed integer. More...
 
coreappend (std::int64_t value)
 Appends a native int64_t as a BSON 64-bit signed integer. More...
 
coreappend (const oid &value)
 Appends an oid as a BSON ObjectId. More...
 
coreappend (decimal128 value)
 Appends a decimal128 object as a BSON Decimal128. More...
 
coreappend (document::view view)
 Appends the given document view. More...
 
coreappend (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_arrayTrue if the top-level BSON datum should be an array.

Member Function Documentation

◆ append() [1/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::exceptionif 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() [2/33]

core& bsoncxx::builder::core::append ( const types::b_utf8 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::exceptionif 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 utf8 fails to append.

◆ append() [3/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::exceptionif 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() [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::exceptionif 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::exceptionif 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_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::exceptionif 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() [7/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::exceptionif 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() [8/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::exceptionif 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() [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::exceptionif 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_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::exceptionif 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() [11/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::exceptionif 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() [12/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::exceptionif 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() [13/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::exceptionif 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() [14/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::exceptionif 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() [15/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::exceptionif 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() [16/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::exceptionif 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() [17/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::exceptionif 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() [18/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::exceptionif 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() [19/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::exceptionif 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() [20/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::exceptionif 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() [21/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::exceptionif 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() [22/33]

core& bsoncxx::builder::core::append ( const types::value 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::exceptionif the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [23/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::exceptionif the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [24/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::exceptionif the current BSON datum is a document that is waiting for a key to be appended to start a new key/value pair.

◆ append() [25/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::exceptionif 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 ( 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::exceptionif 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 ( 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::exceptionif 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 ( 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::exceptionif 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::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::exceptionif 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 ( 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::exceptionif 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 ( 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::exceptionif 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 ( 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::exceptionif 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]

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::exceptionif 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::exceptionif 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::exceptionif 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::exceptionif 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::exceptionif 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::exceptionif 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
keyA string key.
Returns
A reference to the object on which this member function is being called. This facilitates method chaining.
Exceptions
bsoncxx::exceptionif 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
keyA 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::exceptionif 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::exceptionif 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::exceptionif 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::exceptionif 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::exceptionif the precondition is violated.

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