CBOR Values

Introduction

CborValue stores a CBOR value tree and reads or writes one complete data item. CborParseOptions sets input limits and the DAG-CBOR profile; CborFormatOptions selects the output profile. See Reading and Writing CBOR and DAG-CBOR for examples, supported types, tags, navigation, and wire rules.

Truncated input is rejected as ParseError by the throwing decoder, or as an empty optional by the tolerant decoder. Internal bounds errors and resource failures are not converted into malformed-input errors.

Text arguments accept String, StringEditor, and Core string literals directly, including when passed to set() or append(). Stored text retains its value if the original editor is changed later.

Interface

typedef util::List<CborValue> erbsland::data::cbor::CborArray: An ordered array of CBOR values.

typedef text::StringMap<CborValue> erbsland::data::cbor::CborMap: A string-keyed map of CBOR values.

class CborFormatOptions

Profile for serializing CBOR.

Public Functions

inline constexpr bool isDagCbor() const noexcept: Test whether strict DAG-CBOR output is selected.

inline constexpr CborFormatOptions &setDagCbor(bool value) noexcept: Select strict DAG-CBOR output.

struct CborLink

Opaque binary CID carried by DAG-CBOR tag 42.

Public Members

mem::ByteBlock cid: CID bytes without the wire prefix.

class CborParseOptions

Limits and profile for parsing CBOR.

Public Functions

inline constexpr bool isDagCbor() const noexcept: Select strict DAG-CBOR parsing.

inline constexpr CborParseOptions &setDagCbor(bool value) noexcept: Select strict DAG-CBOR parsing.

inline constexpr unit::ByteCount maximumInputLength() const noexcept: Get the input byte limit.

inline constexpr CborParseOptions &setMaximumInputLength(unit::ByteCount value) noexcept: Set the input byte limit.

inline constexpr unit::ItemCount maximumNesting() const noexcept: Get the nesting limit.

inline constexpr CborParseOptions &setMaximumNesting(unit::ItemCount value) noexcept: Set the nesting limit.

inline constexpr unit::ItemCount maximumValueCount() const noexcept: Get the value count limit.

inline constexpr CborParseOptions &setMaximumValueCount(unit::ItemCount value) noexcept: Set the value count limit.

inline constexpr unit::ByteCount maximumStringLength() const noexcept: Get the maximum byte length of one text string.

inline constexpr CborParseOptions &setMaximumStringLength(unit::ByteCount value) noexcept: Set the maximum byte length of one text string.

Public Static Attributes

static constexpr auto cDefaultMaximumInputLength = unit::ByteCount{16U * 1024U * 1024U}: Input limit.

static constexpr auto cDefaultMaximumNesting = unit::ItemCount{64U}: Container depth limit.

static constexpr auto cDefaultMaximumValueCount = unit::ItemCount{1'000'000U}: Value count limit.

static constexpr auto cDefaultMaximumStringLength = unit::ByteCount{8U * 1024U * 1024U}: String byte limit.

enum class erbsland::data::cbor::CborType : uint8_t

The semantic type of a supported CBOR value.

Values:

enumerator Null: Null.

enumerator Bool: Boolean.

enumerator Signed: Signed integer.

enumerator Unsigned: Unsigned integer.

enumerator Float: Floating-point value.

enumerator Text: UTF-8 text.

enumerator Bytes: Binary bytes.

enumerator Array: Ordered values.

enumerator Map: String-keyed values.

enumerator DateTime: Tagged date/time.

enumerator Link: DAG-CBOR CID link.

class CborValue

A copy-on-write CBOR value tree.

See: CBOR Values

Public Functions

CborValue(bool value)

Create a CBOR Boolean value.

Parameters:: value – The Boolean to store.

CborValue(int64_t value)

Create a CBOR signed 64-bit integer value.

Parameters:: value – The signed 64-bit integer to store.

CborValue(uint64_t value)

Create a CBOR unsigned 64-bit integer value.

Parameters:: value – The unsigned 64-bit integer to store.

CborValue(double value)

Create a CBOR double-precision number value.

Parameters:: value – The double-precision number to store.

CborValue(text::String value)

Create a CBOR text string value.

Parameters:: value – The text string to store.

template<typename tText> inline CborValue(tText &&value)

Create a text value from an implicitly convertible string, editor, or literal.

Parameters:: value – The text to store.

CborValue(mem::ByteBlock value)

Create a CBOR binary byte string value.

Parameters:: value – The binary byte string to store.

CborValue(CborArray value)

Create a CBOR array value.

Parameters:: value – The array to store.

CborValue(CborMap value)

Create a CBOR string-keyed map value.

Parameters:: value – The string-keyed map to store.

CborValue(time::Timestamp value)

Create a CBOR UTC date/time value.

Parameters:: value – The UTC date/time to store.

CborValue(CborLink value)

Create a CBOR CID link value.

Parameters:: value – The CID link to store.

template<std::integral T> inline CborValue(T value): Create an integer from any smaller native width.

CborType type() const noexcept: Get the semantic type.

inline bool is(CborType expected) const noexcept: Test for a semantic type.

unit::ItemCount itemCount() const noexcept: Get the array or map size, or zero.

CborValue get(unit::ItemIndex index) const: Get a child, or null when absent.

CborValue get(const text::String &key) const: Get a child, or null when absent.

CborValue getOrThrow(unit::ItemIndex index) const

Get a child or throw for an invalid index or type.

Throws:: err::OutOfRangeError – If the index does not identify an array element.

CborValue getOrThrow(const text::String &key) const

Get a child or throw for a missing key or invalid type.

Throws:: err::NotFoundError – If the requested key is absent.

std::optional<bool> getBool() const noexcept: Get a Boolean value.

std::optional<int64_t> getSigned() const noexcept: Get a signed integer.

std::optional<uint64_t> getUnsigned() const noexcept: Get an unsigned integer.

std::optional<double> getFloat() const noexcept: Get a floating-point value.

std::optional<text::String> getText() const noexcept: Get a text value.

std::optional<mem::ByteBlock> getBytes() const noexcept: Get a byte-string value.

std::optional<mem::ByteBlock> getLinkBytes() const noexcept: Get a CID link’s bytes.

std::optional<time::Timestamp> getTimestamp() const noexcept: Get a tagged date/time.

std::optional<CborArray> getArray() const noexcept: Get a copy of an array.

std::optional<CborMap> getMap() const noexcept: Get a copy of a map.

CborValue &set(unit::ItemIndex index, CborValue value): Replace or append an array child.

CborValue &set(const text::String &key, CborValue value): Replace or add a map member.

CborValue &append(CborValue value): Append an array child.

mem::ByteBlock toByteBlock(CborFormatOptions options = {}) const: Serialize one CBOR data item.

Public Static Functions

static auto fromByteBlock(const mem::ByteBlock &bytes, CborParseOptions options = {}) noexcept -> std::optional<CborValue>: Parse one complete CBOR data item, returning no value on error.

static auto fromByteBlockOrThrow(const mem::ByteBlock &bytes, CborParseOptions options = {}) -> CborValue 

Parse one complete CBOR data item.

Throws:: err::ParseError – For malformed or unsupported input.