# API Reference Generated from `src/avm_cbor.erl` by `scripts/gen-api-docs.py`. Do not edit this file by hand. Run: ```bash python3 scripts/gen-api-docs.py ``` ## Summary | Function | Purpose | |---|---| | `decode/1` | Decode one CBOR item using default options. | | `decode/2` | Decode one CBOR item using explicit options. | | `decode_start/2` | Start a pull-based decode with explicit options. | | `decode_continue/2` | Advance a continuation by a positive work budget. | | `decode_all/1` | Decode a complete CBOR sequence using default options. | | `decode_all/2` | Decode a complete CBOR sequence using explicit options. | | `decode_sequence/1` | Decode as many complete CBOR items as possible using default options. | | `decode_sequence/2` | Decode as many complete CBOR items as possible using explicit options. | | `encode/1` | Encode one supported Erlang value using default options. | | `encode/2` | Encode one supported Erlang value using explicit options. | | `partial_decode/1` | Validate and measure one CBOR item without eagerly constructing nested terms. | | `partial_decode/2` | Partially decode one CBOR item using explicit options. | | `partial_value_bytes/1` | Return the complete encoded bytes represented by a partial descriptor. | | `partial_deep_decode/1` | Materialize the value represented by a partial descriptor. | | `partial_skip/1` | Discard a validated partial descriptor. | | `partial_type/1` | Return the CBOR category represented by a partial descriptor. | | `partial_count/1` | Return an array item count or map pair count. | | `partial_tag/1` | Return the semantic tag number from a tag descriptor. | | `partial_size/1` | Return the content size of a byte or text string descriptor. | | `partial_offset/1` | Return the descriptor item offset. | | `partial_length/1` | Return the complete encoded length of a descriptor item. | | `partial_contents/1` | Return encoded child bytes for an array, map, or tag. | | `get/2` | Look up a key in a decoded CBOR map. | | `get/3` | Look up a key in a decoded CBOR map with a default. | | `require/2` | Require a key in a decoded CBOR map. | | `as_text/1` | Extract a decoded CBOR text string. | | `as_bytes/1` | Extract a decoded CBOR byte string. | | `as_int/1` | Extract a decoded CBOR integer. | | `as_bool/1` | Extract a decoded CBOR boolean. | | `ble_options/0` | Return strict options for small BLE-oriented payloads. | ## Functions ### `decode/1` Decode one CBOR item using default options. **Spec** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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** ```erlang 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.