xentara-utils v1.2.1
Xentara utilities library
Loading...
Searching...
No Matches
xentara::utils::cbor::Map Class Referencefinal

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

#include <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_errorThe 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
tagAlways 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:

decoder >> map;
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));
}
Header of a map, without the actual key/value pairs.
Definition Map.hpp:25
auto iterate(std::reference_wrapper< Decoder > decoder) const -> RangeIterator
Creates an iterator for help in decoding the entries in the map.
T emplace(T... args)
T reserve(T... args)
Exceptions
std::runtime_errorThe 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.