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 class	error_code : std::int32_t {   k_cannot_append_key_in_sub_array = 1 , k_cannot_close_array_in_sub_document , k_cannot_close_document_in_sub_array , k_cannot_perform_array_operation_on_document ,   k_cannot_perform_document_operation_on_array , BSONCXX_ENUM , k_need_key , k_no_array_to_close ,   k_no_document_to_close , k_unmatched_key_in_builder , k_unset_element , k_json_parse_failure ,   k_invalid_oid , k_failed_converting_bson_to_json , k_invalid_decimal128 , k_internal_error ,   k_cannot_begin_appending_array , k_cannot_begin_appending_document , k_cannot_end_appending_array , k_cannot_end_appending_document ,   k_invalid_binary_subtype , k_invalid_bson_type_id , BSONCXX_ENUM , k_cannot_append_utf8 = k_cannot_append_string ,   k_need_element_type_k_utf8 = k_need_element_type_k_string }
	Enum representing the various error types that can occur while operating on BSON values. More...
enum class	ExtendedJsonMode : std::uint8_t { k_legacy , k_canonical , k_relaxed }
	An enumeration of the types of Extended JSON that the to_json function accepts. More...
enum class	type : std::uint8_t
	An enumeration of each BSON type. More...
enum class	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.
std::error_code	make_error_code (error_code error)
	Translate a bsoncxx::error_code into a std::error_code.
std::string	to_json (document::view view, ExtendedJsonMode mode=ExtendedJsonMode::k_legacy)
	Converts a BSON document to a JSON string, in extended format.
document::value	from_json (stdx::string_view json)
	Constructs a new document::value from the provided JSON text.
document::value	operator""_bson (const char *json, size_t len)
	Constructs a new document::value from the provided JSON text.
std::string	to_string (type rhs)
	Returns a stringification of the given type.
std::string	to_string (binary_sub_type rhs)
	Returns a stringification of the given binary sub type.
stdx::optional< document::view >	validate (const std::uint8_t *data, std::size_t length)
	Validates a BSON document.
stdx::optional< document::view >	validate (const std::uint8_t *data, std::size_t length, const validator &validator, std::size_t *invalid_offset=nullptr)
	Validates a BSON document.

Detailed Description

Top level namespace for MongoDB C++ BSON functionality.

Enumeration Type Documentation

binary_sub_type

enum class 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, k_md5 = 0x05, k_encrypted = 0x06, k_column = 0x07, k_user = 0x80

error_code

enum class 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.
k_invalid_binary_subtype	Invalid binary subtype.
k_invalid_bson_type_id	Invalid type.
BSONCXX_ENUM	A value failed to append.

ExtendedJsonMode

enum class 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 class 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_string = 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::exception

with 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

error

An error from bsoncxx

Returns

An error_code

operator""_bson()

document::value bsoncxx::operator""_bson	(	const char *	json,
		size_t	len
	)

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

This is the UDL version of from_json().

Parameters

'json'	A string into a JSON document.
'len'	The length of the JSON string. This is calculated automatically upon use of the UDL.

Returns

A document::value if conversion worked.

Exceptions

bsoncxx::exception

with error details if the conversion failed.

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

view	A valid BSON document.
mode	An optional JSON representation mode.

Exceptions

bsoncxx::exception

with 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

(

binary_sub_type

rhs

)

Returns a stringification of the given binary sub type.

Parameters

rhs	The type to stringify.

Returns

a std::string representation of the type.

to_string() [2/2]

std::string bsoncxx::to_string

(

type

rhs

)

Returns a stringification of the given type.

Parameters

rhs	The 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

data	A buffer containing a BSON document to validate.
length	The 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

data	A buffer containing a BSON document to validate.
length	The size of the buffer.
validator	A 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_offset	If 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.