@@ -16,24 +16,18 @@ Tests whether the tree address `a` is in the head or the tail of a noun.
1616Produces the constant atom `%2` if it is within the head (subtree `+2`), or
1717the constant atom `%3` if it is within the tail (subtree `+3`).
1818
19−In the Urbit binary-tree system, a parent at address `n` will always have its
20−children at address `2n` (the head) and address `2n+1` (the tail).
2119
22−
23−Accepts
24−-------
20+#### Accepts
2521
2622`a` is an atom.
2723
28−Produces
29−--------
24+#### Produces
3025
3126A constant atom.
3227
33−Source
34−------
28+#### Source
3529
36− ++ cap :: tree head
30+ ++ cap
3731 ~/ %cap
3832 |= a=@
3933 ^- ?($2 $3)
@@ -43,10 +37,9 @@ Source
4337 ?(%0 %1) !!
4438 * $(a (div a 2))
4539 ==
46− ::
4740
48−Examples
49−--------
41+
42+#### Examples
5043
5144 > (cap 4)
5245 %2
@@ -77,52 +70,19 @@ Examples
7770Address within head/tail
7871
7972Computes the tree address of atom `a` within either the head (`+2`) or tail
80−(`+3`) of a noun. In other words, `++mas` returns the relative address of `a`
81−with respect to the head or the tail subtrees, depending on which one `a`
82−descends from.
83−
84− 1
85− / \
86− / \
87− 2 3 <--here are the head (`+2`) and the tail (`+3`)
88− / \ /\
89− 4 5 6 7
90− /\ /\ /\ /\
91− (continues...)
73+(`+3`) of a noun.
9274
93−Running `(mas 7)` in the Dojo will return `3`, because address `+3` is what
94−`+7` now occupies. The tree below helps illustrate the relationship. With
95−parentheses are `a` values (if `a` is in subtree `+3`), and without parentheses
96−are the values returned with `(mas a)`.
97−
98− 1(3) ::new/(old) addresses
99− / \
100− 2 3
101− (6) (7)
102− / \ /\
103− / \ / \
104− 4 5 6 7
105− (12) (13) (14) (15)
106− / \ / \ / \ / \
107− (continues...)
108−
109−Notice how the old values in the head (subtree `+2`) were not illustrated in
110−this case, because `+7` is within the tail (subtree `+3`).
111−
112−Accepts
113−-------
75+#### Accepts
11476
11577`a` is an atom.
11678
117−Produces
118−--------
79+#### Produces
11980
12081An atom.
12182
122−Source
123−------
83+#### Source
12484
125− ++ mas :: tree body
85+ ++ mas
12686 ~/ %mas
12787 |= a=@
12888 ^- @
@@ -132,10 +92,9 @@ Source
13292 3 1
13393 * (add (mod a 2) (mul $(a (div a 2)) 2))
13494 ==
135− ::
13695
137−Examples
138−--------
96+
97+#### Examples
13998
14099 > (mas 3)
141100 1
@@ -159,12 +118,8 @@ Examples
159118 > (mas (mas 11))
160119 3
161120
162− > (mas 'p')
163− 47
164− > `@`'p'
165− 111
166−
167− > (cap (mas 5))
121+ > (cap (mas 6))
122+ %3
168123
169124 > (mas 0)
170125 ! exit ::address `0` is in neither the head nor the tail
@@ -173,75 +128,62 @@ Examples
173128 ! exit ::address `1` is in neither the head nor the tail
174129
175130
131+#### Discussion
176132
177−***
178−### `++peg`
179−
180−Address within address
181−
182−Computes the absolute address of `b`, a relative address within the subtree
183−`a`.
184−
185−In other words, the subtree at address `a` is treated as a tree in its own
186−right (starting with root `+1`, head `+2`, and tail `+3`). Relative address
187−`b` is found with respect to `a`, and then its absolute address, within the
188−greater tree, is returned.
189−
190−Running `(peg 3 4)` in the Dojo, for example, will return `12`. Looking at
191−a tree diagram makes it easy to see why.
192−
193− 1
194− / \
195− / \
196− / \
197− 2 3 <- here is the subtree `+3`. The subtree address is `a` in `(peg a b)`
198− / \ / \
199− / \ / \
200− 4 5 6 7
201− / \ / \ / \ / \
202− 8 9 10 11 12 13 14 15
203− /\ /\ /\ /\ /\ /\ /\ /\
204− (continues...)
205133
134+ 1
135+ / \
136+ / \
137+ 2 3 <--here are the head (`+2`) and the tail (`+3`)
138+ / \ /\
139+ 4 5 6 7
140+ /\ /\ /\ /\
141+ (continues...)
206142
207−When we consider subtree at address `+3` by itself, it has relative addresses
208−that are structured in the same way as its parent tree's absolute addresses.
209−The absolute addresses are given in parentheses in the diagram below.
210−Notice how relative address `+4` is at the same position as absolute address
211−`+12`.
143+Running `(mas 7)` in the Dojo will return `3`, because address `+3` is what
144+`+7` now occupies. The tree below helps illustrate the relationship. With
145+parentheses are `a` values (if `a` is in subtree `+3`), and without parentheses
146+are the values returned with `(mas a)`.
212147
213− 1(3) ::new/(old) addresses
148+ 1(3) ::new/(old) addresses
214149 / \
215150 2 3
216151 (6) (7)
217152 / \ /\
218153 / \ / \
219154 4 5 6 7
220− (12) (13) (14) (15)
155+ (12) (13) (14) (15)
221156 / \ / \ / \ / \
222157 (continues...)
223158
159+Notice how the old values in the head (subtree `+2`) were not illustrated in
160+this case, because `+7` is within the tail (subtree `+3`).
161+
162+***
163+### `++peg`
164+
165+Address within address
224166
225−Accepts
226−-------
167+Computes the absolute address of `b`, a relative address within the subtree
168+`a`.
169+
170+#### Accepts
227171
228172`a` is an atom.
229173
230174`b` is an atom.
231175
232−Produces
233−--------
176+#### Produces
234177
235178An atom.
236179
237−Source
238−------
180+#### Source
239181
240− ++ peg :: tree connect
182+ ++ peg
241183 ~/ %peg
242− |= [a=@ b=@] :: creates a gate
243− ?< =(0 a) :: branches if there is no equality
244− ^- @ :: casts to type @
184+ |= [a=@ b=@]
185+ ?< =(0 a)
186+ ^- @
245187 ?- b
246188 $1 a
247189 $2 (mul a 2)
@@ -249,8 +191,7 @@ Source
249191 * (add (mod b 2) (mul $(b (div b 2)) 2))
250192 ==
251193
252−Examples
253−--------
194+#### Examples
254195
255196 > (peg 4 1)
256197 4
@@ -270,24 +211,50 @@ Examples
270211 > (peg 8 45)
271212 269
272213
273− > (peg 5 'a')
274− 353
275− > `@`'a'
276− 97
277−
278− > (peg 0x8 0x2d)
279− 269
280− > `@`0x8
281− 8
282− > `@`0x2d
283− 45
284−
285214 > (cap (peg 4 2)) ::`(cap a)` computes whether address `a` is in the head or the tail
286215 %2
287216
288− > (peg 0 4)
289− ! exit
290217
218+#### Discussion
219+
220+In other words, the subtree at address `a` is treated as a tree in its own
221+right (starting with root `+1`, head `+2`, and tail `+3`). Relative address
222+`b` is found with respect to `a`, and then its absolute address, within the
223+greater tree, is returned.
224+
225+Running `(peg 3 4)` in the Dojo, for example, will return `12`. Looking at
226+a tree diagram makes it easy to see why.
227+
228+ 1
229+ / \
230+ / \
231+ / \
232+ 2 3 <- here is the subtree `+3`. The subtree address is `a` in `(peg a b)`
233+ / \ / \
234+ / \ / \
235+ 4 5 6 7
236+ / \ / \ / \ / \
237+ 8 9 10 11 12 13 14 15
238+ /\ /\ /\ /\ /\ /\ /\ /\
239+ (continues...)
240+
241+
242+When we consider subtree at address `+3` by itself, it has relative addresses
243+that are structured in the same way as its parent tree's absolute addresses.
244+The absolute addresses are given in parentheses in the diagram below.
245+Notice how relative address `+4` is at the same position as absolute address
246+`+12`.
247+
248+ 1(3) ::new/(old) addresses
249+ / \
250+ 2 3
251+ (6) (7)
252+ / \ /\
253+ / \ / \
254+ 4 5 6 7
255+ (12) (13) (14) (15)
256+ / \ / \ / \ / \
257+ (continues...)
291258
292259
293260