encoding.cbor #

Description

encoding.cbor is an RFC 8949 Concise Binary Object Representation codec.

CBOR is a compact, schema-free binary format that supports the same value model as JSON (numbers, strings, arrays, maps) plus byte strings, tagged items, IEEE 754 floats at three widths, and a small set of "simple" values (true, false, null, undefined). It is used by COSE/CWT (IETF security stack), WebAuthn/FIDO2, the Matter smart-home protocol, and many IoT stacks because messages are typically 30–60 % smaller than JSON and parse without quoting/escaping.

Three layers of API are available:

• encode[T] / decode[T] — comptime-driven generic API. Works on primitives, strings, arrays, maps, structs (with @[cbor: 'name'], @[skip], @[cbor_rename_all: 'snake_case']), enums, time.Time (auto-tagged), and any type implementing Marshaler / Unmarshaler.
• Packer / Unpacker — manual streaming API. Use when the schema isn't known at compile time, or when you need full control over tags, indefinite-length items and simple values.
• Value sumtype — dynamic representation for round-tripping unknown payloads or inspecting tagged data.

Defaults follow RFC 8949 preferred serialisation (§4.2.2): floats shrink to the shortest IEEE 754 width that preserves their value, and every length argument uses the shortest encoding. Set EncodeOpts.canonical = true to additionally sort map keys for hash/signature stability (§4.2.1, deterministic encoding). Set EncodeOpts.validate_utf8 = true if callers may build strings from raw bytes (e.g. bytestr()) — the streaming pack_text trusts its input for performance, but encode[T] will then refuse to emit non-UTF-8 text strings the strict-by-default decoder would reject on the way back.

Usage

encode[T] / decode[T]

import encoding.cbor
import time

struct Person {
    name     string
    age      int
    email    ?string
    birthday time.Time
}

fn main() {
    bob := Person{
        name:     'Bob'
        age:      30
        birthday: time.now()
    }

    bytes := cbor.encode[Person](bob, cbor.EncodeOpts{})!
    // bytes is []u8 — wire-ready CBOR

    back := cbor.decode[Person](bytes, cbor.DecodeOpts{})!
    assert back.name == 'Bob'
}

Optional fields (?T) encode as CBOR null when set to none. Enums encode as their underlying integer.

Struct attributes

@[cbor_rename_all: 'kebab-case']
struct Login {
    user_name string @[cbor: 'u'] // emit/read key "u" (overrides rename_all)
    password  string @[skip]      // never serialise
    remember  bool // becomes "remember"
    is_admin  bool // becomes "is-admin"
}

The @[cbor_rename_all: '...'] attribute on a struct applies a global rename strategy to every field that doesn't have an explicit @[cbor: '...'] override — supported strategies: snake_case, camelCase, PascalCase, kebab-case, SCREAMING_SNAKE_CASE. Use @[cbor: '-'] as an alternative to @[skip].

Manual streaming with Packer / Unpacker

Use this when the schema is dynamic or when you need access to CBOR features that don't map directly to V types (tags, indefinite-length strings, custom simple values):

import encoding.cbor

fn main() {
    mut p := cbor.new_packer(cbor.EncodeOpts{})
    p.pack_array_header(3)
    p.pack_uint(42)
    p.pack_text('hello')
    p.pack_bool(true)
    bytes := p.bytes()

    mut u := cbor.new_unpacker(bytes, cbor.DecodeOpts{})
    n := u.unpack_array_header()! // 3
    a := u.unpack_uint()! // 42
    b := u.unpack_text()! // 'hello'
    c := u.unpack_bool()! // true
    _ = n
    _ = a
    _ = b
    _ = c
}

Dynamic values with Value

When the payload schema is unknown at compile time, decode into cbor.Value and walk the sumtype:

import encoding.cbor

fn main() {
    bytes := cbor.encode[map[string]int]({
        'a': 1
        'b': 2
    }, cbor.EncodeOpts{})!

    v := cbor.decode[cbor.Value](bytes, cbor.DecodeOpts{})!
    if val := v.get('a') {
        if i := val.as_int() {
            assert i == 1
        }
    }
}

