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.

Attention

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

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.

Attention

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

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 )

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

Attention

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

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

inlineexplicit

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.

Attention

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

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