bsoncxx::v1::array::view Class Reference

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

Description

A non-owning, read-only BSON array.

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.

Attention

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

Public Types
using	const_iterator = v1::document::view::const_iterator
	A const iterator over the elements of a view.
using	iterator = const_iterator
	Equivalent to const_iterator.

Public Member Functions
	view ()=default
	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 (std::uint32_t i) const
	Return a const iterator to the element within the represented BSON array at index i via key string comparison.
std::size_t	length () const
	Return the length of the BSON bytes being represented.
	operator bool () const
	Return true when this view is valid.
	operator v1::document::view () const
	Implicitly convert to a bsoncxx::v1::document::view.
v1::element::view	operator[] (std::uint32_t i) const
	Return the first element within the represented BSON array whose key compares equal to i.
std::size_t	size () const
	Return the length of the BSON bytes being represented.

Friends
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

const_iterator

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

A const iterator over the elements of a view.

Note

This iterator almost satisfies Cpp17ForwardIterator, but std::iterator_traits<T>::reference is defined as value_type, similar to std::vector<bool>::iterator and std::istreambuf_iterator<T>. Therefore, this iterator only fully satisfies Cpp17InputIterator.

Attention

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

iterator

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

Equivalent to const_iterator.

Constructor & Destructor Documentation

view() [1/3]

bsoncxx::v1::array::view::view ( )

default

Initialize as an empty view.

Postconditions:

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

view() [2/3]

bsoncxx::v1::array::view::view ( std::uint8_t const * data )

inlineexplicit

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::array::view::view ( std::uint8_t const * data, std::size_t length )

inline

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()

const_iterator bsoncxx::v1::array::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::array::view::cbegin ( ) 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.

cend()

const_iterator bsoncxx::v1::array::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::array::view::data ( ) const

inline

Return a pointer to the BSON bytes being represented.

empty()

bool bsoncxx::v1::array::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()

const_iterator bsoncxx::v1::array::view::end ( ) const

inline

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

find()

const_iterator bsoncxx::v1::array::view::find

(

std::uint32_t

i

)

const

Return a const iterator to the element within the represented BSON array at index i via key string comparison.

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::array::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::array::view::operator bool ( ) const

inlineexplicit

Return true when this view is valid.

Note

This does not validate the BSON bytes being represented.

operator v1::document::view()

bsoncxx::v1::array::view::operator v1::document::view ( ) const

inline

Implicitly convert to a bsoncxx::v1::document::view.

operator[]()

v1::element::view bsoncxx::v1::array::view::operator[] ( std::uint32_t i ) const

inline

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

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::array::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

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/array/view.hpp