Value covers every CBOR type: IntNum, FloatNum, Text, Bytes, Array, Map, Tag, Bool, Null, Undefined, Simple. Re-encoding a Value round-trips bit-for-bit when the source was already in preferred form.

Custom Marshaler / Unmarshaler

For types that need a custom on-wire representation, implement either side of the interface:

import encoding.cbor

struct Color {
mut:
    r u8
    g u8
    b u8
}

pub fn (c Color) to_cbor() []u8 {
    mut p := cbor.new_packer(cbor.EncodeOpts{})
    p.pack_array_header(3)
    p.pack_uint(c.r)
    p.pack_uint(c.g)
    p.pack_uint(c.b)
    return p.bytes().clone()
}

pub fn (mut c Color) from_cbor(data []u8) ! {
    mut u := cbor.new_unpacker(data, cbor.DecodeOpts{})
    n := u.unpack_array_header()!
    if n != 3 {
        return error('Color expects 3 elements')
    }
    c.r = u8(u.unpack_uint()!)
    c.g = u8(u.unpack_uint()!)
    c.b = u8(u.unpack_uint()!)
}

to_cbor must return exactly one well-formed CBOR data item — the generic encoder copies the bytes verbatim. from_cbor receives a slice already trimmed to one item.

Canonical (deterministic) encoding

For hashing or signing, set canonical: true so that map keys are sorted by length-then-lexicographic order (RFC 8949 §4.2.1):

import encoding.cbor

bytes := cbor.encode[map[string]int]({
    'b': 2
    'a': 1
}, cbor.EncodeOpts{ canonical: true })!
// keys are emitted in the order "a", "b" regardless of input order

Tags and time.Time

Values of type time.Time round-trip losslessly: whole-second values use tag 1 (epoch seconds, integer) for the smallest canonical wire, and sub-second values use tag 0 (RFC 3339 string with nanosecond precision) — necessary because a tag-1 float can't carry both a 10-digit unix epoch and 9 fractional digits. Decode accepts tag 0 (RFC 3339 text, any sub-second precision) or tag 1 (integer or float). Custom tags can be emitted/read via pack_tag / unpack_tag or by constructing a Value with cbor.new_tag(number, content).

Conformance

The test suite (vlib/encoding/cbor/tests/) covers every vector from RFC 8949 Appendix A, plus indefinite-length strings, depth limits, malformed-input rejection, UTF-8 validation, canonical ordering, and tagged time round-trips.

v test vlib/encoding/cbor/tests/

fn decode[T](data []u8, opts DecodeOpts) !T

decode parses CBOR bytes into a value of type T. Rejects extra bytes after the top-level item by default — callers feeding a buffer that holds multiple concatenated items (or that may carry an unrelated suffix) must opt in via DecodeOpts.allow_trailing_bytes = true and drive an Unpacker themselves.

A leading self-describe tag (d9 d9 f7, RFC 8949 §3.4.6) is stripped transparently so payloads encoded with EncodeOpts.self_describe round-trip through decode[T] without the caller having to peel it.

fn decode_from[T](mut r io.Reader, opts DecodeOpts) !T

decode_from reads bytes from r until EOF (or until DecodeOpts.max_stream_bytes is hit) and decodes a single top-level value. For multi-value streams, use Unpacker directly on a pre-buffered slice.

Always set max_stream_bytes on untrusted readers — otherwise a peer that never sends EOF blocks the call forever.

fn encode[T](val T, opts EncodeOpts) ![]u8

