git.iko.soy/urbit.org
on 99bdb21 help sign in
urbit.org/content/docs/hoon/reference/stdlib/2p.md
248 lines 3.6 kB history raw
1+++
2title = "2p: Serialization"
3weight = 19
4template = "doc.html"
5+++
7## `++cue` {#cue}
9Unpack atom to noun
11Produces a noun unpacked from atom `a`. The inverse of [+jam](#jam).
13#### Accepts
15`a` is an atom.
17#### Produces
19A noun.
21#### Source
23```hoon
24++ cue
25 ~/ %cue
26 |= a=@
27 ^- *
28 =+ b=0
29 =+ m=`(map @ *)`~
30 =< q
31 |- ^- [p=@ q=* r=(map @ *)]
32 ?: =(0 (cut 0 [b 1] a))
33 =+ c=(rub +(b) a)
34 [+(p.c) q.c (~(put by m) b q.c)]
35 =+ c=(add 2 b)
36 ?: =(0 (cut 0 [+(b) 1] a))
37 =+ u=$(b c)
38 =+ v=$(b (add p.u c), m r.u)
39 =+ w=[q.u q.v]
40 [(add 2 (add p.u p.v)) w (~(put by r.v) b w)]
41 =+ d=(rub c a)
42 [(add 2 p.d) (need (~(get by m) q.d)) m]
43```
45#### Examples
47```
48> (jam [1 2 3])
493.426.417
51> (cue 3.426.417)
52[1 2 3]
53```
55---
57## `++jam` {#jam}
59Pack noun to atom
61Produces an atom packed from noun `a`. The inverse of [+cue](#cue).
63#### Accepts
65`a` is a noun.
67#### Produces
69An atom.
71#### Source
73```hoon
74++ jam
75 ~/ %jam
76 |= a=*
77 ^- @
78 =+ b=0
79 =+ m=`(map * @)`~
80 =< q
81 |- ^- [p=@ q=@ r=(map * @)]
82 =+ c=(~(get by m) a)
83 ?~ c
84 => .(m (~(put by m) a b))
85 ?: ?=(@ a)
86 =+ d=(mat a)
87 [(add 1 p.d) (lsh 0 q.d) m]
88 => .(b (add 2 b))
89 =+ d=$(a -.a)
90 =+ e=$(a +.a, b (add b p.d), m r.d)
91 [(add 2 (add p.d p.e)) (mix 1 (lsh [0 2] (cat 0 q.d q.e))) r.e]
92 ?: ?&(?=(@ a) (lte (met 0 a) (met 0 u.c)))
93 =+ d=(mat a)
94 [(add 1 p.d) (lsh 0 q.d) m]
95 =+ d=(mat u.c)
96 [(add 2 p.d) (mix 3 (lsh [0 2] q.d)) m]
97```
99#### Examples
101```
102> (jam 1)
10312
105> (cue 12)
107```
109```
110> (jam [1 1])
111817
113> (cue 817)
114[1 1]
115```
117```
118> (jam [~ u=19])
11939.689
121> (cue 39.689)
122[0 19]
123```
125---
127## `++mat`
129Length-encode
131Produces a cell whose tail `q` is atom `a` with a bit representation of
132its length prepended to it (as the least significant bits). The head `p`
133is the length of `q` in bits.
135#### Accepts
137`a` is an atom.
139#### Produces
141A cell of two atoms, `p` and `q`.
143#### Source
145```hoon
146++ mat
147 ~/ %mat
148 |= a=@
149 ^- [p=@ q=@]
150 ?: =(0 a)
151 [1 1]
152 =+ b=(met 0 a)
153 =+ c=(met 0 b)
154 :- (add (add c c) b)
155 (cat 0 (bex c) (mix (end [0 (dec c)] b) (lsh [0 (dec c)] a)))
156```
158#### Examples
160```
161> (mat 0xaaa)
162[p=20 q=699.024]
164> (met 0 q:(mat 0xaaa))
16520
167> `@ub`q:(mat 0xaaa)
1680b1010.1010.1010.1001.0000
170> =a =-(~&(- -) `@ub`0xaaa)
1710b1010.1010.1010
173> =b =-(~&(- -) `@ub`(xeb a))
1740b1100
176> =b =-(~&(- -) `@ub`(met 0 a))
1770b1100
179> =c =-(~&(- -) (xeb b))
182> [`@ub`a `@ub`(end 0 (dec c) b) `@ub`(bex c)]
183[0b1010.1010.1010 0b100 0b1.0000]
184```
186#### Discussion
188`mat` is only used internally as a helper to [`jam`](#jam).
190---
192## `++rub`
194Length-decode
196The inverse of `mat`. Accepts a cell of index `a` and a bitstring `b`
197and produces the cell whose tail `q` is the decoded atom at index `a`
198and whose head is the length of the encoded atom `q`, by which the
199offset `a` is advanced.
201#### Accepts
203`a` is an atom.
205`b` is a bitstring as an atom.
207#### Produces
209A cell of two atoms, `p` and `q`.
211#### Source
213```hoon
214++ rub
215 ~/ %rub
216 |= [a=@ b=@]
217 ^- [p=@ q=@]
218 =+ ^= c
219 =+ [c=0 m=(met 0 b)]
220 |- ?< (gth c m)
221 ?. =(0 (cut 0 [(add a c) 1] b))
222 c
223 $(c +(c))
224 ?: =(0 c)
225 [1 0]
226 =+ d=(add a +(c))
227 =+ e=(add (bex (dec c)) (cut 0 [d (dec c)] b))
228 [(add (add c c) e) (cut 0 [(add d (dec c)) e] b)]
229```
231#### Examples
233```
234> `@ub`(jam 0xaaa)
2350b1.0101.0101.0101.0010.0000
237> (rub 1 0b1.0101.0101.0101.0010.0000)
238[p=20 q=2.730]
240> `@ux`q:(rub 1 0b1.0101.0101.0101.0010.0000)
2410xaaa
242```
244#### Discussion
246`rub` is only used internally as a helper to [`cue`](#cue).
248---