MongoDB C++ Driver  mongocxx-3.4.0
Classes | Enumerations | Functions
bsoncxx Namespace Reference

Top level namespace for MongoDB C++ BSON functionality. More...

Classes

class  decimal128
 Represents an IEEE 754-2008 BSON Decimal128 value in a platform-independent way. More...
 
class  exception
 Class representing any exceptions emitted from the bsoncxx library or its underlying implementation. More...
 
class  oid
 Represents a MongoDB ObjectId. More...
 
class  validator
 A validator is used to enable or disable specific checks that can be performed during BSON validation. More...
 
class  view_or_value
 Class representing a view-or-value variant type. More...
 

Enumerations

enum  error_code : std::int32_t {
  error_code::k_cannot_append_key_in_sub_array = 1, error_code::k_cannot_close_array_in_sub_document, error_code::k_cannot_close_document_in_sub_array, error_code::k_cannot_perform_array_operation_on_document,
  error_code::k_cannot_perform_document_operation_on_array , error_code::k_need_key, error_code::k_no_array_to_close, error_code::k_no_document_to_close ,
  error_code::k_unset_element, error_code::k_json_parse_failure, error_code::k_invalid_oid , error_code::k_invalid_decimal128,
  error_code::k_internal_error, error_code::k_cannot_begin_appending_array, error_code::k_cannot_begin_appending_document, error_code::k_cannot_end_appending_array,
  error_code::k_cannot_end_appending_document, error_code::BSONCXX_ENUM
}
 Enum representing the various error types that can occur while operating on BSON values. More...
 
enum  ExtendedJsonMode : std::uint8_t { ExtendedJsonMode::k_legacy, ExtendedJsonMode::k_canonical, ExtendedJsonMode::k_relaxed }
 An enumeration of the types of Extended JSON that the to_json function accepts. More...
 
enum  type : std::uint8_t
 An enumeration of each BSON type. More...
 
enum  binary_sub_type : std::uint8_t
 An enumeration of each BSON binary sub type. More...
 

Functions

const std::error_category & error_category ()
 Get the error_category for exceptions originating from the bsoncxx library. More...
 
std::error_code make_error_code (error_code error)
 Translate a bsoncxx::error_code into a std::error_code. More...
 
std::string to_json (document::view view, ExtendedJsonMode mode=ExtendedJsonMode::k_legacy)
 Converts a BSON document to a JSON string, in extended format. More...
 
document::value from_json (stdx::string_view json)
 Constructs a new document::value from the provided JSON text. More...
 
std::string to_string (type rhs)
 Returns a stringification of the given type. More...
 
std::string to_string (binary_sub_type rhs)
 Returns a stringification of the given binary sub type. More...
 
stdx::optional< document::viewvalidate (const std::uint8_t *data, std::size_t length)
 Validates a BSON document. More...
 
stdx::optional< document::viewvalidate (const std::uint8_t *data, std::size_t length, const validator &validator, std::size_t *invalid_offset=nullptr)
 Validates a BSON document. More...
 

Detailed Description

Top level namespace for MongoDB C++ BSON functionality.

Enumeration Type Documentation

◆ binary_sub_type

enum bsoncxx::binary_sub_type : std::uint8_t
strong

An enumeration of each BSON binary sub type.

These x-macros will expand to be of the form: k_binary = 0x00, k_function = 0x01, k_binary_deprecated = 0x02, k_uuid_deprecated = 0x03, k_uuid = 0x04 ...

◆ error_code

enum bsoncxx::error_code : std::int32_t
strong

Enum representing the various error types that can occur while operating on BSON values.

Enumerator
k_cannot_append_key_in_sub_array 

A new key was appended while building a subarray.

k_cannot_close_array_in_sub_document 

A subarray was closed while building a subdocument.

k_cannot_close_document_in_sub_array 

A subdocument was closed while building a subarray.

k_cannot_perform_array_operation_on_document 

An array operation was performed while building a document.

k_cannot_perform_document_operation_on_array 

A document operation was performed while building an array.

k_need_key 

No key was provided when one was needed.

k_no_array_to_close 

An array was closed while no array was open.

k_no_document_to_close 

