git.iko.soy/urbit.org
on 140ac0e help sign in
urbit.org/docs/programming/reference/library/2p.md
225 lines 4.0 kB history raw
1# 2p: serialization
2### `++cue`
4Unpack atom to noun
6Produces a noun unpacked from atom `a`. The inverse of jam.
8Accepts
9-------
11`a` is an atom.
13Produces
14--------
16A `++noun`.
18Source
19------
21 ++ cue :: unpack
22 ~/ %cue
23 |= a/@
24 ^- *
25 =+ b=0
26 =+ m=`(map @ *)`~
27 =< q
28 |- ^- {p/@ q/* r/(map @ *)}
29 ?: =(0 (cut 0 [b 1] a))
30 =+ c=(rub +(b) a)
31 [+(p.c) q.c (~(put by m) b q.c)]
32 =+ c=(add 2 b)
33 ?: =(0 (cut 0 [+(b) 1] a))
34 =+ u=$(b c)
35 =+ v=$(b (add p.u c), m r.u)
36 =+ w=[q.u q.v]
37 [(add 2 (add p.u p.v)) w (~(put by r.v) b w)]
38 =+ d=(rub c a)
39 [(add 2 p.d) (need (~(get by m) q.d)) m]
40 ::
43Examples
44--------
46 > (cue 12)
47 1
48 > (cue 817)
49 [1 1]
50 > (cue 4.657)
51 [1 2]
52 > (cue 39.689)
53 [0 19]
56***
57### `++jam`
59Unpack noun to atom
61Produces an atom unpacked from noun `a`. The inverse of cue.
63Accepts
64-------
66`a` is a noun.
68Produces
69--------
71An atom.
73Source
74------
76 ++ jam :: pack
77 ~/ %jam
78 |= a/*
79 ^- @
80 =+ b=0
81 =+ m=`(map * @)`~
82 =< q
83 |- ^- {p/@ q/@ r/(map * @)}
84 =+ c=(~(get by m) a)
85 ?~ c
86 => .(m (~(put by m) a b))
87 ?: ?=(@ a)
88 =+ d=(mat a)
89 [(add 1 p.d) (lsh 0 1 q.d) m]
90 => .(b (add 2 b))
91 =+ d=$(a -.a)
92 =+ e=$(a +.a, b (add b p.d), m r.d)
93 [(add 2 (add p.d p.e)) (mix 1 (lsh 0 2 (cat 0 q.d q.e))) r.e]
94 ?: ?&(?=(@ a) (lte (met 0 a) (met 0 u.c)))
95 =+ d=(mat a)
96 [(add 1 p.d) (lsh 0 1 q.d) m]
97 =+ d=(mat u.c)
98 [(add 2 p.d) (mix 3 (lsh 0 2 q.d)) m]
99 ::
102Examples
103--------
105 > (jam 1)
106 12
107 > (jam [1 1])
108 817
109 > (jam [1 2])
110 4.657
111 > (jam [~ u=19])
112 39.689
116***
117### `++mat`
119Length-encode
121Produces a cell whose tail `q` is atom `a` with a bit representation of
122its length prepended to it (as the least significant bits). The head `p`
123is the length of `q` in bits.
125Accepts
126-------
128`a` is an atom.
130Produces
131--------
133A cell of two atoms, `p` and `q`.
135Source
136------
138 ++ mat :: length-encode
139 ~/ %mat
140 |= a/@
141 ^- {p/@ q/@}
142 ?: =(0 a)
143 [1 1]
144 =+ b=(met 0 a)
145 =+ c=(met 0 b)
146 :- (add (add c c) b)
147 (cat 0 (bex c) (mix (end 0 (dec c) b) (lsh 0 (dec c) a)))
148 ::
151Examples
152--------
154 > (mat 0xaaa)
155 [p=20 q=699.024]
156 > (met 0 q:(mat 0xaaa))
157 20
158 > `@ub`q:(mat 0xaaa)
159 0b1010.1010.1010.1001.0000
160 > =a =-(~&(- -) `@ub`0xaaa)
161 0b1010.1010.1010
162 > =b =-(~&(- -) `@ub`(xeb a))
163 0b1100
164 > =b =-(~&(- -) `@ub`(met 0 a))
165 0b1100
166 > =c =-(~&(- -) (xeb b))
167 4
168 > [`@ub`a `@ub`(end 0 (dec c) b) `@ub`(bex c)]
169 [0b1010.1010.1010 0b100 0b1.0000]
173***
174### `++rub`
176Length-decode
178The inverse of `++mat`. Accepts a cell of index `a` and a bitstring `b`
179and produces the cell whose tail `q` is the decoded atom at index `a`
180and whose head is the length of the encoded atom `q`, by which the
181offset `a` is advanced. Only used internally as a helper cue.
183Accepts
184-------
186`a` is an atom.
188`b` is a bitstring as an atom.
190Produces
191--------
193A cell of two atoms, `p` and `q`.
195Source
196------
198 ++ rub :: length-decode
199 ~/ %rub
200 |= {a/@ b/@}
201 ^- {p/@ q/@}
202 =+ ^= c
203 =+ [c=0 m=(met 0 b)]
204 |- ?< (gth c m)
205 ?. =(0 (cut 0 [(add a c) 1] b))
206 c
207 $(c +(c))
208 ?: =(0 c)
209 [1 0]
210 =+ d=(add a +(c))
211 =+ e=(add (bex (dec c)) (cut 0 [d (dec c)] b))
212 [(add (add c c) e) (cut 0 [(add d (dec c)) e] b)]
215Examples
216--------
218 > `@ub`(jam 0xaaa)
219 0b1.0101.0101.0101.0010.0000
220 > (rub 1 0b1.0101.0101.0101.0010.0000)
221 [p=20 q=2.730]
222 > `@ux`q:(rub 1 0b1.0101.0101.0101.0010.0000)
223 0xaaa
225***