std.cbor

rfc 8949; writer emits preferred (shortest) forms, reader allocates nothing

CborError

pub CborError :: errors {
    truncated,
    malformed,
    bad_text,
    too_deep,
}

• truncated: the bytes end in the middle of an item
• malformed: invalid header, or a stray break
• bad_text: a text string that is not UTF-8
• too_deep: skip hit 1000 nesting levels

Kind

pub Kind :: enum {
    uint,
    negint,
    bytes,
    text,
    array,
    map,
    tag,
    simple,
    boolean,
    null_value,
    undefined,
    float,
    end,
}

• uint: value
• negint: -1 - value
• bytes: data
• text: data, UTF-8
• array: value items follow
• map: value pairs follow, each a key and its value
• tag: the tag value; the item it tags follows
• simple: unassigned simple value, number in value
• boolean: value 1 for true, 0 for false
• float: number
• end: break closing an indefinite item

Item

pub Item :: struct {
    kind: Kind,
    value: u64,
    data: []const u8,
    number: f64,
    indefinite: bool,
}

from Reader.next; data slices the input

Item.as_i64

pub as_i64 :: fn(self: *Self) -> ?i64

uint/negint as i64; null if it doesn’t fit

Out

pub Out :: struct {
    w: *Writer,
    failed: bool,
}

caller keeps item counts right; end closes indefinites; write errors show in finish

Out.uint

pub uint :: fn(self: *Self, v: u64)

Out.int

pub int :: fn(self: *Self, v: i64)

Out.bytes

pub bytes :: fn(self: *Self, b: []const u8)

Out.text

pub text :: fn(self: *Self, s: []const u8)

utf-8 not checked

Out.begin_array

pub begin_array :: fn(self: *Self, n: usize)

write n items next

Out.begin_map

pub begin_map :: fn(self: *Self, n: usize)

write n key/value pairs next

Out.begin_array_indefinite

pub begin_array_indefinite :: fn(self: *Self)

write the items, then end

Out.begin_map_indefinite

pub begin_map_indefinite :: fn(self: *Self)

write the pairs, then end

Out.end

pub end :: fn(self: *Self)

closes an indefinite array or map

Out.tag

pub tag :: fn(self: *Self, t: u64)

tags the next item (1 = epoch seconds, 32 = uri, …)

Out.boolean

pub boolean :: fn(self: *Self, v: bool)

Out.null_value

pub null_value :: fn(self: *Self)

Out.undefined

pub undefined :: fn(self: *Self)

Out.simple

pub simple :: fn(self: *Self, v: u8)

0..19 or 32..255; anything else writes nothing

Out.float

pub float :: fn(self: *Self, v: f64)

shortest exact width; NaN as half

Out.raw

pub raw :: fn(self: *Self, b: []const u8)

pre-encoded cbor, as is

Out.finish

pub finish :: fn(self: *Self) -> void ! IoError

.write_failed if any write failed

writer

pub writer :: fn(w: *Writer) -> Out

Reader

pub Reader :: struct {
    data: []const u8,
    pos: usize,
}

one item at a time; a container’s items follow its header

Reader.at_end

pub at_end :: fn(self: *Self) -> bool

Reader.next

pub next :: fn(self: *Self) -> Item ! CborError

Reader.skip

pub skip :: fn(self: *Self) -> void ! CborError

skips the next item and everything in it

Reader.skip_contents

pub skip_contents :: fn(self: *Self, it: Item) -> void ! CborError

skips what it (just read) holds: items, pairs, tagged item, string parts

reader

pub reader :: fn(data: []const u8) -> Reader