@@ -4,13 +4,21 @@ navhome: /docs/
6# 1b: tree addressing
6# 1b: tree addressing
8+Check out the Nock [explanation](docs/nock/explanation/) for more
9+information on the tree-addressing system.
7### `++cap`
11### `++cap`
11−Tests whether an `a` is in the head or tail of a noun. Produces the
15+Tests whether the tree address `a` is in the head or the tail of a noun.
12−cube `%2` if it is within the head, or the cube `%3` if it is
16+Produces the constant atom `%2` if it is within the head (subtree `+2`), or
13−within the tail.
17+the constant atom `%3` if it is within the tail (subtree `+3`).
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).
@@ -20,7 +28,7 @@ Accepts
23−A cube.
31+A constant atom.
@@ -28,10 +36,10 @@ Source
28 ++ cap :: tree head
36 ++ cap :: tree head
31− ^- ?(%2 %3)
39+ ^- ?($2 $3)
35 ?(%0 %1) !!
43 ?(%0 %1) !!
36 * $(a (div a 2))
44 * $(a (div a 2))
@@ -42,24 +50,69 @@ Examples
47 > (cap (add 10 9))
57 > (cap (add 10 9))
60+ > (cap 1) ::address '1' is in neither the head nor the tail
53### `++mas`
75### `++mas`
55−Axis within head/tail?
77+Address within head/tail
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).
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`
87+ 2 3 <--here are the head (`+2`) and the tail (`+3`)
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)`.
98+ 1(3) ::new/(old) addresses
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`).
62−`a` is an [atom]().
115+`a` is an atom.
@@ -86,25 +139,88 @@ Examples
87 > (mas 3)
140 > (mas 3)
89 > (mas 4)
143 > (mas 4)
91 > (mas 5)
146 > (mas 5)
93− > (mas 6)
148+ > (cap 5) ::`(cap a)` computes whether address `a` is in the head or the tail
95− > (mas 0)
151+ > (mas 7)
170+ ! exit ::address `0` is in neither the head nor the tail
97 > (mas 1)
172 > (mas 1)
98− ! exit
173+ ! exit ::address `1` is in neither the head nor the tail
103### `++peg`
178### `++peg`
105−Axis within axis
180+Address within address
182+Computes the absolute address of `b`, a relative address within the subtree
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.
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.
197+ 2 3 <- here is the subtree `+3`. The subtree address is `a` in `(peg a b)`
202+ 8 9 10 11 12 13 14 15
203+ /\ /\ /\ /\ /\ /\ /\ /\
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
213+ 1(3) ::new/(old) addresses
107−Computes the axis of `b` within axis `a`.
@@ -123,9 +239,10 @@ Source
124 ++ peg :: tree connect
240 ++ peg :: tree connect
126− |= {a/@ b/@}
242+ |= [a=@ b=@] :: creates a gate
127− ^- @
243+ ?< =(0 a) :: branches if there is no equality
244+ ^- @ :: casts to type @
130 $2 (mul a 2)
247 $2 (mul a 2)
131 $3 +((mul a 2))
248 $3 +((mul a 2))
@@ -135,12 +252,42 @@ Source
138− > (peg 4 1)
255+ > (peg 4 1)
140− > (peg 4 2)
261+ > (peg 4 2)
142− > (peg 8 45)
270+ > (peg 8 45)
285+ > (cap (peg 4 2)) ::`(cap a)` computes whether address `a` is in the head or the tail