Loading...
Searching...
No Matches
bsoncxx::v_noabi::builder::core Class Reference

`#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 (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.
core & | append (v_noabi::array::view view)
| Appends the given array view.
core & | append (v_noabi::document::view view)
| Appends the given document view.
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 (v_noabi::document::view const &view)
| Appends the keys from a BSON document into this BSON datum.
v_noabi::array::value | extract_array ()
| Transfers ownership of the underlying document to the caller.
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.
v_noabi::array::view | view_array () const
| Gets a view over the array.
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 | ( | 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() [4/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() [5/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() [6/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() [7/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() [8/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() [9/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() [10/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() [11/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() [12/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() [13/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() [14/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() [15/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() [16/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() [17/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() [18/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() [19/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() [20/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() [21/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() [22/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() [23/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() [24/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() [25/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() [26/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() [27/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() [28/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() [29/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() [30/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() [31/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() [32/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.

## append() [33/34]

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

core & bsoncxx::v_noabi::builder::core::append | ( | 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.

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

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

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

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

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