encode serialises any V value into CBOR bytes. The returned slice owns its backing buffer (V's GC tracks it) — no copy, so the returned bytes are safe to keep across calls and to pass to other modules.

fn encode_to[T](val T, mut w io.Writer, opts EncodeOpts) !

encode_to serialises val into an internal buffer, then writes the bytes to w in a loop until everything is accepted. Errors on the first I/O failure.

fn encode_value(v Value, opts EncodeOpts) ![]u8

encode_value emits a Value tree to a fresh byte slice with default opts.

fn new_bytes(b []u8) Value

new_bytes wraps a []u8 as a CBOR byte-string Value.

fn new_float(v f64) Value

new_float wraps an f64 as a CBOR FloatNum that re-encodes at full precision unless f64_to_half / f32 conversion is lossless.

fn new_int(n i64) Value

new_int wraps a signed i64 in a Value, picking unsigned vs negative.

fn new_negative(magnitude u64) Value

new_negative wraps the encoded argument of a major-type-1 value, where the actual integer is -1 - magnitude. Useful when magnitude exceeds i64.

fn new_packer(opts EncodeOpts) Packer

new_packer builds a Packer with the given options. opts.initial_cap reserves the buffer up-front; oversize is harmless, undersize triggers the usual growth policy.

fn new_tag(number u64, content Value) Value

new_tag wraps an existing Value with a tag number.

fn new_text(s string) Value

new_text wraps a string as a CBOR text Value.

fn new_uint(n u64) Value

new_uint wraps a u64 in a Value (unsigned-int variant).

fn new_unpacker(data []u8, opts DecodeOpts) Unpacker

new_unpacker constructs an Unpacker over the given byte slice.

fn FloatBits.from[W](input W) !FloatBits

fn Kind.from[W](input W) !Kind

interface Marshaler {
	to_cbor() []u8
}

Marshaler lets a user type control its own CBOR encoding. Returned bytes must be exactly one well-formed CBOR data item — the generic encoder copies them verbatim, so malformed output corrupts the surrounding stream.

interface Unmarshaler {
mut:
	from_cbor(data []u8) !
}

Unmarshaler is the reverse: given the bytes of one CBOR data item, populate the receiver. The slice is already trimmed to exactly one item by the generic decoder.

Implementers use a mut receiver:

pub fn (mut ip Ipv4) from_cbor(data []u8) ! { ... }

type Value = Array
	| Bool
	| Bytes
	| FloatNum
	| IntNum
	| Map
	| Null
	| Simple
	| Tag
	| Text
	| Undefined

Value is the dynamic representation of any CBOR data item. Use it when the schema isn't known at compile time, when you need to inspect tags, or when keys aren't strings:

v := cbor.decodecbor.Value! match v { cbor.Text { println(v.value) } else { ... } }

For known schemas prefer decode[YourStruct] — it's faster and avoids the heap allocations of building a Value tree.

fn (v &Value) is_nil() bool

is_nil returns true if v is the CBOR null value.

fn (v &Value) is_undefined() bool

is_undefined returns true if v is the CBOR undefined value.

fn (v &Value) as_int() ?i64

as_int returns the value as an i64 when it fits, or none otherwise. Returns none for FloatNum, Text, etc.

CBOR negative integers represent -1 - magnitude, so magnitude 2^63 - 1 maps to i64::min and magnitude 2^63 would map to -2^63 - 1 — outside i64 range — hence the strict ">" cutoff for negatives. Use as_uint plus the negative flag to recover the full -2^64..2^64-1 CBOR range.

fn (v &Value) as_uint() ?u64

as_uint returns the value as a u64 if it's a non-negative integer, else none.

fn (v &Value) as_float() ?f64

as_float returns the f64 value, or none if v isn't a FloatNum.

fn (v &Value) as_bool() ?bool

as_bool returns the boolean value, or none if v isn't a Bool.

fn (v &Value) as_string() ?string

as_string returns the text-string value, or none if v isn't Text.

fn (v &Value) as_bytes() ?[]u8

as_bytes returns the byte-string payload, or none if v isn't Bytes.

fn (v &Value) as_array() ?[]Value

as_array returns the elements of an Array, or none.

fn (v &Value) as_map() ?[]MapPair

as_map returns the pairs of a Map, or none.

fn (v &Value) as_tag() ?(u64, Value)

as_tag returns (number, content) of a Tag, or none.

fn (v &Value) get(key string) ?Value

get does a linear lookup of a string-keyed entry in a Map. O(n) — for hot paths decode into a typed struct or map[string]V.

fn (v &Value) at(index int) ?Value

at returns the element at index of an Array.

fn (v &Value) len() int

len returns the length of an Array, Map, Text, or Bytes value, or 0.

enum FloatBits as u8 {
	@none  = 0
	half   = 16
	single = 32
	double = 64
}

FloatBits records which IEEE 754 width the float was originally encoded at. The encoder honours this when re-emitting a Value, so round-tripping preserves the original byte width.

enum Kind {
	unsigned   // major type 0
	negative   // major type 1
	bytes      // major type 2 (definite or indefinite)
	text       // major type 3 (definite or indefinite)
	array_val  // major type 4 (definite or indefinite)
	map_val    // major type 5 (definite or indefinite)
	tag_val    // major type 6
	bool_val   // simple 20/21
	null_val   // simple 22
	undefined  // simple 23
	simple_val // other simple values
	float_val  // half/single/double
	break_code // 0xff outside a definite header
}

Kind classifies the next item without consuming it. Useful to branch before committing to a typed read.

struct Array {
pub mut:
	elements []Value
}

Array holds the elements of a CBOR array (major type 4).

struct Bool {
pub:
	value bool
}

Bool is the wrapped form of CBOR true/false (simple values 20/21).

struct Bytes {
pub mut:
	data []u8
}

Bytes is a CBOR byte string (major type 2).

struct DecodeOpts {
pub:
	max_depth            int = 256
	max_stream_bytes     int // 0 = unbounded for stream readers
	validate_utf8        bool = true
	deny_unknown_fields  bool // struct decode rejects unmapped keys
	deny_duplicate_keys  bool // Map decode rejects repeated keys
	allow_trailing_bytes bool // accept extra bytes after the top-level item
}

DecodeOpts tunes the decoder. Defaults are conservative: UTF-8 is validated, depth is capped to fend off stack-blow-up payloads, and duplicate map keys are tolerated (callers that need detection turn deny_duplicate_keys on).

struct EncodeOpts {
pub:
	initial_cap   int = 64
	canonical     bool // sort map keys, definite-length only
	self_describe bool // prepend tag 55799 (`d9 d9 f7`)
	// validate_utf8 makes encode[T] reject V `string` payloads that
	// contain non-UTF-8 bytes. Off by default to match the conventional
	// V invariant ("strings are UTF-8") and avoid paying for validation
	// on hot paths. Turn on at trust boundaries when callers may build
	// strings from raw bytes (e.g. `bytestr()`), so the wire stays
	// round-trip-safe against the strict-by-default decoder.
	validate_utf8 bool
}

EncodeOpts tunes the encoder. Defaults yield RFC 8949 preferred serialisation: floats shrink to the shortest IEEE 754 width that preserves their value, headers use the shortest length encoding.

Setting canonical = true additionally sorts map keys per RFC 8949 §4.2.1 (deterministic encoding) — useful for hashing/signing.

struct FloatNum {
pub:
	value f64
	bits  FloatBits = .@none
}

FloatNum is a CBOR floating-point value (major type 7, additional info 25/26/27). bits records the wire width for fidelity on re-encoding; the default .@none lets the encoder pick the shortest IEEE 754 width that preserves the value (RFC 8949 §4.2.2 preferred serialisation), so hand-built FloatNum literals don't accidentally lock in 8-byte output.

struct IntNum {
pub:
	negative  bool
	magnitude u64
}

IntNum holds the full unsigned/negative CBOR integer range. CBOR allows values from -(2^64) to 2^64-1, which exceeds either i64 or u64 alone, so the sign bit is split out and the magnitude carried as u64.

for unsigned: negative=false, magnitude=value for negative: negative=true, magnitude=encoded_argument actual integer = -1 - i64(magnitude) (when it fits i64)

struct IntRangeError {
	Error
pub:
	pos    int
	target string
	value  string
}

IntRangeError fires when a decoded integer doesn't fit the target type.

fn (e &IntRangeError) msg() string

msg formats an IntRangeError for IError.msg().

struct InvalidUtf8Error {
	Error
pub:
	pos int
}

InvalidUtf8Error fires when a text-string payload isn't valid UTF-8 and the decoder is configured to validate strings.

fn (e &InvalidUtf8Error) msg() string

msg formats an InvalidUtf8Error for IError.msg().

struct MalformedError {
	Error
pub:
	pos    int
	reason string
}

MalformedError fires when the byte stream violates RFC 8949 well-formedness.

fn (e &MalformedError) msg() string

msg formats a MalformedError for IError.msg().

struct Map {
pub mut:
	pairs []MapPair
}

Map holds the ordered key/value pairs of a CBOR map (major type 5).

struct MapPair {
pub:
	key   Value
	value Value
}

MapPair represents one key/value entry in a CBOR map. CBOR allows any data item as a key, so we keep an ordered list of pairs rather than using V's map[K]V.

struct MaxDepthError {
	Error
pub:
	pos       int
	max_depth int
}

MaxDepthError fires when nested arrays/maps exceed the configured cap.

fn (e &MaxDepthError) msg() string

msg formats a MaxDepthError for IError.msg().

struct Null {}

Null is the wrapped form of CBOR null (simple value 22).

struct Packer {
pub mut:
	buf  []u8
	opts EncodeOpts
mut:
	indef_string_open bool // top of the indef "stack" is text or bytes
	indef_other_depth int  // count of currently open indef arrays/maps
}

Packer accumulates CBOR bytes into an internal buffer. Use bytes() to retrieve the wire output, or reset() to reuse the buffer for the next message — that's the cheapest way to emit many small frames.

indef_string_open and indef_other_depth track open indefinite-length items so the encoder can reject malformed compositions: nested indef strings, indef array/map inside an indef string (RFC 8949 §3.2.3), or a stray break code.

fn (mut p Packer) bytes() []u8

bytes returns the encoded buffer. The returned slice aliases the Packer's storage — clone it if you keep using the Packer. This is a low-level accessor that does NOT verify the buffer holds a complete item; if you opened an indefinite-length container without closing it, the bytes will be malformed. Use pack_to (or encode[T]) for the validated path, or call is_complete() yourself.

fn (p &Packer) is_complete() bool

is_complete reports whether the buffer holds a sequence of fully closed items. False while an indefinite-length array, map, text, or bytes container is still open (waiting for pack_break).

fn (mut p Packer) pack[T](val T) !

pack encodes val into the packer's buffer using compile-time dispatch.

fn (mut p Packer) pack_array_header(n u64)

pack_array_header writes the prefix for a definite-length array.

fn (mut p Packer) pack_array_indef() !

pack_array_indef opens an indefinite-length array. Close with pack_break.

fn (mut p Packer) pack_bool(v bool)

pack_bool emits the simple value 20 (false) or 21 (true).

fn (mut p Packer) pack_break() !

pack_break writes the break stop code 0xff that terminates the most recently opened indefinite-length item. Errors when no item is open (the byte 0xff is otherwise reserved and emitting one would corrupt the stream).

fn (mut p Packer) pack_bytes(b []u8)

pack_bytes writes a byte string (major type 2).

fn (mut p Packer) pack_bytes_indef() !

pack_bytes_indef opens an indefinite-length byte string. Each chunk must be a definite-length byte string; close with pack_break.

fn (mut p Packer) pack_float(v f64)

pack_float emits the shortest IEEE 754 width that preserves the value, per RFC 8949 §4.2.2. NaN serialises as the canonical quiet NaN (0xf97e00), not the original payload.

fn (mut p Packer) pack_float16_bits(bits u16)

pack_float16_bits always emits a 2-byte IEEE 754 float.

fn (mut p Packer) pack_float32(v f32)

pack_float32 always emits a 4-byte IEEE 754 float.

fn (mut p Packer) pack_float64(v f64)

pack_float64 always emits an 8-byte IEEE 754 float.

fn (mut p Packer) pack_int(v i64)

pack_int picks the right major type for a signed integer. For values below i64.min that can still fit -1-u64, prefer pack_negative_arg.

fn (mut p Packer) pack_map_header(n u64)

pack_map_header writes the prefix for a definite-length map. The argument is the number of pairs, not items.

fn (mut p Packer) pack_map_indef() !

pack_map_indef opens an indefinite-length map. Close with pack_break.

fn (mut p Packer) pack_negative_arg(arg u64)

pack_negative_arg writes a major type 1 value where the encoded argument is arg and the represented integer is -1 - arg. Lets you emit values down to -2^64 (the lower bound of CBOR negative ints).

fn (mut p Packer) pack_null()

pack_null emits CBOR null (simple value 22, byte 0xf6).

fn (mut p Packer) pack_raw(raw RawMessage) !

pack_raw appends a RawMessage's bytes to the Packer without re-encoding. An empty RawMessage is rejected: emitting zero bytes would silently drop the slot when the value is a struct field or array element, shifting every subsequent item by one — almost always a caller bug.

fn (mut p Packer) pack_simple(v u8) !

pack_simple emits a CBOR simple value. Values 0..23 use the inline form, values 32..255 use the 1-byte trailer form. Values 24..31 are not well-formed per RFC 8949 §3.3 and are rejected here.

fn (mut p Packer) pack_tag(number u64)

pack_tag writes a tag header (major type 6). The next packed item is the tag's content.

fn (mut p Packer) pack_text(s string)

pack_text writes a UTF-8 text string (major type 3). Single-shot reservation: the head + payload bytes are appended via one capacity check and one memcpy.

fn (mut p Packer) pack_text_indef() !

pack_text_indef opens an indefinite-length text string. Each chunk must be a definite-length text string; close with pack_break.

fn (mut p Packer) pack_to(mut w io.Writer) !

pack_to is the streaming sibling of encode_to, for users who built their payload manually via the Packer API. Errors if any indefinite-length container is still open — emitting half-closed CBOR would produce a payload no decoder can parse.

fn (mut p Packer) pack_uint(v u64)

pack_uint emits a CBOR unsigned-integer (major type 0). Covers the full u64 range, including values above i64.max.

fn (mut p Packer) pack_undefined()

pack_undefined emits CBOR undefined (simple value 23, byte 0xf7).

fn (mut p Packer) pack_value(v Value) !

pack_value emits an arbitrary Value tree, honouring the original float width hint. Map keys are sorted when opts.canonical is set. Returns an error if the tree is malformed (e.g. a Tag with no content) — silently emitting a placeholder would corrupt round-trips.

fn (mut p Packer) reserve(n int)

reserve grows the buffer's capacity by at least n bytes. Useful before a string/binary write of known length to skip per-byte growth.

fn (mut p Packer) reset()

reset clears the buffer for reuse. The capacity is preserved, so this is the fast path for high-throughput senders.

struct RawMessage {
pub mut:
	data []u8
}

RawMessage holds the byte-exact encoding of one CBOR data item as it appeared on the wire. Useful for caching/forwarding code that wants to defer decoding of a nested field.

struct Envelope { id int payload cbor.RawMessage // bytes preserved as-is }

raw := cbor.decodecbor.RawMessage! back := cbor.encode(raw, cbor.EncodeOpts{})! // identical bytes

struct Simple {
pub:
	value u8
}

Simple is the catch-all for major type 7 simple values 0..255 not otherwise covered by Bool/Null/Undefined.

struct Tag {
pub:
	number      u64
	content_box []Value
}

Tag wraps a tagged data item (major type 6). The content is stored in a one-element slice rather than as a &Value reference: V can box and recurse a sumtype through a slice, while a direct &Value field requires manual heap allocation. Use tag.content() to access it.

fn (t &Tag) content() Value

content returns the Value enclosed by a Tag, or Null{} if missing.

struct Text {
pub:
	value string
}

Text is a CBOR text string (major type 3, valid UTF-8).

struct TypeMismatchError {
	Error
pub:
	pos      int
	expected string
	got      u8 // initial byte
}

TypeMismatchError fires when a typed read finds a different major type.

fn (e &TypeMismatchError) msg() string

msg formats a TypeMismatchError for IError.msg().

struct Undefined {}

Undefined is the wrapped form of CBOR undefined (simple value 23).

struct UnexpectedEofError {
	Error
pub:
	pos       int // position at which the read began
	need      i64 // bytes the decoder was trying to read
	remaining int // bytes actually available
}

UnexpectedEofError fires when the decoder runs past the end of its input. need is i64 so it can represent the full CBOR length range (which is u64 on the wire); huge values are clamped to i64::max for reporting.

fn (e &UnexpectedEofError) msg() string

msg formats an UnexpectedEofError for IError.msg().

struct UnknownFieldError {
	Error
pub:
	pos  int
	name string
}

UnknownFieldError fires when a struct decoded with deny_unknown_fields encounters an unmapped key.

fn (e &UnknownFieldError) msg() string

msg formats an UnknownFieldError for IError.msg().

struct Unpacker {
pub mut:
	data []u8
	pos  int
	opts DecodeOpts
}

Unpacker walks a CBOR byte slice. Operates non-allocating where possible; strings and bytes returned by unpack_text / unpack_bytes always own their storage so they outlive the input buffer.

fn (u &Unpacker) done() bool

done reports whether the unpacker has consumed every byte.

fn (mut u Unpacker) expect_break() !

expect_break consumes a single 0xff break code; errors otherwise.

fn (u &Unpacker) peek_break() bool

peek_break reports whether the next byte is the break stop code.

fn (u &Unpacker) peek_kind() !Kind

peek_kind classifies the next item without consuming any input.

fn (u &Unpacker) remaining() int

remaining returns the number of unread bytes.

fn (mut u Unpacker) skip_value() !

skip_value advances past one complete CBOR value without allocating. Honours the depth cap so adversarial deeply-nested input cannot blow the stack.

fn (mut u Unpacker) unpack[T]() !T

unpack reads one CBOR value from the buffer and converts it to T.

fn (mut u Unpacker) unpack_array_header() !i64

unpack_array_header reads the prefix of an array. Returns the count for definite-length arrays, or -1 for indefinite-length arrays (the caller then loops until peek_kind() == .break_code and consumes the break with expect_break).

fn (mut u Unpacker) unpack_bool() !bool

unpack_bool reads a CBOR boolean (simple 20/21). Position is rolled back on a type mismatch so callers can branch on peek_kind and try a different read.

fn (mut u Unpacker) unpack_bytes() ![]u8

unpack_bytes reads a definite or indefinite-length byte string. The returned slice is a clone, safe to retain after the unpacker is freed.

fn (mut u Unpacker) unpack_float() !f64

unpack_float reads a CBOR float of any width (half/single/double) and returns it as f64.

fn (mut u Unpacker) unpack_int() !i64

unpack_int reads any CBOR integer (major type 0 or 1) into i64. Errors when the magnitude exceeds i64 range; use unpack_int_full to pull values as u64 with a separate sign flag.

fn (mut u Unpacker) unpack_int_full() !(bool, u64)

unpack_int_full returns (negative, magnitude). For unsigned values negative=false and magnitude is the raw u64. For negative values negative=true and magnitude is the encoded argument (the integer itself is -1 - magnitude).

fn (mut u Unpacker) unpack_map_header() !i64

unpack_map_header reads the prefix of a map. Returns pair count or -1 for indefinite-length maps.

fn (mut u Unpacker) unpack_null() !

unpack_null consumes a CBOR null (0xf6) or errors with type mismatch. Position is rolled back on mismatch (same convention as unpack_bool).

fn (mut u Unpacker) unpack_raw() !RawMessage

unpack_raw captures the bytes of the next value without building a Value tree. Returns an owned clone, safe to outlive the unpacker.

fn (mut u Unpacker) unpack_simple() !u8

unpack_simple reads a simple value (0..255). Bool/null/undefined are also simple values; this method returns the raw u8.

fn (mut u Unpacker) unpack_tag() !u64

unpack_tag reads a tag header and returns the tag number. The caller must follow up by reading the tag content. Position is rolled back on any error so callers can branch on peek_kind and try a different read.

fn (mut u Unpacker) unpack_text() !string

unpack_text reads a definite or indefinite-length text string. The returned string owns its bytes (it's a clone of the input slice). UTF-8 validation runs unless DecodeOpts.validate_utf8 is false.

fn (mut u Unpacker) unpack_uint() !u64

unpack_uint reads a non-negative integer (major type 0). Errors on negatives, floats, or other major types. Position is rolled back on any error so callers can branch on peek_kind and try a different read (same convention as unpack_bool / unpack_text).

fn (mut u Unpacker) unpack_value() !Value

unpack_value materialises one CBOR data item as a Value.