msgpack/decode
the low-level MessagePack node tree.
Since: Phase MP2
MpTree
(MpTree)
an owned, already-validated MessagePack document. Owns the bytes
MpNode
(MpNode)
a handle to one value inside a tree. Borrowed: it dangles once
mp-parse
(mp-parse [buf : Buf] :)
parse a buffer of MessagePack bytes into a node tree.
| buf | the MessagePack bytes (borrowed) |
(Result MpTree cstr) -- err with a static message on malformed input.
(let [r (mp-parse (hex->buf "81a16101"))] ; {"a":1}
(when (ok? r) (mp-tree-free (ok-val r))))
Since: Phase MP2
mp-tree-root
(mp-tree-root [tree : MpTree] :)
the tree's single top-level value.
| tree | the parsed tree |
MpNode -- the root node.
(mp-type-name t (mp-tree-root t)) ; => "object"
Since: Phase MP2
mp-tree-free
(mp-tree-free [tree : MpTree] :)
release the tree and the bytes every node points into.
| tree | the tree to release |
(mp-tree-free t)
Since: Phase MP2
mp-absent?
(mp-absent? [tree : MpTree node : MpNode] :)
true when the node does not refer to a value at all (what a
Since: Phase MP2
mp-nil?
(mp-nil? [tree : MpTree node : MpNode] :)
true when the node is MessagePack `nil` (0xc0).
Since: Phase MP2
mp-bool?
(mp-bool? [tree : MpTree node : MpNode] :)
true when the node is `true` or `false`.
Since: Phase MP2
mp-int?
(mp-int? [tree : MpTree node : MpNode] :)
true for every integer format (fixint, uint8..64, int8..64).
Since: Phase MP2
mp-float?
(mp-float? [tree : MpTree node : MpNode] :)
true for float32 / float64 only. MessagePack keeps integers
Since: Phase MP2
mp-num?
(mp-num? [tree : MpTree node : MpNode] :)
true for an int OR a float, matching what `mp-get-float`
Since: Phase MP2
mp-str?
(mp-str? [tree : MpTree node : MpNode] :)
true for the `str` formats. A `bin` is NOT a string: v0 maps
Since: Phase MP2
mp-arr?
(mp-arr? [tree : MpTree node : MpNode] :)
true for fixarray / array16 / array32.
Since: Phase MP2
mp-map?
(mp-map? [tree : MpTree node : MpNode] :)
true for fixmap / map16 / map32.
Since: Phase MP2
mp-type-name
(mp-type-name [tree : MpTree node : MpNode] :)
name the format family actually present at the node.
| tree | the owning tree | |
| node | the node to describe |
cstr -- a borrowed static name; do not free it.
(mp-type-name t (mp-tree-root t)) ; => "int"
Since: Phase MP2
mp-map-get
(mp-map-get [tree : MpTree node : MpNode key : cstr] :)
look up a string key inside a map node.
| tree | the owning tree | |
| node | the map node to search | |
| key | the string key to match (exact bytes) |
(Option MpNode) -- the value node, or none.
(mp-map-get t (mp-tree-root t) "id") ; => (some <node>)
Since: Phase MP2
mp-map-size
(mp-map-size [tree : MpTree node : MpNode] :)
the number of key/value pairs in a map node.
| tree | the owning tree | |
| node | the node to measure |
(Option int) -- none when the node is not a map. `(some 0)` is an empty map, which is a different answer from "not a map" -- hence the Option rather than a negative count.
(unwrap (mp-map-size t root)) ; => 2
Since: Phase MP2
mp-arr-size
(mp-arr-size [tree : MpTree node : MpNode] :)
the number of elements in an array node.
| tree | the owning tree | |
| node | the node to measure |
(Option int) -- none when the node is not an array.
(unwrap (mp-arr-size t root)) ; => 3
Since: Phase MP2
mp-arr-get
(mp-arr-get [tree : MpTree node : MpNode i : int] :)
the i-th element of an array node.
| tree | the owning tree | |
| node | the array node | |
| i | zero-based index |
(Option MpNode) -- none when the node is not an array or i is out of range.
(mp-arr-get t root 0) ; => (some <node>)
Since: Phase MP2
mp-get-int
(mp-get-int [tree : MpTree node : MpNode] :)
read the node as a 64-bit signed integer.
| tree | the owning tree | |
| node | the node to read |
(Result int cstr) -- err with a static message on a non-integer or an out-of-range value.
(ok-val (mp-get-int t (mp-tree-root t))) ; => 42
Since: Phase MP2
mp-get-bool
(mp-get-bool [tree : MpTree node : MpNode] :)
read the node as a boolean.
| tree | the owning tree | |
| node | the node to read |
(Result bool cstr) -- err on anything that is not `true` / `false`.
(ok-val (mp-get-bool t n)) ; => true
Since: Phase MP2
mp-get-float
(mp-get-float [tree : MpTree node : MpNode] :)
read the node as an IEEE-754 double.
| tree | the owning tree | |
| node | the node to read |
(Result float cstr) -- err on a non-numeric node.
(ok-val (mp-get-float t n)) ; => 7.1
Since: Phase MP2
mp-get-str
(mp-get-str [tree : MpTree node : MpNode] :)
read the node as a string, copied out of the tree.
| tree | the owning tree | |
| node | the node to read |
(Result cstr cstr) -- err on a non-string node (a `bin` included).
(ok-val (mp-get-str t n)) ; => "alice" (caller frees)
Since: Phase MP2
Internal definitions
__mp-null-ptr?-- internal: is this a null pointer?__mp-null-cstr?-- internal: is this a null string pointer?__mp-parse-raw-- internal: parse, as a bare pointer (NULL if malformed).__mp-tree-root-raw-- internal: the root offset as a bare int.__mp-map-get-raw-- internal: value offset for `key`, or -1 when absent.__mp-map-size-raw-- internal: entry count, or -1 when not a map.__mp-arr-size-raw-- internal: element count, or -1 when not an array.__mp-arr-get-raw-- internal: i-th element offset, or -1.__mp-int-status-- internal: 0 ok, -1 not an integer, -2 out of int64 range.__mp-int-value-- internal: the integer value (0 unless the status is 0).__mp-bool-value-- internal: the boolean value (false unless it is a bool).__mp-float-value-- internal: the double value (0.0 unless numeric).__mp-str-copy-- internal: malloc'd copy of a str node, or NULL.