git.iko.soy/urbit.org
on 6d45ede help sign in
urbit.org/docs/hoon/library/2p.md
230 lines 4.1 kB history raw
1---
2navhome: /docs
3---
6# 2p: serialization
7### `++cue`
9Unpack atom to noun
11Produces a noun unpacked from atom `a`. The inverse of jam.
13Accepts
14-------
16`a` is an atom.
18Produces
19--------
21A `++noun`.
23Source
24------
26 ++ cue :: unpack
27 ~/ %cue
28 |= a/@
29 ^- *
30 =+ b=0
31 =+ m=`(map @ *)`~
32 =< q
33 |- ^- {p/@ q/* r/(map @ *)}
34 ?: =(0 (cut 0 [b 1] a))
35 =+ c=(rub +(b) a)
36 [+(p.c) q.c (~(put by m) b q.c)]
37 =+ c=(add 2 b)
38 ?: =(0 (cut 0 [+(b) 1] a))
39 =+ u=$(b c)
40 =+ v=$(b (add p.u c), m r.u)
41 =+ w=[q.u q.v]
42 [(add 2 (add p.u p.v)) w (~(put by r.v) b w)]
43 =+ d=(rub c a)
44 [(add 2 p.d) (need (~(get by m) q.d)) m]
45 ::
48Examples
49--------
51 > (cue 12)
52 1
53 > (cue 817)
54 [1 1]
55 > (cue 4.657)
56 [1 2]
57 > (cue 39.689)
58 [0 19]
61***
62### `++jam`
64Pack noun to atom
66Produces an atom packed from noun `a`. The inverse of cue.
68Accepts
69-------
71`a` is a noun.
73Produces
74--------
76An atom.
78Source
79------
81 ++ jam :: pack
82 ~/ %jam
83 |= a/*
84 ^- @
85 =+ b=0
86 =+ m=`(map * @)`~
87 =< q
88 |- ^- {p/@ q/@ r/(map * @)}
89 =+ c=(~(get by m) a)
90 ?~ c
91 => .(m (~(put by m) a b))
92 ?: ?=(@ a)
93 =+ d=(mat a)
94 [(add 1 p.d) (lsh 0 1 q.d) m]
95 => .(b (add 2 b))
96 =+ d=$(a -.a)
97 =+ e=$(a +.a, b (add b p.d), m r.d)
98 [(add 2 (add p.d p.e)) (mix 1 (lsh 0 2 (cat 0 q.d q.e))) r.e]
99 ?: ?&(?=(@ a) (lte (met 0 a) (met 0 u.c)))
100 =+ d=(mat a)
101 [(add 1 p.d) (lsh 0 1 q.d) m]
102 =+ d=(mat u.c)
103 [(add 2 p.d) (mix 3 (lsh 0 2 q.d)) m]
104 ::
107Examples
108--------
110 > (jam 1)
111 12
112 > (jam [1 1])
113 817
114 > (jam [1 2])
115 4.657
116 > (jam [~ u=19])
117 39.689
121***
122### `++mat`
124Length-encode
126Produces a cell whose tail `q` is atom `a` with a bit representation of
127its length prepended to it (as the least significant bits). The head `p`
128is the length of `q` in bits.
130Accepts
131-------
133`a` is an atom.
135Produces
136--------
138A cell of two atoms, `p` and `q`.
140Source
141------
143 ++ mat :: length-encode
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 ::
156Examples
157--------
159 > (mat 0xaaa)
160 [p=20 q=699.024]
161 > (met 0 q:(mat 0xaaa))
162 20
163 > `@ub`q:(mat 0xaaa)
164 0b1010.1010.1010.1001.0000
165 > =a =-(~&(- -) `@ub`0xaaa)
166 0b1010.1010.1010
167 > =b =-(~&(- -) `@ub`(xeb a))
168 0b1100
169 > =b =-(~&(- -) `@ub`(met 0 a))
170 0b1100
171 > =c =-(~&(- -) (xeb b))
172 4
173 > [`@ub`a `@ub`(end 0 (dec c) b) `@ub`(bex c)]
174 [0b1010.1010.1010 0b100 0b1.0000]
178***
179### `++rub`
181Length-decode
183The inverse of `++mat`. Accepts a cell of index `a` and a bitstring `b`
184and produces the cell whose tail `q` is the decoded atom at index `a`
185and whose head is the length of the encoded atom `q`, by which the
186offset `a` is advanced. Only used internally as a helper cue.
188Accepts
189-------
191`a` is an atom.
193`b` is a bitstring as an atom.
195Produces
196--------
198A cell of two atoms, `p` and `q`.
200Source
201------
203 ++ rub :: length-decode
204 ~/ %rub
205 |= {a/@ b/@}
206 ^- {p/@ q/@}
207 =+ ^= c
208 =+ [c=0 m=(met 0 b)]
209 |- ?< (gth c m)
210 ?. =(0 (cut 0 [(add a c) 1] b))
211 c
212 $(c +(c))
213 ?: =(0 c)
214 [1 0]
215 =+ d=(add a +(c))
216 =+ e=(add (bex (dec c)) (cut 0 [d (dec c)] b))
217 [(add (add c c) e) (cut 0 [(add d (dec c)) e] b)]
220Examples
221--------
223 > `@ub`(jam 0xaaa)
224 0b1.0101.0101.0101.0010.0000
225 > (rub 1 0b1.0101.0101.0101.0010.0000)
226 [p=20 q=2.730]
227 > `@ux`q:(rub 1 0b1.0101.0101.0101.0010.0000)
228 0xaaa
230***