A document was closed while no document was open.

k_unset_element 

An empty element was accessed.

k_json_parse_failure 

A JSON document failed to parse.

k_invalid_oid 

An Object ID string failed to parse.

k_invalid_decimal128 

A Decimal128 string failed to parse.

k_internal_error 

BSON data could not be processed, but no specific reason was available.

k_cannot_begin_appending_array 

Failed to begin appending an array to a BSON document or array.

k_cannot_begin_appending_document 

Failed to begin appending a BSON document to a BSON document or array.

k_cannot_end_appending_array 

Failed to complete appending an array to a BSON document or array.

k_cannot_end_appending_document 

Failed to complete appending a BSON document to a BSON document or array.

BSONCXX_ENUM 

A value failed to append.

◆ ExtendedJsonMode

enum bsoncxx::ExtendedJsonMode : std::uint8_t
strong

An enumeration of the types of Extended JSON that the to_json function accepts.

Enumerator
k_legacy 

to produce Legacy Extended JSON

k_canonical 

to produce Canonical Extended JSON

k_relaxed 

to produce Relaxed Extended JSON

◆ type

enum bsoncxx::type : std::uint8_t
strong

An enumeration of each BSON type.

These x-macros will expand to be of the form: k_double = 0x01, k_utf8 = 0x02, k_document = 0x03, k_array = 0x04 ...

Function Documentation

◆ error_category()

const std::error_category& bsoncxx::error_category ( )

Get the error_category for exceptions originating from the bsoncxx library.

Returns
The bsoncxx error_category

◆ from_json()

document::value bsoncxx::from_json ( stdx::string_view  json)

Constructs a new document::value from the provided JSON text.

Parameters
'json'A string_view into a JSON document
Returns
A document::value if conversion worked.
Exceptions
bsoncxx::exceptionwith error details if the conversion failed.

◆ make_error_code()

std::error_code bsoncxx::make_error_code ( error_code  error)

Translate a bsoncxx::error_code into a std::error_code.

Parameters
errorAn error from bsoncxx
Returns
An error_code

◆ to_json()

std::string bsoncxx::to_json ( document::view  view,
ExtendedJsonMode  mode = ExtendedJsonMode::k_legacy 
)

Converts a BSON document to a JSON string, in extended format.

Parameters
viewA valid BSON document.
modeAn optional JSON representation mode.
Exceptions
bsoncxx::exceptionwith error details if the conversion failed.
Returns
An extended JSON string.
Examples:
examples/mongocxx/client_session.cpp.

◆ to_string() [1/2]

std::string bsoncxx::to_string ( type  rhs)

Returns a stringification of the given type.

Parameters
rhsThe type to stringify.
Returns
a std::string representation of the type.

◆ to_string() [2/2]

std::string bsoncxx::to_string ( binary_sub_type  rhs)

Returns a stringification of the given binary sub type.

Parameters
rhsThe type to stringify.
Returns
a std::string representation of the type.

◆ validate() [1/2]

stdx::optional<document::view> bsoncxx::validate ( const std::uint8_t *  data,
std::size_t  length 
)

Validates a BSON document.

This is a simplified overload that will only do the bare minimum validation of document structure, and does not provide any further information if the document is found to be invalid.

Parameters
dataA buffer containing a BSON document to validate.
lengthThe size of the buffer.
Returns
An engaged optional containing a view if the document is valid, or an unengaged optional if the document is invalid.

◆ validate() [2/2]

stdx::optional<document::view> bsoncxx::validate ( const std::uint8_t *  data,
std::size_t  length,
const validator validator,
std::size_t *  invalid_offset = nullptr 
)

Validates a BSON document.

This overload provides additional control over the precise validation that is performed, and will give the caller access to the offset at which the document was found to be invalid.

Parameters
dataA buffer containing a BSON document to validate.
lengthThe size of the buffer.
validatorA validator used to configure what checks are done. If validation fails, it will contain the offset at which the document was found to be invalid.
invalid_offsetIf validation fails, the offset at which the document was found to be invalid will be stored here (if non-null).
Returns
An engaged optional containing a view if the document is valid, or an unengaged optional if the document is invalid.