std/cbor
On this page
Index
- type
Value- method
Value.to_int - method
Value.get - method
Value.diagnostic - method
Value.to_json
- method
- type
CborErr- method
CborErr.display
- method
- type
Unm - fn
from_int - fn
encode - fn
decode - fn
decode_prefix - fn
well_formed - fn
from_json - fn
marshal - fn
unmarshal - fn
unmarshal_prefix - fn
unm_new - fn
dec_error - fn
is_null - fn
to_str - fn
to_int - fn
to_float - fn
to_bool - fn
to_bytes - fn
items - fn
pairs - fn
key_text - fn
key_int - fn
unknown_key - fn
sorted_keys - fn
to_value - fn
from_value - fn
to_time - fn
to_duration - fn
from_time - fn
from_duration - fn
put_head - fn
put_int - fn
put_float - fn
put_text - fn
put_bytes - fn
put_value - fn
det_keys - fn
bad_arity - fn
bad_variant
Types
Value
enum Value {
Uint(n: UInt64)
Nint(n: UInt64)
ByteString(b: Bytes)
TextString(s: Str)
Array(items: List[Value])
Map(pairs: List[(Value, Value)])
Tag(num: UInt64, v: Value)
Simple(n: Int)
Bool(b: Bool)
Null
Undefined
Float(f: Float)
}A CBOR data item. Integers keep the full range of the format: Uint(n)
is n (0 to 2^64-1) and Nint(n) is -1-n (-1 down to -2^64), so
Nint(0) is -1. A map keeps its pairs in order, with any key. Simple(n)
is a simple value other than false, true, null and undefined (n is 0 to
19 or 32 to 255). A decoded half, single or double float is a Float;
encode writes the shortest of the three that holds the value.
Value.to_int
fn (v: Value) to_int() -> Int?The Int an item holds: Uint or Nint within Int’s range; None for any other item or a value past Int.
Value.get
fn (v: Value) get(key: Str) -> Value?The value in a map with a text key; None for a missing key or a value that is not a map.
Value.diagnostic
fn (v: Value) diagnostic() -> StrRFC 8949 Section 8: integers in decimal, byte strings as h'0102’, text in
double quotes with JSON escapes (non ASCII as \uXXXX), arrays [1, 2],
maps {1: 2}, tags N(item), simple(N), true, false, null,
undefined, and floats with a decimal point or exponent (1.0, 1.5e+300,
NaN, Infinity, -Infinity; ES6 number text). An indefinite length item
is written as its definite value.
Value.to_json
fn (v: Value) to_json() -> json.Value ! CborErrRFC 8949 Section 6.2, the item as JSON: integers and floats as numbers
(a float without a fraction stays a float; a Nint or Uint past Int is
a number text through Float), byte strings as base64url text without
padding, text as text, Null and Undefined as null, true and false,
arrays, maps with text, integer, float, bool or null keys as objects (the
key’s text), tags dropped (their content kept), Simple(n) as the text
simple(n). NaN and infinity are Invalid, as is a map key that is
not one of those kinds.
CborErr
enum CborErr {
Truncated
Syntax(msg: Str)
Invalid(msg: Str)
Limit(msg: Str)
Type(msg: Str)
}Truncated: the data ends inside an item. Syntax: not well formed
(a reserved additional information, a break outside an indefinite item,
an indefinite string with a chunk of another kind or an indefinite
chunk, an odd number of items in an indefinite map, a simple value below
32 written in two bytes). Invalid: well formed but refused (text that
is not UTF-8, a repeated map key when reject_dup_keys is set, data after
the item, a Simple or float that cannot be written). Limit: more
nesting than max_depth, or an item larger than the data.
CborErr.display
fn (e: CborErr) display() -> StrUnm
struct Unm {
strict: Bool
err: CborErr?
}The state of one unmarshal: the first type mismatch is kept and the
decode goes on (fxamacker’s UnmarshalTypeError); strict makes a map
key no field names an error.
Functions
from_int
fn from_int(n: Int) -> ValueThe value of n as an Int-valued item: Uint(n) for n >= 0, Nint(-1-n)
below.
encode
fn encode(v: Value, deterministic: Bool = false) -> Bytes ! CborErrEncodes v with the preferred serialization (shortest integer heads, the
shortest float that holds the value, definite lengths). With
deterministic (RFC 8949 Section 4.2.1) the pairs of every map are
sorted bytewise by the encoding of the key. Invalid for a Simple
that is not 0 to 19 or 32 to 255.
decode
fn decode(data: Bytes, max_depth: Int = 128, reject_dup_keys: Bool = false) -> Value ! CborErrOne data item; nothing may follow it. max_depth bounds the nesting of
arrays, maps and tags; with reject_dup_keys a map with a repeated key
is Invalid.
decode_prefix
fn decode_prefix(data: Bytes, max_depth: Int = 128, reject_dup_keys: Bool = false) -> (Value, Int) ! CborErrThe first item of data and the number of bytes it takes; what follows is left for the caller (a CBOR sequence, RFC 8742).
well_formed
fn well_formed(data: Bytes, max_depth: Int = 128) -> BoolWhether data is exactly one well formed item (no UTF-8 or duplicate key check), as RFC 8949 Section 5.3.1 defines it.
from_json
fn from_json(j: json.Value) -> ValueRFC 8949 Section 6.1, the JSON value as an item: Null, Bool, Int as Uint
or Nint, Num as Float, Str as TextString, List as Array, Object as Map
with text keys. A Trusted value is its text.
marshal
fn marshal[T: Cbor](v: T, deterministic: Bool = true) -> Bytes ! CborErrDecoded into a struct that derives Cbor, by the types of its fields.
The call is compiled as a call of the function derive Cbor generates
for T. deterministic sorts map keys (section 4.2.1).
unmarshal
fn unmarshal[T: Cbor](data: Bytes, strict: Bool = false, max_depth: Int = 128) -> T ! CborErrdata (exactly one item) decoded into T.
unmarshal_prefix
fn unmarshal_prefix[T: Cbor](data: Bytes, strict: Bool = false, max_depth: Int = 128) -> (T, Int) ! CborErrThe first item of data decoded into T, and the bytes it used.
unm_new
fn unm_new(strict: Bool) -> Unmdec_error
fn dec_error(st: Unm) -> CborErr?is_null
fn is_null(v: Value) -> Boolto_str
fn to_str(v: Value, var st: Unm) -> (Bool, Str)to_int
fn to_int(v: Value, var st: Unm) -> (Bool, Int)to_float
fn to_float(v: Value, var st: Unm) -> (Bool, Float)to_bool
fn to_bool(v: Value, var st: Unm) -> (Bool, Bool)to_bytes
fn to_bytes(v: Value, var st: Unm) -> (Bool, Bytes)items
fn items(v: Value, want: Str, var st: Unm) -> (Bool, List[Value])pairs
fn pairs(v: Value, want: Str, var st: Unm) -> (Bool, List[(Value, Value)])key_text
fn key_text(k: Value) -> Str?key_int
fn key_int(k: Value) -> Int?unknown_key
fn unknown_key(var st: Unm, want: Str, k: Value)sorted_keys
fn sorted_keys(keys: List[Str]) -> List[Str]to_value
fn to_value(v: Value, var st: Unm) -> (Bool, Value)from_value
fn from_value(v: Value) -> Valueto_time
fn to_time(v: Value, var st: Unm) -> (Bool, Time)to_duration
fn to_duration(v: Value, var st: Unm) -> (Bool, Duration)from_time
fn from_time(t: Time) -> Valuefrom_duration
fn from_duration(d: Duration) -> Valueput_head
fn put_head(var out: BytesBuilder, major: Int, n: Int)put_int
fn put_int(var out: BytesBuilder, n: Int)put_float
fn put_float(var out: BytesBuilder, f: Float)put_text
fn put_text(var out: BytesBuilder, s: Str)put_bytes
fn put_bytes(var out: BytesBuilder, b: Bytes)put_value
fn put_value(var out: BytesBuilder, v: Value, deterministic: Bool) -> () ! CborErrdet_keys
fn det_keys(keys: List[Str]) -> List[Str]bad_arity
fn bad_arity(var st: Unm, want: Str, got: Int, need: Int)bad_variant
fn bad_variant(var st: Unm, want: Str, got: Str)