Loading...
Searching...
No Matches
bsoncxx::array::value Class Reference

`#include <bsoncxx/v_noabi/bsoncxx/array/value.hpp>`

## Description

A read-only BSON array that owns its underlying buffer.

When a array::value goes out of scope, the underlying buffer is freed. Generally this class should be used sparingly; array::view should be used instead wherever possible.

## Public Types

using | const_iterator = v_noabi::array::view::const_iterator
| A const iterator over the contents of a document view.
using | deleter_type = void( *)(std::uint8_t*)
| The type of the deleter used to free the underlying BSON binary data.
using | iterator = const_iterator
| Equivalent to const_iterator.
using | unique_ptr_type = std::unique_ptr<uint8_t[], deleter_type>
| The type of the unique pointer used to manage the underlying BSON binary data.

## Public Member Functions

| value (std::uint8_t *data, std::size_t length, deleter_type deleter)
| Constructs a value from a buffer.
| value (unique_ptr_type ptr, std::size_t length)
| Constructs a value from a std::unique_ptr to a buffer. The ownership of the buffer is transferred to the resulting value.
| value (v_noabi::array::view view)
| Constructs a value from a view of an array. The data referenced by the array::view will be copied into a new buffer managed by the constructed value.
const_iterator | begin () const
const_iterator | cbegin () const
const_iterator | cend () const
std::uint8_t const * | data () const
| Access the raw bytes of the underlying array.
bool | empty () const
| Return true when this->length() == 5.
const_iterator | end () const
const_iterator | find (std::uint32_t i) const
| Indexes into this BSON array. If the index is out-of-bounds, a past-the-end iterator will be returned. As BSON represents arrays as documents, the runtime of find() is linear in the length of the array.
std::size_t | length () const
| Gets the length of the underlying buffer in bytes.
| operator v1::array::value () &&
| Convert to the bsoncxx::v1 equivalent.
| operator v1::array::value () const &
| Convert to the bsoncxx::v1 equivalent.
| operator v_noabi::array::view () const noexcept
| Conversion operator that provides a view given a value.
v_noabi::document::element | operator[] (std::uint32_t i) const
| Indexes into this BSON array. If the index is out-of-bounds, the invalid array::element will be returned. As BSON represents arrays as documents, the runtime of operator[] is linear in the length of the array.
unique_ptr_type | release ()
| Transfer ownership of the underlying buffer to the caller.
void | reset (v_noabi::array::view view)
| Replace the formerly-owned buffer with the new view. This will make a copy of the passed-in view.
std::size_t | size () const
| Gets the length of the underlying buffer in bytes.
v_noabi::array::view | view () const noexcept
| Get a view over the array owned by this value.

## Member Typedef Documentation

## const_iterator

using bsoncxx::v_noabi::array::value::const_iterator = v_noabi::array::view::const_iterator

A const iterator over the contents of a document view.

This iterator type provides a const forward iterator interface to document view elements.

## deleter_type

using bsoncxx::v_noabi::array::value::deleter_type = void( *)(std::uint8_t*)

The type of the deleter used to free the underlying BSON binary data.

## iterator

using bsoncxx::v_noabi::array::value::iterator = const_iterator

Equivalent to const_iterator.

## unique_ptr_type

using bsoncxx::v_noabi::array::value::unique_ptr_type = std::unique_ptr<uint8_t[], deleter_type>

The type of the unique pointer used to manage the underlying BSON binary data.

## Constructor & Destructor Documentation

## value() [1/3]

bsoncxx::v_noabi::array::value::value | ( | std::uint8_t * | data,
|  | std::size_t | length,
|  | deleter_type | deleter )

inline

Constructs a value from a buffer.

This constructor transfers ownership of the buffer to the resulting value. A user-provided deleter is used to destroy the buffer.

Warning
  For backward compatibility, length is NOT validated. When length is inconsistent with the embedded length as indicated by the BSON bytes, the BSON bytes may be parsed as "invalid" despite the BSON bytes themselves being valid.

Parameters

  data | A pointer to a buffer containing a valid BSON array.
  length | The length of the document.
  deleter | A user provided deleter.

## value() [2/3]

bsoncxx::v_noabi::array::value::value | ( | unique_ptr_type | ptr,
|  | std::size_t | length )

inline

Constructs a value from a std::unique_ptr to a buffer. The ownership of the buffer is transferred to the resulting value.

Warning
  For backward compatibility, length is NOT validated. When length is inconsistent with the embedded length as indicated by the BSON bytes, the BSON bytes may be parsed as "invalid" despite the BSON bytes themselves being valid.

Parameters

  ptr | A pointer to a buffer containing a valid BSON array.
  length | The length of the document.

## value() [3/3]

