bsoncxx::v1::element::view Class Reference

#include <bsoncxx/v1/element/view.hpp>

Description

A non-owning, read-only BSON element.

An "invalid" element, as indicated by operator bool() const, does not represent a BSON element and does not have an underlying key or value. Attempting to query the key or value of an invalid element will throw an exception. However, subscripting will not throw an exception when the requested field does not exist; instead it will return an invalid element to facilitate chaining.

a = doc["a"]; // If "a" exists, `a` is valid. Otherwise, `a` is invalid.
b = a["b"];   // If "a" is a document and "a.b" exists, `b` is valid. Otherwise, `b` is invalid.
c = b[3];     // If "a.b" is an array and "a.b[3]" exists, `c` is valid. Otherwise, `c` is invalid.
 
a.key();       // Throws an exception if invalid.
b.type_id();   // Throws an exception if invalid.
c.get_int32(); // Throws an exception if invalid.

Do not chain subscripts (e.g. doc["a"]["b"]) or immediately query element properties (e.g. doc["x"].key()) if you need to identify which field may be missing.

// Unclear whether "x" or "x.y" was missing when an exception is thrown.
try { doc["x"]["y"].type_id(); } catch (...) {}
 
// Check validity prior to further access to identify the missing field.
if (x = doc["x"]) {
    if (y = x["y"]) {} // Field "x.y" is present.
    else            {} // Field "x.y" is missing.
} else              {} // Field "x" is missing.
 
// A less efficient but more concise approach.
if (doc["x"]["y"]) {} // Field "x.y" is present.
else if (doc["x"]) {} // Field "x.y" is missing.
else               {} // Field "x" is missing.

The BSON bytes being represented is only validated as minimally required to satisfy a requested operation. When an operation is not satisfiable due to invalid data, the operation will throw an bsoncxx::v1::exception with bsoncxx::v1::document::view::errc::invalid_data.

Attention

This feature is experimental! It is not ready for use!

Public Types
enum class	errc
	Errors codes which may be returned by bsoncxx::v1::element::view. More...

Public Member Functions
	view ()
	Initialize as an invalid element without any associated BSON bytes.
	view (view const &other) noexcept
	Copy (or move) construction.
	~view ()
	Destroy this object.
v1::stdx::string_view	key () const
	Return the key.
std::uint32_t	keylen () const
	Return the "keylen" component of the underlying BSON bytes.
std::uint32_t	length () const
	Return the "length" component of the underlying BSON bytes.
std::uint32_t	offset () const
	Return the "offset" component of the underlying BSON bytes.
	operator bool () const
	Return true when this is a valid element.
view &	operator= (view const &other) noexcept
	Copy (or move) assignment.
v1::element::view	operator[] (std::uint32_t idx) const
	Return the first element within the represented BSON array whose key compares equal to i.
v1::element::view	operator[] (v1::stdx::string_view key) const
	Return the first element within the represented BSON document whose key compares equal to key.
std::uint8_t const *	raw () const
	Return the "raw" component of the underlying BSON bytes.
v1::types::id	type_id () const
	Return the type.
v1::types::value	type_value () const
	Return a deep copy of the underlying BSON type value.
v1::types::view	type_view () const
	Return a view of the underlying BSON type value.
v1::types::b_minkey	get_minkey () const
	Return the underlying BSON type value.
v1::types::b_double	get_double () const
	Return the underlying BSON type value.
v1::types::b_string	get_string () const
	Return the underlying BSON type value.
v1::types::b_document	get_document () const
	Return the underlying BSON type value.
v1::types::b_array	get_array () const
	Return the underlying BSON type value.
v1::types::b_binary	get_binary () const
	Return the underlying BSON type value.
v1::types::b_undefined	get_undefined () const
	Return the underlying BSON type value.
v1::types::b_oid	get_oid () const
	Return the underlying BSON type value.
v1::types::b_bool	get_bool () const
	Return the underlying BSON type value.
v1::types::b_date	get_date () const
	Return the underlying BSON type value.
v1::types::b_null	get_null () const
	Return the underlying BSON type value.
v1::types::b_regex	get_regex () const
	Return the underlying BSON type value.
v1::types::b_dbpointer	get_dbpointer () const
	Return the underlying BSON type value.
v1::types::b_code	get_code () const
	Return the underlying BSON type value.
v1::types::b_symbol	get_symbol () const
	Return the underlying BSON type value.
v1::types::b_codewscope	get_codewscope () const
	Return the underlying BSON type value.
v1::types::b_int32	get_int32 () const
	Return the underlying BSON type value.
v1::types::b_timestamp	get_timestamp () const
	Return the underlying BSON type value.
v1::types::b_int64	get_int64 () const
	Return the underlying BSON type value.
v1::types::b_decimal128	get_decimal128 () const
	Return the underlying BSON type value.
v1::types::b_maxkey	get_maxkey () const
	Return the underlying BSON type value.

Static Public Member Functions
static std::error_category const &	error_category ()
	The error category for bsoncxx::v1::element::view::errc.

Friends
std::error_code	make_error_code (errc v)
	Support implicit conversion to std::error_code.

Member Enumeration Documentation

errc

enum class bsoncxx::v1::element::view::errc

strong

Errors codes which may be returned by bsoncxx::v1::element::view.

Attention

This feature is experimental! It is not ready for use!

Enumerator
zero	Zero.
invalid_view	View is invalid.
invalid_data	Data is invalid.

Constructor & Destructor Documentation

~view()

bsoncxx::v1::element::view::~view

(

)

