API Reference

Generated from src/avm_cbor.erl by scripts/gen-api-docs.py.

Do not edit this file by hand. Run:

python3 scripts/gen-api-docs.py

Summary

Functions

decode/1

Decode one CBOR item using default options.

Spec

decode(term()) -> decode_result()

Example

{ok, 42, <<>>} = avm_cbor:decode(<<16#18, 42>>).

What it does

Reads one complete CBOR value and returns the decoded value plus trailing bytes.

What it is not

It is not a strict whole-binary decoder; use decode_all/1 for that.

decode/2

Decode one CBOR item using explicit options.

Spec

decode(term(), term()) -> decode_result()

Example

{ok, [1, 2], <<>>} = avm_cbor:decode(<<16#82, 1, 2>>, [{max_items, 3}]).

What it does

Applies caller-provided limits and feature flags while decoding one item.

What it is not

It does not silently ignore invalid options.

decode_start/2

Start a pull-based decode with explicit options.

Spec

decode_start(term(), term()) -> {ok, term()} | {error, term()}

Example

{ok, State} = avm_cbor:decode_start(<<16#82, 1, 2>>, []),
{done, [1, 2], <<>>} = avm_cbor:decode_continue(State, 100).

What it does

Returns an opaque immutable continuation without performing parser work.

What it is not

It is not a streaming-input API; the complete binary must already exist.

decode_continue/2

Advance a continuation by a positive work budget.

Spec

decode_continue(term(), term()) -> {done, term(), binary()} | {more, term()} | {error, term()}

Example

{ok, State} = avm_cbor:decode_start(<<16#82, 1, 2>>, []),
{done, [1, 2], <<>>} = avm_cbor:decode_continue(State, 100).

What it does

Returns done, more, or a controlled decode error after bounded parser transitions.

What it is not

It does not sleep, yield, or schedule the next call for the caller.

decode_all/1

Decode a complete CBOR sequence using default options.

Spec

decode_all(term()) -> {ok, list()} | {error, term()}

Example

{ok, [1, 2]} = avm_cbor:decode_all(<<1, 2>>).

What it does

Consumes all CBOR items and succeeds only when no trailing data remains.

What it is not

It is not meant for incomplete stream buffers; use decode_sequence/1 for that.

decode_all/2

Decode a complete CBOR sequence using explicit options.

Spec

decode_all(term(), term()) -> {ok, list()} | {error, term()}

Example

{ok, [1, 2]} = avm_cbor:decode_all(<<1, 2>>, [{max_items, 2}]).

What it does

Consumes all CBOR items while applying caller-provided limits and feature flags.

What it is not

It does not accept malformed or incomplete trailing data.

decode_sequence/1

Decode as many complete CBOR items as possible using default options.

Spec

decode_sequence(term()) -> {ok, list(), binary()} | {error, term()}

Example

{ok, [1], <<16#82, 2>>} = avm_cbor:decode_sequence(<<1, 16#82, 2>>).

What it does

Returns complete items and keeps a truncated final item as Rest.

What it is not

It is not a whole-input validation helper; use decode_all/1 for that.

decode_sequence/2

Decode as many complete CBOR items as possible using explicit options.

Spec

decode_sequence(term(), term()) -> {ok, list(), binary()} | {error, term()}

Example

{ok, [1, 2], <<>>} = avm_cbor:decode_sequence(<<1, 2>>, [{max_items, 2}]).

What it does

Like decode_sequence/1, but applies caller-provided limits and feature flags.

What it is not

It does not hide malformed data; malformed items still return errors.

sequence_fold/3

Fold complete CBOR sequence items without building a result list.

Spec

sequence_fold(term(), term(), term()) -> {ok, term(), binary()} | {error, term()}

Example

Sum = fun(Item, Acc) -> {cont, Item + Acc} end,
{ok, 6, <<>>} = avm_cbor:sequence_fold(<<1, 2, 3>>, Sum, 0).

What it does

Calls Fun(Item, Acc) for each complete item; {cont, NewAcc} continues, while {halt, Result} returns the result and unconsumed Rest.

What it is not

It is not a streaming-input API; a truncated final item is returned unchanged as Rest, and callback exceptions are not caught.

encode/1

Encode one supported Erlang value using default options.

Spec

encode(term()) -> encode_result()

Example

{ok, <<16#82, 1, 2>>} = avm_cbor:encode([1, 2]).

What it does

Produces definite-length CBOR for the documented public term representation.

What it is not

It does not enable preferred or deterministic encoding unless requested with encode/2.

encode/2

Encode one supported Erlang value using explicit options.

Spec

encode(term(), list()) -> encode_result()

Example

{ok, <<23>>} = avm_cbor:encode(23, [{preferred, true}]).

What it does

Supports preferred and deterministic serialization while enforcing caller-provided limits.

What it is not

It does not support arbitrary Erlang terms outside the documented representation.

encode_with_size/1

Encode one value and return its exact byte size using default options.

Spec

encode_with_size(term()) -> {ok, binary(), non_neg_integer()} | {error, term()}

Example

{ok, <<16#82, 1, 2>>, 3} = avm_cbor:encode_with_size([1, 2]).

What it does

Returns {ok, Binary, Size}, where Size is measured from the binary produced by the single encode operation.

What it is not

It is not a separate sizing or preflight pass.

encode_with_size/2

Encode one value and return its exact byte size using explicit options.

Spec

encode_with_size(term(), term()) -> {ok, binary(), non_neg_integer()} | {error, term()}

Example

{ok, <<23>>, 1} = avm_cbor:encode_with_size(23, [{preferred, true}]).

What it does

Applies the same normalized options and limits as encode/2, then returns {ok, Binary, Size}.

What it is not

It does not estimate a size or encode the value twice.

encode_sequence/1

Encode a list of values as an RFC 8742 CBOR sequence using default options.

Spec

encode_sequence(term()) -> {ok, binary()} | {error, term()}

Example

{ok, <<1, 2, 3>>} = avm_cbor:encode_sequence([1, 2, 3]).

What it does

Encodes each list element as one CBOR data item and concatenates the item binaries while enforcing sequence limits.

What it is not

It does not encode the input list as a CBOR array.

encode_sequence/2

Encode a list of values as an RFC 8742 CBOR sequence using explicit options.

Spec

encode_sequence(term(), term()) -> {ok, binary()} | {error, term()}

Example

{ok, <<1, 2>>} = avm_cbor:encode_sequence([1, 2], [{max_items, 2}]).

What it does

Applies the supplied encoding options to every item and enforces cumulative max_items and max_bytes limits.

What it is not

It does not accept a non-list or improper list as a sequence.

validate_all/1

Validate exactly one complete CBOR item using default partial-decoding limits.

Spec

validate_all(term()) -> ok | {error, term()}

Example

ok = avm_cbor:validate_all(<<16#82, 1, 2>>).

What it does

Checks the entire item and returns ok only when no trailing bytes remain, without materializing its nested Erlang value.

What it is not

It is not a CBOR sequence validator; additional complete items are reported as trailing bytes.

validate_all/2

Validate exactly one complete CBOR item using explicit options.

Spec

validate_all(term(), term()) -> ok | {error, term()}

Example

ok = avm_cbor:validate_all(<<23>>, [{preferred, true}]).

What it does

Applies partial-decoding limits plus deterministic or preferred checks and rejects trailing bytes.

What it is not

It does not return the decoded value; use decode_all/2 when the materialized term is required.

partial_decode/1

Validate and measure one CBOR item without eagerly constructing nested terms.

Spec

partial_decode(term()) -> {ok, term(), binary()} | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#82, 1, 2>>),
array = avm_cbor:partial_type(Partial).

What it does

Returns an opaque descriptor and trailing bytes using constrained partial-path defaults.

What it is not

The descriptor layout is private; use the partial_* accessors.

partial_decode/2

Partially decode one CBOR item using explicit options.

Spec

partial_decode(term(), term()) -> {ok, term(), binary()} | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#81, 1>>, [{max_depth, 2}]),
array = avm_cbor:partial_type(Partial).

What it does

Applies decode limits, deterministic/preferred checks, and the partial max_string_size limit.

What it is not

It does not bypass validation simply because nested terms are deferred.

partial_value_bytes/1

Return the complete encoded bytes represented by a partial descriptor.

Spec

partial_value_bytes(term()) -> binary() | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#82, 1, 2>>),
<<16#82, 1, 2>> = avm_cbor:partial_value_bytes(Partial).

What it does

Returns the validated item as a sub-binary.

What it is not

It does not return only the child contents; use partial_contents/1 for that.

partial_deep_decode/1

Materialize the value represented by a partial descriptor.

Spec

partial_deep_decode(term()) -> {ok, term()} | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#82, 1, 2>>),
{ok, [1, 2]} = avm_cbor:partial_deep_decode(Partial).

What it does

Fully decodes the validated item only when the caller needs it.

What it is not

It does not accept forged or malformed descriptors.

partial_skip/1

Discard a validated partial descriptor.

Spec

partial_skip(term()) -> ok | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#82, 1, 2>>),
ok = avm_cbor:partial_skip(Partial).

What it does

Returns ok after validating that the value is a descriptor.

What it is not

It does not scan or materialize the represented value again.

partial_type/1

Return the CBOR category represented by a partial descriptor.

Spec

partial_type(term()) -> atom() | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#82, 1, 2>>),
array = avm_cbor:partial_type(Partial).

What it does

Reports unsigned, negative, bytes, text, array, map, tag, float, or simple.

What it is not

It does not return an Erlang runtime type.

partial_count/1

Return an array item count or map pair count.

Spec

partial_count(term()) -> non_neg_integer() | undefined | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#A1, 1, 2>>),
1 = avm_cbor:partial_count(Partial).

What it does

Returns undefined for descriptor types without a count.

What it is not

It does not count nested descendants.

partial_tag/1

Return the semantic tag number from a tag descriptor.

Spec

partial_tag(term()) -> non_neg_integer() | undefined | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#C1, 1>>),
1 = avm_cbor:partial_tag(Partial).

What it does

Returns undefined for non-tag descriptors.

What it is not

It does not interpret tag semantics.

partial_size/1

Return the content size of a byte or text string descriptor.

Spec

partial_size(term()) -> non_neg_integer() | undefined | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#62, "ok">>),
2 = avm_cbor:partial_size(Partial).

What it does

Reports the content byte length and returns undefined for other descriptor types.

What it is not

It does not report the complete encoded item length.

partial_offset/1

Return the descriptor item offset.

Spec

partial_offset(term()) -> non_neg_integer() | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#82, 1, 2>>),
0 = avm_cbor:partial_offset(Partial).

What it does

Reports the start offset recorded for the represented item.

What it is not

It does not return a child index.

partial_length/1

Return the complete encoded length of a descriptor item.

Spec

partial_length(term()) -> non_neg_integer() | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#82, 1, 2>>),
3 = avm_cbor:partial_length(Partial).

What it does

Includes the CBOR header and any break marker.

What it is not

It does not return only string content length.

partial_contents/1

Return encoded child bytes for an array, map, or tag.

Spec

partial_contents(term()) -> {ok, binary()} | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#82, 1, 2>>),
{ok, <<1, 2>>} = avm_cbor:partial_contents(Partial).

What it does

The returned binary can be walked with repeated partial_decode calls.

What it is not

It does not deep-decode the children.

partial_map_fold/3

Fold a map descriptor as opaque key and value descriptors.

Spec

partial_map_fold(term(), fun((term(), term(), term()) -> {cont, term()} | {halt, term()}), term()) -> {ok, term()} | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#A1, 1, 2>>),
Count = fun(_Key, _Value, Acc) -> {cont, Acc + 1} end,
{ok, 1} = avm_cbor:partial_map_fold(Partial, Count, 0).

What it does

Calls Fun(KeyDescriptor, ValueDescriptor, Acc) in CBOR map order; {cont, NewAcc} continues and {halt, Result} stops early.

What it is not

It does not materialize the map or catch callback exceptions.

partial_array_fold/3

Fold an array descriptor as opaque element descriptors.

Spec

partial_array_fold(term(), fun((term(), term()) -> {cont, term()} | {halt, term()}), term()) -> {ok, term()} | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#82, 1, 2>>),
Sum = fun(Element, Acc) ->
    {ok, Value} = avm_cbor:partial_deep_decode(Element),
    {cont, Acc + Value}
end,
{ok, 3} = avm_cbor:partial_array_fold(Partial, Sum, 0).

What it does

Calls Fun(ElementDescriptor, Acc) in array order with the same continue and early-halt contract as partial_map_fold/3.

What it is not

It does not materialize the array or accept a non-array descriptor.

partial_select/2

Select requested keys from a map descriptor in one pass.

Spec

partial_select(term(), term()) -> {ok, [{term(), term()}], [term()]} | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#A2, 1, 2, 3, 4>>),
{ok, [{1, Value}], [9]} = avm_cbor:partial_select(Partial, [1, 9]),
{ok, 2} = avm_cbor:partial_deep_decode(Value).

What it does

Returns {ok, Found, Missing}; found pairs retain CBOR map order, missing keys retain request order, and values remain descriptors.

What it is not

It does not accept duplicate requested keys or deep-decode selected values; the first matching map entry wins.

partial_map_find/2

Find the first matching key in a map descriptor.

Spec

partial_map_find(term(), term()) -> {ok, term()} | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#A1, 1, 2>>),
{ok, Value} = avm_cbor:partial_map_find(Partial, 1),
{ok, 2} = avm_cbor:partial_deep_decode(Value).

What it does

Compares decoded keys exactly and returns the matching opaque value descriptor without decoding that value.

What it is not

It does not return a materialized value or search past the first match.

partial_array_nth/2

Return an opaque array element descriptor by zero-based index.

Spec

partial_array_nth(term(), term()) -> {ok, term()} | {error, term()}

Example

{ok, Partial, <<>>} = avm_cbor:partial_decode(<<16#82, 1, 2>>),
{ok, Second} = avm_cbor:partial_array_nth(Partial, 1),
{ok, 2} = avm_cbor:partial_deep_decode(Second).

What it does

Traverses the array until the requested non-negative index and returns that element descriptor.

What it is not

It is not one-based and does not deep-decode the selected element.

get/2

Look up a key in a decoded CBOR map.

Spec

get(term(), {map, list()}) -> {ok, term()} | error

Example

Map = {map, [{{text, <<"id">>}, 7}]},
{ok, 7} = avm_cbor:get({text, <<"id">>}, Map).

What it does

Searches the {map, Pairs} representation and returns {ok, Value} when present.

What it is not

It is not an Erlang map helper; decoded CBOR maps are represented as pair lists.

get/3

Look up a key in a decoded CBOR map with a default.

Spec

get(term(), {map, list()}, term()) -> term()

Example

Map = {map, []},
unknown = avm_cbor:get({text, <<"id">>}, Map, unknown).

What it does

Returns the value when present, otherwise returns the supplied default.

What it is not

It does not distinguish a missing key from a present value equal to the default.

require/2

Require a key in a decoded CBOR map.

Spec

require(term(), {map, list()}) -> {ok, term()} | {error, {missing_key, term()}}

Example

Map = {map, [{{text, <<"id">>}, 7}]},
{ok, 7} = avm_cbor:require({text, <<"id">>}, Map).

What it does

Returns a structured missing-key error when the key is absent.

What it is not

It does not validate the value type; use as_text/1, as_int/1, or related helpers.

as_text/1

Extract a decoded CBOR text string.

Spec

as_text(term()) -> {ok, binary()} | {error, bad_type}

Example

{ok, <<"hello">>} = avm_cbor:as_text({text, <<"hello">>}).

What it does

Accepts {text, Bin} and returns the UTF-8 binary.

What it is not

It does not accept arbitrary binaries; use as_bytes/1 for byte strings.

as_bytes/1

Extract a decoded CBOR byte string.

Spec

as_bytes(term()) -> {ok, binary()} | {error, bad_type}

Example

{ok, <<1, 2>>} = avm_cbor:as_bytes(<<1, 2>>).

What it does

Accepts a binary byte string and returns it unchanged.

What it is not

It does not accept {text, Bin}; text and byte strings are distinct.

as_int/1

Extract a decoded CBOR integer.

Spec

as_int(term()) -> {ok, integer()} | {error, bad_type}

Example

{ok, 42} = avm_cbor:as_int(42).

What it does

Accepts Erlang integers returned by the decoder.

What it is not

It does not coerce floats, strings, or binaries into integers.

as_bool/1

Extract a decoded CBOR boolean.

Spec

as_bool(term()) -> {ok, boolean()} | {error, bad_type}

Example

{ok, true} = avm_cbor:as_bool(true).

What it does

Accepts only true or false.

What it is not

It does not treat other values as truthy or falsey.

ble_options/0

Return strict options for small BLE-oriented payloads.

Spec

ble_options() -> list()

Example

Options = avm_cbor:ble_options(),
{max_depth, 8} = lists:keyfind(max_depth, 1, Options).

What it does

Provides conservative depth, item, byte, and string limits with floats, tags, and indefinite-length items disabled.

What it is not

It is not a Bluetooth transport implementation or a performance benchmark.