git.iko.soy/urbit.org
on c19bc7a help sign in
urbit.org/docs/reference/library/2p.udon
246 lines 3.9 kB history raw
1:- :~ navhome/'/docs/'
2 sort/'19'
3 title/'2p: Serialization'
4 ==
6;>
9# 2p: serialization
11### `++cue`
13Unpack atom to noun
15Produces a noun unpacked from atom `a`. The inverse of `jam`.
17#### Accepts
19An Atom.
21#### Produces
23A noun.
25#### Source
27```
28 ++ cue
29 ~/ %cue
30 |= a=@
31 ^- *
32 =+ b=0
33 =+ m=`(map @ *)`~
34 =< q
35 |- ^- [p=@ q=* r=(map @ *)]
36 ?: =(0 (cut 0 [b 1] a))
37 =+ c=(rub +(b) a)
38 [+(p.c) q.c (~(put by m) b q.c)]
39 =+ c=(add 2 b)
40 ?: =(0 (cut 0 [+(b) 1] a))
41 =+ u=$(b c)
42 =+ v=$(b (add p.u c), m r.u)
43 =+ w=[q.u q.v]
44 [(add 2 (add p.u p.v)) w (~(put by r.v) b w)]
45 =+ d=(rub c a)
46 [(add 2 p.d) (need (~(get by m) q.d)) m]
47```
49#### Examples
51```
52 > (cue 12)
53 1
55 > (cue 817)
56 [1 1]
58 > (cue 4.657)
59 [1 2]
61 > (cue 39.689)
62 [0 19]
63```
65---
66### `++jam`
68Pack noun to atom
70Produces an atom packed from noun `a`. The inverse of `cue`.
72#### Accepts
74`a` is a noun.
76#### Produces
78An atom.
80#### Source
82```
83 ++ jam
84 ~/ %jam
85 |= a=*
86 ^- @
87 =+ b=0
88 =+ m=`(map * @)`~
89 =< q
90 |- ^- [p=@ q=@ r=(map * @)]
91 =+ c=(~(get by m) a)
92 ?~ c
93 => .(m (~(put by m) a b))
94 ?: ?=(@ a)
95 =+ d=(mat a)
96 [(add 1 p.d) (lsh 0 1 q.d) m]
97 => .(b (add 2 b))
98 =+ d=$(a -.a)
99 =+ e=$(a +.a, b (add b p.d), m r.d)
100 [(add 2 (add p.d p.e)) (mix 1 (lsh 0 2 (cat 0 q.d q.e))) r.e]
101 ?: ?&(?=(@ a) (lte (met 0 a) (met 0 u.c)))
102 =+ d=(mat a)
103 [(add 1 p.d) (lsh 0 1 q.d) m]
104 =+ d=(mat u.c)
105 [(add 2 p.d) (mix 3 (lsh 0 2 q.d)) m]
106```
108#### Examples
110```
111 > (jam 1)
112 12
114 > (jam [1 1])
115 817
117 > (jam [1 2])
118 4.657
120 > (jam [~ u=19])
121 39.689
122```
124#### Discussion
126`mat` is only used internally as a helper to `jam`.
128---
129### `++mat`
131Length-encode
133Produces a cell whose tail `q` is atom `a` with a bit representation of
134its length prepended to it (as the least significant bits). The head `p`
135is the length of `q` in bits.
137#### Accepts
139`a` is an atom.
141#### Produces
143A cell of two atoms.
145#### Source
147```
148 ++ mat
149 ~/ %mat
150 |= a=@
151 ^- [p=@ q=@]
152 ?: =(0 a)
153 [1 1]
154 =+ b=(met 0 a)
155 =+ c=(met 0 b)
156 :- (add (add c c) b)
157 (cat 0 (bex c) (mix (end 0 (dec c) b) (lsh 0 (dec c) a)))
158```
160#### Examples
162```
163 > (mat 0xaaa)
164 [p=20 q=699.024]
166 > (met 0 q:(mat 0xaaa))
167 20
169 > `@ub`q:(mat 0xaaa)
170 0b1010.1010.1010.1001.0000
172 > =a =-(~&(- -) `@ub`0xaaa)
173 0b1010.1010.1010
175 > =b =-(~&(- -) `@ub`(xeb a))
176 0b1100
178 > =b =-(~&(- -) `@ub`(met 0 a))
179 0b1100
181 > =c =-(~&(- -) (xeb b))
182 4
184 > [`@ub`a `@ub`(end 0 (dec c) b) `@ub`(bex c)]
185 [0b1010.1010.1010 0b100 0b1.0000]
186```
189---
190### `++rub`
192Length-decode
194The inverse of `mat`. Accepts a cell of index `a` and a bitstring `b`
195and produces the cell whose tail `q` is the decoded atom at index `a`
196and whose head is the length of the encoded atom `q`, by which the
197offset `a` is advanced.
199#### Accepts
201`a` is an atom.
203`b` is a bitstring as an atom.
205#### Produces
207A cell of two atoms.
209#### Source
211```
212 ++ rub
213 ~/ %rub
214 |= [a=@ b=@]
215 ^- [p=@ q=@]
216 =+ ^= c
217 =+ [c=0 m=(met 0 b)]
218 |- ?< (gth c m)
219 ?. =(0 (cut 0 [(add a c) 1] b))
220 c
221 $(c +(c))
222 ?: =(0 c)
223 [1 0]
224 =+ d=(add a +(c))
225 =+ e=(add (bex (dec c)) (cut 0 [d (dec c)] b))
226 [(add (add c c) e) (cut 0 [(add d (dec c)) e] b)]
227```
229#### Examples
231```
232 > `@ub`(jam 0xaaa)
233 0b1.0101.0101.0101.0010.0000
235 > (rub 1 0b1.0101.0101.0101.0010.0000)
236 [p=20 q=2.730]
238 > `@ux`q:(rub 1 0b1.0101.0101.0101.0010.0000)
239 0xaaa
240```
242#### Discussion
244`rub` is only used internally as a helper to `cue`.
246---