Destroy this object.

view() [1/2]

bsoncxx::v1::element::view::view ( view const & other )

noexcept

Copy (or move) construction.

view() [2/2]

bsoncxx::v1::element::view::view

(

)

Initialize as an invalid element without any associated BSON bytes.

Member Function Documentation

error_category()

std::error_category const & bsoncxx::v1::element::view::error_category ( )

static

The error category for bsoncxx::v1::element::view::errc.

Attention

This feature is experimental! It is not ready for use!

get_array()

v1::types::b_array bsoncxx::v1::element::view::get_array

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_binary()

v1::types::b_binary bsoncxx::v1::element::view::get_binary

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_bool()

v1::types::b_bool bsoncxx::v1::element::view::get_bool

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_code()

v1::types::b_code bsoncxx::v1::element::view::get_code

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_codewscope()

v1::types::b_codewscope bsoncxx::v1::element::view::get_codewscope

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_date()

v1::types::b_date bsoncxx::v1::element::view::get_date

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_dbpointer()

v1::types::b_dbpointer bsoncxx::v1::element::view::get_dbpointer

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_decimal128()

v1::types::b_decimal128 bsoncxx::v1::element::view::get_decimal128

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_document()

v1::types::b_document bsoncxx::v1::element::view::get_document

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_double()

v1::types::b_double bsoncxx::v1::element::view::get_double

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_int32()

v1::types::b_int32 bsoncxx::v1::element::view::get_int32

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_int64()

v1::types::b_int64 bsoncxx::v1::element::view::get_int64

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_maxkey()

v1::types::b_maxkey bsoncxx::v1::element::view::get_maxkey

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_minkey()

v1::types::b_minkey bsoncxx::v1::element::view::get_minkey

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_null()

v1::types::b_null bsoncxx::v1::element::view::get_null

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_oid()

v1::types::b_oid bsoncxx::v1::element::view::get_oid

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_regex()

v1::types::b_regex bsoncxx::v1::element::view::get_regex

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_string()

v1::types::b_string bsoncxx::v1::element::view::get_string

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_symbol()

v1::types::b_symbol bsoncxx::v1::element::view::get_symbol

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_timestamp()

v1::types::b_timestamp bsoncxx::v1::element::view::get_timestamp

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

get_undefined()

v1::types::b_undefined bsoncxx::v1::element::view::get_undefined

(

)

const

Return the underlying BSON type value.

Exceptions

bsoncxx::v1::exception	with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.
bsoncxx::v1::exception	with bsoncxx::v1::types::view::errc::type_mismatch if the BSON type value does not match the requested type.

key()

v1::stdx::string_view bsoncxx::v1::element::view::key

(

)

const

Return the key.

Exceptions

bsoncxx::v1::exception

with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.

keylen()

std::uint32_t bsoncxx::v1::element::view::keylen

(

)

const

Return the "keylen" component of the underlying BSON bytes.

The value is unspecified when this element is invalid.

length()

std::uint32_t bsoncxx::v1::element::view::length

(

)

const

Return the "length" component of the underlying BSON bytes.

The value is unspecified when this element is invalid.

offset()

std::uint32_t bsoncxx::v1::element::view::offset

(

)

const

Return the "offset" component of the underlying BSON bytes.

The value is unspecified when this element is invalid.

operator bool()

bsoncxx::v1::element::view::operator bool ( ) const

explicit

Return true when this is a valid element.

Note

This does not validate the BSON bytes being represented.

operator=()

view & bsoncxx::v1::element::view::operator= ( view const & other )

noexcept

Copy (or move) assignment.

operator[]() [1/2]

v1::element::view bsoncxx::v1::element::view::operator[]

(

std::uint32_t

idx

)

const

Return the first element within the represented BSON array whose key compares equal to i.

Returns

An invalid element if this view is invalid, this element does not represent a BSON array, or the requested field is not found.

Complexity

Linear.

Exceptions

bsoncxx::v1::exception

with bsoncxx::v1::element::view::errc::invalid_data if this operation failed due to invalid BSON bytes.

operator[]() [2/2]

v1::element::view bsoncxx::v1::element::view::operator[]

(

v1::stdx::string_view

key

)

const

Return the first element within the represented BSON document whose key compares equal to key.

Returns

An invalid element if this view is invalid, this element does not represent a BSON document, or the requested field is not found.

Complexity

Linear.

Exceptions

bsoncxx::v1::exception

with bsoncxx::v1::element::view::errc::invalid_data if this operation failed due to invalid BSON bytes.

raw()

std::uint8_t const * bsoncxx::v1::element::view::raw

(

)

const

Return the "raw" component of the underlying BSON bytes.

The value is unspecified when this element is invalid.

type_id()

v1::types::id bsoncxx::v1::element::view::type_id

(

)

const

Return the type.

Exceptions

bsoncxx::v1::exception

with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.

type_value()

v1::types::value bsoncxx::v1::element::view::type_value

(

)

const

Return a deep copy of the underlying BSON type value.

Exceptions

bsoncxx::v1::exception

with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.

type_view()

v1::types::view bsoncxx::v1::element::view::type_view

(

)

const

Return a view of the underlying BSON type value.

Exceptions

bsoncxx::v1::exception

with bsoncxx::v1::element::view::errc::invalid_view if this element is invalid.

Friends And Related Symbol Documentation

make_error_code

std::error_code make_error_code ( errc v )

friend

Support implicit conversion to std::error_code.

Attention

This feature is experimental! It is not ready for use!

---

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

• bsoncxx/v1/element/view.hpp