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()

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()

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()}

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()}

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()}

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()}

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()}

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()}

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.

encode/1

Encode one supported Erlang value using default options.

Spec

encode(term()) -> encode_result()

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()

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.

partial_decode/1

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

Spec

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

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()}

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()}

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()}

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()}

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()}

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()}

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()}

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()}

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()}

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()}

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()}

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.

get/2

Look up a key in a decoded CBOR map.

Spec

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

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()

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()}}

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}

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}

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}

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}

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()

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.