BSON Iteration

BSON Iteration#

<bson/iterator.h> (header file)#

Note

Using bson_iterator::reference in C++ and certain document decoding C APIs requires the inclusion of the bson/view.h.

Types#

struct bson_iterator#

A BSON iterator is used to refer to elements and positions within a BSON document. It can be used to read elements from a bson_view or bson_doc, and is also used when modifying elements with bson_mut.

Zero-initialized:

A zero-initialized bson_iterator has no defined semantics and should not be used for any operations.

Header:

bson/iterator.h

This type is fully trivial and is the size of two pointers.

This struct also implements the C++ std::forward_iterator concept.

reference operator*() const#
auto operator->() const#

Obtain a reference to the element. This will throw an exception if the iterator is errant.

bson_iterator &operator++()#
bool operator==(const bson_iterator) const#

Implements std::forward_iterator.

C API:

bson_next() and bson_iterator_eq()

bson_iter_errc error() const#
bool has_error() const#
C API:

bson_iterator_get_error()

bool has_value() const#
Returns:

not stop()

bool stop() const#
C API:

bson_stop()

const bson_byte *data() const#
C API:

bson_iterator_data()

void throw_if_error() const#

If has_error(), throws an exception related to that error.

class bson_iterator::reference#

(C++) Implements a proxy reference for the iterator for using with operator*() and operator->(). This class is used to access properties of the underlying element.

Header:

bson/view.h

bson_type type() const#
std::string_view key() const#
bson_value_ref value() const#
C API:

bson_key(), bson_iterator_type(), and bson_iterator_value()

enum bson_iter_errc#

Error conditions that may occur during BSON iteration. See: Errant Iterators

enumerator bson_iter_errc_okay#

No error condition.

enumerator bson_iter_errc_short_read#

The document ended abruptly before being able to read another element.

enumerator bson_iter_errc_invalid_type#

An invalid type tag was encountered, and iteration cannot decode the value.

enumerator bson_iter_errc_invalid_length#

An element declares itself to have a size that is too large to fit within the document which contains it.

Functions & Macros#

Document Iteration#

bson_iterator bson_begin(__bson_viewable B)#
bson_iterator bson_end(__bson_viewable B)#

Obtain a bson_iterator referring to the beginning or end of the given BSON document, respectively.

C++ API:

Use the begin() and end() member function of the object B

Parameters:

B – A BSON document to be viewed. Passed through bson_view_from().

Returns:

A bson_iterator referring to the respective positions.

Important

bson_begin() may return an errant iterator if decoding the first element fails.

Note

This is implemented as a C preprocessor macro

bson_iterator bson_next(bson_iterator i)#

Obtain a bson_iterator referring to the next element after i, or an errant iterator if a parsing error occurs.

C++ API:

bson_iterator::operator++()

Parameters:

i – An iterator referring to some document. The iterator must refer to a valid element.

Precondition:

not bson_stop(i)

bool bson_iterator_eq(bson_iterator a, bson_iterator b)#

Determine whether the iterators a and b refer to the same element within their respective document.

C++ API:

bson_iterator::operator==()

bool bson_stop(bson_iterator it)#

Determine whether the given iterator can be advanced further.

This function will return true if it is the end iterator or if it has encountered a decoding error while it was advanced.

bson_iter_errc bson_iterator_get_error(bson_iterator it)#

Obtain the error condition for the given iterator. If the iterator is valid, returns bson_iter_errc::bson_iter_errc_okay. See: Errant Iterators

bson_iterator bson_find(__bson_viewable B, __string_convertible Key)#

Obtain a bson_iterator referring to the first element within B that has the key Key

Parameters:
Returns:

A bson_iterator. If the expected key was found, returns an iterator referring to that element.

If an error occured during iteration, the returned iterator will have an associated error (see: bson_iterator_get_error()).

If the requested element was not found, returns bson_end(B)

Note

This is implemented as a C preprocessor macro

Looping#

bson_foreach(IterName, Viewable)#
bson_foreach_subrange(IterName, FirstIter, LastIter)#

These macros allow the creation of control flow loops that iterate over the elements of a BSON document or array.

Parameters:

  • IterName – An identifier that will be the name of the bson_iterator that will be in scope for the loop body.

  • Viewable – A BSON document object, passed through bson_view_from()

  • FirstIter – A first iterator to begin iteration.

  • LastIter – The iterator at which to stop the loop.

bson_foreach(it, my_doc) {
  // loop body
}

For every element in the document/range, an iterator (named by IterName) will point to that element. The created iterator is const-qualified. If the document being inspected is modified during execution of the loop, the behavior is undefined.

Error Behavior

If a call to bson_next() results in an errant iterator, then the loop will be executed once using that errant iterator, and then the loop will stop on the next iteration. For this reason, it is important to check that the iterator is not errant (see bson_iterator_get_error()).

Element Properties#

mlib_str_view bson_key(bson_iterator it)#

Obtain a string that views the key of the element referred-to by it

Precondition:

not bson_stop(it).

bool bson_key_eq(bson_iterator it, auto K)#

Test whether the it element key is equal to the given string.

Parameters:

  • it – The element to inspect.

  • K – A string to compare against. Passed through mlib_str_view_from()

Note

This is implemented as a C preprocessor macro

bson_type bson_iterator_type(bson_iterator it)#

Get the type of the element referred-to by it

Precondition:

not bson_iterator_get_error(it)

bson_value_ref bson_iterator_value(bson_iterator it)#

Obtain a bson_value_ref that views the element value referred-to by it.

Precondition:

not bson_iterator_get_error(it)

const bson_byte *bson_iterator_data(bson_iterator it)#

Obtain a pointer to the element data referred-to by it.

Precondition:

not bson_iterator_get_error(it)

Behavioral Notes#

Errant Iterators#

BSON documents are validated on-the-fly as the iterator is advanced. If a parse error occurs during bson_next() or bson_begin(), then an errant iterator will be created. Attempting to read from or advance an errant iterator will result in undefined behavior. In C++, the bson_iterator::operator*() and bson_iterator::operator->() will throw an exception if the iterator is errant.

To test whether an iterator has an error, use bson_iterator_get_error() (C) or bson_iterator::error() (C++).

Contents