Loading...
Searching...
No Matches
bsoncxx::v1::document::view Class Reference

`#include <bsoncxx/v1/document/view.hpp>`

## Description

A non-owning, read-only BSON document.

An "invalid" view, as indicated by operator bool() const, does not satisfy the minimum requirements of a valid BSON document, which are that:

- data() is not null, and
- size() is not less than 5 (the minimum size of a BSON document).

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.

## Classes

class | const_iterator
| A const iterator over the elements of a view. More...

## Public Types

enum class | errc
| Errors codes which may be returned by bsoncxx::v1::document::view. More...
using | iterator = const_iterator
| Equivalent to const_iterator.

## Public Member Functions

| view ()
| Initialize as an empty view.
| view (std::uint8_t const *data)
| Initialize with the given BSON bytes.
| view (std::uint8_t const *data, std::size_t length)
| Equivalent to view(std::uint8_t const* data), but validates the embedded length against length.
const_iterator | begin () const
| Return a const iterator to the beginning of the range of BSON elements within this view.
const_iterator | cbegin () const
| Return a const iterator to the beginning of the range of BSON elements within this view.
const_iterator | cend () const
| Return a const iterator to the end of the range of BSON elements within this view.
std::uint8_t const * | data () const
| Return a pointer to the BSON bytes being represented.
bool | empty () const
| Return true when the BSON bytes represents an empty view:
const_iterator | end () const
| Return a const iterator to the end of the range of BSON elements within this view.
const_iterator | find (v1::stdx::string_view key) const
| Return a const iterator to the element within the represented BSON document whose key compares equal to key.
std::size_t | length () const
| Return the length of the BSON bytes being represented.
| operator bool () const
| Return true when this view is valid.
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::size_t | size () const
| Return the length of the BSON bytes being represented.

## Static Public Member Functions

static std::error_category const & | error_category ()
| The error category for bsoncxx::v1::document::view::errc.

## Friends

std::error_code | make_error_code (errc v)
| Support implicit conversion to std::error_code.
bool | operator== (view lhs, view rhs)
| Compare equal when the BSON bytes represented by lhs and rhs compare equal.
bool | operator!= (view lhs, view rhs)
| Compare equal when the BSON bytes represented by lhs and rhs compare equal.

## Member Typedef Documentation

## iterator

using bsoncxx::v1::document::view::iterator = const_iterator

Equivalent to const_iterator.

## Member Enumeration Documentation

## errc

enum class bsoncxx::v1::document::view::errc

strong

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

Enumerator
zero | Zero.
invalid_length | Length is invalid.
invalid_data | Data is invalid.

## Constructor & Destructor Documentation

## view() [1/3]

bsoncxx::v1::document::view::view | ( |  | ) |

Initialize as an empty view.

Postconditions:
  - this->data() != nullptr
  - this->size() == 5
  - this->empty() == true

## view() [2/3]

bsoncxx::v1::document::view::view | ( | std::uint8_t const * | data | ) |

inline explicit

Initialize with the given BSON bytes.

Preconditions:
  - If data is not null, the size of the storage region pointed to by data must be greater than or equal to 5.
  - The embedded length must be less than or equal to the size of the storage region pointed to by data.

## view() [3/3]

bsoncxx::v1::document::view::view | ( | std::uint8_t const * | data,
|  | std::size_t | length )

Equivalent to view(std::uint8_t const* data), but validates the embedded length against length.

Preconditions:
  - If data is not null, the size of the storage region pointed to by data must be greater than or equal to length.

Exceptions

  bsoncxx::v1::exception | with bsoncxx::v1::document::view::errc::invalid_length if `length` is less than 5 or less than this->size().

## Member Function Documentation

## begin()

view::const_iterator bsoncxx::v1::document::view::begin | ( |  | ) | const

inline

Return a const iterator to the beginning of the range of BSON elements within this view.

If this view is invalid, returns an end iterator.

Exceptions

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

## cbegin()

const_iterator bsoncxx::v1::document::view::cbegin | ( |  | ) | const

Return a const iterator to the beginning of the range of BSON elements within this view.

If this view is invalid, returns an end iterator.

Exceptions

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

## cend()

view::const_iterator bsoncxx::v1::document::view::cend | ( |  | ) | const

inline

Return a const iterator to the end of the range of BSON elements within this view.

## data()

std::uint8_t const * bsoncxx::v1::document::view::data | ( |  | ) | const

inline

Return a pointer to the BSON bytes being represented.

## empty()

bool bsoncxx::v1::document::view::empty | ( |  | ) | const

inline

Return true when the BSON bytes represents an empty view:

- data() is not null,
- size() is equal to 5, and
- the pointed-to BSON bytes are terminated with a null byte.

Note
  This does not return true when this view is invalid.

## end()

view::const_iterator bsoncxx::v1::document::view::end | ( |  | ) | const

inline

Return a const iterator to the end of the range of BSON elements within this view.

## error_category()

std::error_category const & bsoncxx::v1::document::view::error_category | ( |  | ) |

static

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

## find()

const_iterator bsoncxx::v1::document::view::find | ( | v1::stdx::string_view | key | ) | const

Return a const iterator to the element within the represented BSON document whose key compares equal to key.

If this view is invalid or the requested field is not found, returns an end iterator.

Complexity
  Linear.

Exceptions

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

## length()

std::size_t bsoncxx::v1::document::view::length | ( |  | ) | const

inline

Return the length of the BSON bytes being represented.

If this->data() is null, returns 0.

Note
  This returns the embedded length as indicated by the pointed-to BSON bytes. The result is always within the range [0, INT32_MAX] when preconditions are satisfied.

## operator bool()

bsoncxx::v1::document::view::operator bool | ( |  | ) | const

inline explicit

Return true when this view is valid.

Note
  This does not validate the BSON bytes being represented.

## operator[]()

v1::element::view bsoncxx::v1::document::view::operator[] | ( | v1::stdx::string_view | key | ) | const

inline

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

Returns
  An invalid element if this view is invalid or the requested field is not found.

Complexity
  Linear.

Exceptions

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

## size()

std::size_t bsoncxx::v1::document::view::size | ( |  | ) | const

inline

Return the length of the BSON bytes being represented.

If this->data() is null, returns 0.

Note
  This returns the embedded length as indicated by the pointed-to BSON bytes. The result is always within the range [0, INT32_MAX] when preconditions are satisfied.

## Friends And Related Symbol Documentation

## make_error_code

std::error_code make_error_code | ( | errc | v | ) |

friend

Support implicit conversion to std::error_code.

## operator!=

bool operator!= | ( | view | lhs,
|  | view | rhs )

friend

Compare equal when the BSON bytes represented by lhs and rhs compare equal.

An invalid view only compares equal to another invalid view. The underlying BSON bytes (if any) is ignored for an invalid document.

## operator==

bool operator== | ( | view | lhs,
|  | view | rhs )

friend

Compare equal when the BSON bytes represented by lhs and rhs compare equal.

An invalid view only compares equal to another invalid view. The underlying BSON bytes (if any) is ignored for an invalid document.

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

- bsoncxx/v1/document/view.hpp