bsoncxx::v_noabi::array::value::value | ( | v_noabi::array::view | view | ) |

explicit

Constructs a value from a view of an array. The data referenced by the array::view will be copied into a new buffer managed by the constructed value.

Parameters

  view | A view of another array to copy.

## Member Function Documentation

## begin()

const_iterator bsoncxx::v_noabi::array::value::begin | ( |  | ) | const

inline

Returns
  A const_iterator to the first element of the array.

## cbegin()

const_iterator bsoncxx::v_noabi::array::value::cbegin | ( |  | ) | const

inline

Returns
  A const_iterator to the first element of the array.

## cend()

const_iterator bsoncxx::v_noabi::array::value::cend | ( |  | ) | const

inline

Returns
  A const_iterator to the past-the-end element of the array.

## data()

std::uint8_t const * bsoncxx::v_noabi::array::value::data | ( |  | ) | const

inline

Access the raw bytes of the underlying array.

Returns
  A (non-owning) pointer to the view's buffer.

## empty()

bool bsoncxx::v_noabi::array::value::empty | ( |  | ) | const

inline

Return true when this->length() == 5.

Warning
  For backward compatibility, this function does NOT check if the underlying BSON bytes represent a valid empty document.

## end()

const_iterator bsoncxx::v_noabi::array::value::end | ( |  | ) | const

inline

Returns
  A const_iterator to the past-the-end element of the array.

## find()

const_iterator bsoncxx::v_noabi::array::value::find | ( | std::uint32_t | i | ) | const

inline

Indexes into this BSON array. If the index is out-of-bounds, a past-the-end iterator will be returned. As BSON represents arrays as documents, the runtime of find() is linear in the length of the array.

Parameters

  i | The index of the element.

Returns
  An iterator to the element if it exists, or the past-the-end iterator.

## length()

std::size_t bsoncxx::v_noabi::array::value::length | ( |  | ) | const

inline

Gets the length of the underlying buffer in bytes.

Remarks
  This is not the number of BSON elements. To compute the number of elements, use std::distance.

Returns
  The length of the document, in bytes.

## operator v1::array::value() [1/2]

bsoncxx::v_noabi::array::value::operator v1::array::value | ( |  | ) | &&

inline explicit

Convert to the bsoncxx::v1 equivalent.

Preconditions:
  - If this->data() is not null, the size of the storage region pointed to by data must be greater than or equal to 5.
  - The "total number of bytes comprising the document" as indicated by the BSON bytes pointed-to by this->data() must be less than or equal to the size of the storage region pointed to by data.

Note
  this->size() is ignored.

## operator v1::array::value() [2/2]

bsoncxx::v_noabi::array::value::operator v1::array::value | ( |  | ) | const &

inline explicit

Convert to the bsoncxx::v1 equivalent.

Preconditions:
  - If this->data() is not null, the size of the storage region pointed to by data must be greater than or equal to 5.
  - The "total number of bytes comprising the document" as indicated by the BSON bytes pointed-to by this->data() must be less than or equal to the size of the storage region pointed to by data.

Note
  this->size() is ignored.

## operator v_noabi::array::view()

bsoncxx::v_noabi::array::value::operator v_noabi::array::view | ( |  | ) | const

inline noexcept

Conversion operator that provides a view given a value.

Returns
  A view over the value.

## operator[]()

v_noabi::document::element bsoncxx::v_noabi::array::value::operator[] | ( | std::uint32_t | i | ) | const

inline

Indexes into this BSON array. If the index is out-of-bounds, the invalid array::element will be returned. As BSON represents arrays as documents, the runtime of operator[] is linear in the length of the array.

Parameters

  i | The index of the element.

Returns
  The element if it exists, or the invalid element.

## release()

unique_ptr_type bsoncxx::v_noabi::array::value::release | ( |  | ) |

inline

Transfer ownership of the underlying buffer to the caller.

Warning
  After calling release() it is illegal to call any methods on this class, unless it is subsequently moved into.

Returns
  A std::unique_ptr with ownership of the buffer.

## reset()

void bsoncxx::v_noabi::array::value::reset | ( | v_noabi::array::view | view | ) |

inline

Replace the formerly-owned buffer with the new view. This will make a copy of the passed-in view.

## size()

std::size_t bsoncxx::v_noabi::array::value::size | ( |  | ) | const

inline

Gets the length of the underlying buffer in bytes.

Remarks
  This is not the number of BSON elements. To compute the number of elements, use std::distance.

Returns
  The length of the document, in bytes.

## view()

v_noabi::array::view bsoncxx::v_noabi::array::value::view | ( |  | ) | const

inline noexcept

Get a view over the array owned by this value.

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

- bsoncxx/v_noabi/bsoncxx/array/value.hpp