git.iko.soy/urbit.org
on dc20522 help sign in
urbit.org/reference/library/2p.md
242 lines 3.9 kB history raw
1+++
2title = "2p: Serialization"
3weight = 19
4template = "doc.html"
5+++
7### `++cue`
9Unpack atom to noun
11Produces a noun unpacked from atom `a`. The inverse of `jam`.
13#### Accepts
15An 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 > (cue 12)
49 1
51 > (cue 817)
52 [1 1]
54 > (cue 4.657)
55 [1 2]
57 > (cue 39.689)
58 [0 19]
59```
61---
62### `++jam`
64Pack noun to atom
66Produces an atom packed from noun `a`. The inverse of `cue`.
68#### Accepts
70`a` is a noun.
72#### Produces
74An atom.
76#### Source
78```hoon
79 ++ jam
80 ~/ %jam
81 |= a=*
82 ^- @
83 =+ b=0
84 =+ m=`(map * @)`~
85 =< q
86 |- ^- [p=@ q=@ r=(map * @)]
87 =+ c=(~(get by m) a)
88 ?~ c
89 => .(m (~(put by m) a b))
90 ?: ?=(@ a)
91 =+ d=(mat a)
92 [(add 1 p.d) (lsh 0 1 q.d) m]
93 => .(b (add 2 b))
94 =+ d=$(a -.a)
95 =+ e=$(a +.a, b (add b p.d), m r.d)
96 [(add 2 (add p.d p.e)) (mix 1 (lsh 0 2 (cat 0 q.d q.e))) r.e]
97 ?: ?&(?=(@ a) (lte (met 0 a) (met 0 u.c)))
98 =+ d=(mat a)
99 [(add 1 p.d) (lsh 0 1 q.d) m]
100 =+ d=(mat u.c)
101 [(add 2 p.d) (mix 3 (lsh 0 2 q.d)) m]
102```
104#### Examples
106```
107 > (jam 1)
108 12
110 > (jam [1 1])
111 817
113 > (jam [1 2])
114 4.657
116 > (jam [~ u=19])
117 39.689
118```
120#### Discussion
122`mat` is only used internally as a helper to `jam`.
124---
125### `++mat`
127Length-encode
129Produces a cell whose tail `q` is atom `a` with a bit representation of
130its length prepended to it (as the least significant bits). The head `p`
131is the length of `q` in bits.
133#### Accepts
135`a` is an atom.
137#### Produces
139A cell of two atoms.
141#### Source
143```hoon
144 ++ mat
145 ~/ %mat
146 |= a=@
147 ^- [p=@ q=@]
148 ?: =(0 a)
149 [1 1]
150 =+ b=(met 0 a)
151 =+ c=(met 0 b)
152 :- (add (add c c) b)
153 (cat 0 (bex c) (mix (end 0 (dec c) b) (lsh 0 (dec c) a)))
154```
156#### Examples
158```
159 > (mat 0xaaa)
160 [p=20 q=699.024]
162 > (met 0 q:(mat 0xaaa))
163 20
165 > `@ub`q:(mat 0xaaa)
166 0b1010.1010.1010.1001.0000
168 > =a =-(~&(- -) `@ub`0xaaa)
169 0b1010.1010.1010
171 > =b =-(~&(- -) `@ub`(xeb a))
172 0b1100
174 > =b =-(~&(- -) `@ub`(met 0 a))
175 0b1100
177 > =c =-(~&(- -) (xeb b))
178 4
180 > [`@ub`a `@ub`(end 0 (dec c) b) `@ub`(bex c)]
181 [0b1010.1010.1010 0b100 0b1.0000]
182```
185---
186### `++rub`
188Length-decode
190The inverse of `mat`. Accepts a cell of index `a` and a bitstring `b`
191and produces the cell whose tail `q` is the decoded atom at index `a`
192and whose head is the length of the encoded atom `q`, by which the
193offset `a` is advanced.
195#### Accepts
197`a` is an atom.
199`b` is a bitstring as an atom.
201#### Produces
203A cell of two atoms.
205#### Source
207```hoon
208 ++ rub
209 ~/ %rub
210 |= [a=@ b=@]
211 ^- [p=@ q=@]
212 =+ ^= c
213 =+ [c=0 m=(met 0 b)]
214 |- ?< (gth c m)
215 ?. =(0 (cut 0 [(add a c) 1] b))
216 c
217 $(c +(c))
218 ?: =(0 c)
219 [1 0]
220 =+ d=(add a +(c))
221 =+ e=(add (bex (dec c)) (cut 0 [d (dec c)] b))
222 [(add (add c c) e) (cut 0 [(add d (dec c)) e] b)]
223```
225#### Examples
227```
228 > `@ub`(jam 0xaaa)
229 0b1.0101.0101.0101.0010.0000
231 > (rub 1 0b1.0101.0101.0101.0010.0000)
232 [p=20 q=2.730]
234 > `@ux`q:(rub 1 0b1.0101.0101.0101.0010.0000)
235 0xaaa
236```
238#### Discussion
240`rub` is only used internally as a helper to `cue`.
242---