xentara::utils::cbor::Map Class Reference

Header of a map, without the actual key/value pairs. More...

#include <xentara/utils/cbor/Map.hpp>

Public Member Functions
constexpr	Map () noexcept=default
	Default constructor.
constexpr	Map (std::size_t size)
	Constructor for a map with a known length.
constexpr	Map (IndefiniteTag tag) noexcept
	Constructor for an indefinite length map.
constexpr auto	indefinite () const noexcept -> bool
	Checks whether the map has an indefinite length.
constexpr auto	size () const noexcept -> std::size_t
	Gets the length of the map.
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 map is empty.
auto	iterate (std::reference_wrapper< Decoder > decoder) const -> RangeIterator
	Creates an iterator for help in decoding the entries in the map.

Detailed Description

Header of a map, without the actual key/value pairs.

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

Constructor & Destructor Documentation

Map() [1/3]

constexpr xentara::utils::cbor::Map::Map ( )

constexprdefaultnoexcept

Default constructor.

This constructor creates an empty map.

Map() [2/3]

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

constexpr

Constructor for a map with a known length.

size The length of the map

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

Map() [3/3]

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

constexprnoexcept

Constructor for an indefinite length map.

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::Map::empty ( ) const -> bool

constexprnoexcept

Checks whether the map is empty.

Returns

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

This function cannot determine whether maps 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::Map::indefinite ( ) const -> bool

constexprnoexcept

Checks whether the map has an indefinite length.

Returns

true if the map 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::Map::iterate

(

std::reference_wrapper< Decoder >

decoder

)

const -> RangeIterator

Creates an iterator for help in decoding the entries in the map.

The returned iterator is not used to actually decode the individual key/value pairs, but only to keep track of whether all the entries have been read. The only thing the iterator decodes itself is the stop code (“beak”) at the end of a map with indefinite length.

To read a map of string/string pairs from a CBOR decoder, you can use the following code, for example:

xentara::utils::cbor::Map map;
decoder >> map;
 
std::unordered_map<std::string, std::string> entries;
string.reserve(array.suggestCapacity());
 
for (auto dummy : array.iterate(decoder))
{
    std::string key, value;
    decoder >> key >> value;
    entries.emplace(std::move(key), std::move(value));
}

Exceptions

std::runtime_error

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

size()

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

constexprnoexcept

Gets the length of the map.

Returns

The length of the map, or a the largest possible std::size_t value if the map has indefinite length. You can return value that will compare equal to kIndefinite.

suggestCapacity()

constexpr auto xentara::utils::cbor::Map::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 key/value pairs into a collection that supports preallocation, like e.g. std::unordered_map. Calling reserve() on the collection with the return value of this function will reserve space for all the key/value pairs if the entry count is known. If the map has indefinite length, then suggestCapacity() will return 0, and no preallocation will take place.

Returns

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