xentara::utils::cbor::Array Class Reference

Header of an array, without the actual elements. More...

#include <cbor/Array.hpp>

Public Member Functions
constexpr	Array () noexcept=default
	Default constructor.
constexpr	Array (std::size_t size)
	Constructor for an array with a known length.
constexpr	Array (IndefiniteTag tag) noexcept
	Constructor for an indefinite length array.
constexpr auto	indefinite () const noexcept -> bool
	Checks whether the array has an indefinite length.
constexpr auto	size () const noexcept -> std::size_t
	Gets the length of the array.
constexpr auto	suggestCapacity () const noexcept -> std::size_t
	Suggests a capacity that can be used to reserve space in an std::vector or similar.
constexpr auto	empty () const noexcept -> bool
	Checks whether the array is empty.
auto	iterate (std::reference_wrapper< Decoder > decoder) const -> RangeIterator
	Creates an iterator for help in decoding the elements of the array.

Detailed Description

Header of an array, without the actual elements.

This object can be used to insert and extract CBOR arrays. This object only encodes and decodes the array header, consisting of the major type and the length. The array elements and (for indefinite length arrays) the stop code must be extracted and inserted separately.

Constructor & Destructor Documentation

Array() [1/3]

constexpr xentara::utils::cbor::Array::Array ( )

constexprdefaultnoexcept

Default constructor.

This constructor creates an empty array.

Array() [2/3]

constexpr xentara::utils::cbor::Array::Array ( std::size_t  size )

constexpr

Constructor for an array with a known length.

size The length of the array

Exceptions

std::length_error

The size is larger than supported. The largest possible std::size_t value is not supported because it is used to represent indefinite length arrays.

Array() [3/3]

constexpr xentara::utils::cbor::Array::Array ( IndefiniteTag  tag )

constexprnoexcept

Constructor for an indefinite length array.

Parameters

tag	Always pass kIndefinite as this parameter

See also

section 3.2.2) of RFC 8949.

Member Function Documentation

empty()

constexpr auto xentara::utils::cbor::Array::empty ( ) const -> bool

constexprnoexcept

Checks whether the array is empty.

Returns

Returns true if the array has length 0, or false if the length is greater 0, or if the array is indefinite length.

This function cannot determine whether arrays of indefinite length are empty, because that would require looking ahead into the JSON data that comes after the marker.

indefinite()

constexpr auto xentara::utils::cbor::Array::indefinite ( ) const -> bool

constexprnoexcept

Checks whether the array has an indefinite length.

Returns

true if the array has an indefinite length, ot false if it has a known length.

See also

section 3.2.2) of RFC 8949.

iterate()

auto xentara::utils::cbor::Array::iterate

(

std::reference_wrapper< Decoder >

decoder

)

const -> RangeIterator

Creates an iterator for help in decoding the elements of the array.

The returned iterator is not used to actually decode the individual elements, but only to keep track of whether all the elements have been read. The only thing the iterator decodes itself is the stop code (“beak”) at the end of an array with indefinite length.

To read an array of strings from a CBOR decoder, you can use the following code, for example:

xentara::utils::cbor::Array array;
decoder >> array;
 
std::vector<std::string> strings;
string.reserve(array.suggestCapacity());
 
for (auto dummy : array.iterate(decoder))
{
    std::string string;
    decoder >> string;
    strings.emplace_back(std::move(string));
}

Exceptions

std::runtime_error

The array has indefinite length, and an error occurred checking for the stop code at the beginning of the data.

size()

constexpr auto xentara::utils::cbor::Array::size ( ) const -> std::size_t

constexprnoexcept

Gets the length of the array.

Returns

The length of the array, or the largest possible std::size_t value if the array has indefinite length. You can compare the return value to kIndefinite to determine if the array has indefinite length.

suggestCapacity()

constexpr auto xentara::utils::cbor::Array::suggestCapacity ( ) const -> std::size_t

constexprnoexcept

Suggests a capacity that can be used to reserve space in an std::vector or similar.

This function can be used in preparation to decoding the array elements into a collection that supports preallocation, like e.g. std::vector. Calling reserve() on the collection with the return value of this function will reserve space for all the elements if the element count is known. If the array has indefinite length, then suggestCapacity() will return 0, and no preallocation will take place.

Returns

The length of the array, or 0 if the array has indefinite length.