git.iko.soy/urbit.org
on cfa2bed help sign in
urbit.org/reference/library/2p.md
241 lines 3.9 kB history raw
1+++
2title = "2p: Serialization"
3weight = 19
4template = "doc.html"
5+++
6### `++cue`
8Unpack atom to noun
10Produces a noun unpacked from atom `a`. The inverse of `jam`.
12#### Accepts
14An Atom.
16#### Produces
18A noun.
20#### Source
22```
23 ++ cue
24 ~/ %cue
25 |= a=@
26 ^- *
27 =+ b=0
28 =+ m=`(map @ *)`~
29 =< q
30 |- ^- [p=@ q=* r=(map @ *)]
31 ?: =(0 (cut 0 [b 1] a))
32 =+ c=(rub +(b) a)
33 [+(p.c) q.c (~(put by m) b q.c)]
34 =+ c=(add 2 b)
35 ?: =(0 (cut 0 [+(b) 1] a))
36 =+ u=$(b c)
37 =+ v=$(b (add p.u c), m r.u)
38 =+ w=[q.u q.v]
39 [(add 2 (add p.u p.v)) w (~(put by r.v) b w)]
40 =+ d=(rub c a)
41 [(add 2 p.d) (need (~(get by m) q.d)) m]
42```
44#### Examples
46```
47 > (cue 12)
48 1
50 > (cue 817)
51 [1 1]
53 > (cue 4.657)
54 [1 2]
56 > (cue 39.689)
57 [0 19]
58```
60---
61### `++jam`
63Pack noun to atom
65Produces an atom packed from noun `a`. The inverse of `cue`.
67#### Accepts
69`a` is a noun.
71#### Produces
73An atom.
75#### Source
77```
78 ++ jam
79 ~/ %jam
80 |= a=*
81 ^- @
82 =+ b=0
83 =+ m=`(map * @)`~
84 =< q
85 |- ^- [p=@ q=@ r=(map * @)]
86 =+ c=(~(get by m) a)
87 ?~ c
88 => .(m (~(put by m) a b))
89 ?: ?=(@ a)
90 =+ d=(mat a)
91 [(add 1 p.d) (lsh 0 1 q.d) m]
92 => .(b (add 2 b))
93 =+ d=$(a -.a)
94 =+ e=$(a +.a, b (add b p.d), m r.d)
95 [(add 2 (add p.d p.e)) (mix 1 (lsh 0 2 (cat 0 q.d q.e))) r.e]
96 ?: ?&(?=(@ a) (lte (met 0 a) (met 0 u.c)))
97 =+ d=(mat a)
98 [(add 1 p.d) (lsh 0 1 q.d) m]
99 =+ d=(mat u.c)
100 [(add 2 p.d) (mix 3 (lsh 0 2 q.d)) m]
101```
103#### Examples
105```
106 > (jam 1)
107 12
109 > (jam [1 1])
110 817
112 > (jam [1 2])
113 4.657
115 > (jam [~ u=19])
116 39.689
117```
119#### Discussion
121`mat` is only used internally as a helper to `jam`.
123---
124### `++mat`
126Length-encode
128Produces a cell whose tail `q` is atom `a` with a bit representation of
129its length prepended to it (as the least significant bits). The head `p`
130is the length of `q` in bits.
132#### Accepts
134`a` is an atom.
136#### Produces
138A cell of two atoms.
140#### Source
142```
143 ++ mat
144 ~/ %mat
145 |= a=@
146 ^- [p=@ q=@]
147 ?: =(0 a)
148 [1 1]
149 =+ b=(met 0 a)
150 =+ c=(met 0 b)
151 :- (add (add c c) b)
152 (cat 0 (bex c) (mix (end 0 (dec c) b) (lsh 0 (dec c) a)))
153```
155#### Examples
157```
158 > (mat 0xaaa)
159 [p=20 q=699.024]
161 > (met 0 q:(mat 0xaaa))
162 20
164 > `@ub`q:(mat 0xaaa)
165 0b1010.1010.1010.1001.0000
167 > =a =-(~&(- -) `@ub`0xaaa)
168 0b1010.1010.1010
170 > =b =-(~&(- -) `@ub`(xeb a))
171 0b1100
173 > =b =-(~&(- -) `@ub`(met 0 a))
174 0b1100
176 > =c =-(~&(- -) (xeb b))
177 4
179 > [`@ub`a `@ub`(end 0 (dec c) b) `@ub`(bex c)]
180 [0b1010.1010.1010 0b100 0b1.0000]
181```
184---
185### `++rub`
187Length-decode
189The inverse of `mat`. Accepts a cell of index `a` and a bitstring `b`
190and produces the cell whose tail `q` is the decoded atom at index `a`
191and whose head is the length of the encoded atom `q`, by which the
192offset `a` is advanced.
194#### Accepts
196`a` is an atom.
198`b` is a bitstring as an atom.
200#### Produces
202A cell of two atoms.
204#### Source
206```
207 ++ rub
208 ~/ %rub
209 |= [a=@ b=@]
210 ^- [p=@ q=@]
211 =+ ^= c
212 =+ [c=0 m=(met 0 b)]
213 |- ?< (gth c m)
214 ?. =(0 (cut 0 [(add a c) 1] b))
215 c
216 $(c +(c))
217 ?: =(0 c)
218 [1 0]
219 =+ d=(add a +(c))
220 =+ e=(add (bex (dec c)) (cut 0 [d (dec c)] b))
221 [(add (add c c) e) (cut 0 [(add d (dec c)) e] b)]
222```
224#### Examples
226```
227 > `@ub`(jam 0xaaa)
228 0b1.0101.0101.0101.0010.0000
230 > (rub 1 0b1.0101.0101.0101.0010.0000)
231 [p=20 q=2.730]
233 > `@ux`q:(rub 1 0b1.0101.0101.0101.0010.0000)
234 0xaaa
235```
237#### Discussion
239`rub` is only used internally as a helper to `cue`.
241---