Loading...
Searching...
No Matches
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.

## 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.

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.

## 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.

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

- bsoncxx/v1/element/view.hpp