@@ -4,13 +4,21 @@ navhome: /docs/
44
55
66# 1b: tree addressing
7+
8+Check out the Nock [explanation](docs/nock/explanation/) for more
9+information on the tree-addressing system.
10+
711### `++cap`
812
913Tree head
1014
11−Tests whether an `a` is in the head or tail of a noun. Produces the
12−cube `%2` if it is within the head, or the cube `%3` if it is
13−within the tail.
15+Tests whether the tree address `a` is in the head or the tail of a noun.
16+Produces the constant atom `%2` if it is within the head (subtree `+2`), or
17+the constant atom `%3` if it is within the tail (subtree `+3`).
18+
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).
21+
1422
1523Accepts
1624-------
@@ -20,7 +28,7 @@ Accepts
2028Produces
2129--------
2230
23−A cube.
31+A constant atom.
2432
2533Source
2634------
@@ -28,10 +36,10 @@ Source
2836 ++ cap :: tree head
2937 ~/ %cap
3038 |= a=@
31− ^- ?(%2 %3)
39+ ^- ?($2 $3)
3240 ?- a
33− %2 %2
34− %3 %3
41+ $2 %2
42+ $3 %3
3543 ?(%0 %1) !!
3644 * $(a (div a 2))
3745 ==
@@ -42,24 +50,69 @@ Examples
4250
4351 > (cap 4)
4452 %2
53+
4554 > (cap 6)
4655 %3
56+
4757 > (cap (add 10 9))
4858 %2
4959
60+ > (cap 1) ::address '1' is in neither the head nor the tail
61+ ! exit
62+
63+ > (cap 0x40))
64+ %2
65+ > `@`0x40
66+ 64
67+
68+ > (cap 'a')
69+ %3
70+ > `@`'a'
71+ 97
5072
5173
5274***
5375### `++mas`
5476
55−Axis within head/tail?
56−
57−Computes the axis of `a` within either the head or tail of a noun (depends whether `a` lies within the the head or tail).
77+Address within head/tail
78+
79+Computes 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...)
92+
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`).
58111
59112Accepts
60113-------
61114
62−`a` is an [atom]().
115+`a` is an atom.
63116
64117Produces
65118--------
@@ -86,25 +139,88 @@ Examples
86139
87140 > (mas 3)
88141 1
142+
89143 > (mas 4)
90144 2
145+
91146 > (mas 5)
92147 3
93− > (mas 6)
94− 2
95− > (mas 0)
96− ! exit
148+ > (cap 5) ::`(cap a)` computes whether address `a` is in the head or the tail
149+ %2
150+
151+ > (mas 7)
152+ 3
153+ > (cap 7)
154+ %3
155+
156+ > (mas 11)
157+ 7
158+
159+ > (mas (mas 11))
160+ 3
161+
162+ > (mas 'p')
163+ 47
164+ > `@`'p'
165+ 111
166+
167+ > (cap (mas 5))
168+
169+ > (mas 0)
170+ ! exit ::address `0` is in neither the head nor the tail
171+
97172 > (mas 1)
98− ! exit
173+ ! exit ::address `1` is in neither the head nor the tail
99174
100175
101176
102177***
103178### `++peg`
104179
105−Axis within axis
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...)
205+
206+
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`.
212+
213+ 1(3) ::new/(old) addresses
214+ / \
215+ 2 3
216+ (6) (7)
217+ / \ /\
218+ / \ / \
219+ 4 5 6 7
220+ (12) (13) (14) (15)
221+ / \ / \ / \ / \
222+ (continues...)
106223
107−Computes the axis of `b` within axis `a`.
108224
109225Accepts
110226-------
@@ -123,9 +239,10 @@ Source
123239
124240 ++ peg :: tree connect
125241 ~/ %peg
126− |= {a/@ b/@}
127− ^- @
128− ?- b
242+ |= [a=@ b=@] :: creates a gate
243+ ?< =(0 a) :: branches if there is no equality
244+ ^- @ :: casts to type @
245+ ?- b
129246 $1 a
130247 $2 (mul a 2)
131248 $3 +((mul a 2))
@@ -135,12 +252,42 @@ Source
135252Examples
136253--------
137254
138− > (peg 4 1)
255+ > (peg 4 1)
256+ 4
257+
258+ > (peg 1 4)
139259 4
140− > (peg 4 2)
260+
261+ > (peg 4 2)
141262 8
142− > (peg 8 45)
263+
264+ > (peg 4 8)
265+ 32
266+
267+ > (peg 4 (4 2))
268+ 32
269+
270+ > (peg 8 45)
271+ 269
272+
273+ > (peg 5 'a')
274+ 353
275+ > `@`'a'
276+ 97
277+
278+ > (peg 0x8 0x2d)
143279 269
280+ > `@`0x8
281+ 8
282+ > `@`0x2d
283+ 45
284+
285+ > (cap (peg 4 2)) ::`(cap a)` computes whether address `a` is in the head or the tail
286+ %2
287+
288+ > (peg 0 4)
289+ ! exit
290+
144291
145292
146293