@@ -9,137 +9,205 @@ navhome: /docs/
99
1010Blocksize
1111
12−Atom representing a blocksize, by convention expressed as a power of 2.
12+Atom representing block size. A block of size `a` has a bitwidth of `2^a`.
1313
14−Source
15−------
14+#### Source
1615
17− ++ bloq @ :: blockclass
16+ ++ bloq @
1817
19−Examples
20−--------
18+#### Examples
2119
22− > :: ++met measures how many bloqs long an atom is
23− > (met 3 256)
20+ :: ++met measures how many a-bloqs long an atom is.
21+
22+ > (met 3 256)
23+ 2
24+
25+ > (met 3 255)
26+ 1
27+
28+ > (met 3 65.535)
29+ 2
30+
31+ > (met 2 65.536)
32+ > 3
33+
34+ > (met 0 4)
35+ 3
36+
37+ > (met 1 4)
2438 2
25− > :: 256 is 2 bloqs of 2^3
2639
40+ > (met 5 9.999.999.999)
41+ 2
42+
43+ > (met 2 0xb5)
44+ 2
45+
46+#### Discussion
47+
48+You can think of `bloq` as a numeral system that can represent values of
49+`a^2^2`, where `a` is the block size. That's because a block of size
50+`a` contains `a^2` bits, and a binary number that is `b` bits wide can represent
51+`b^2` values.
52+
53+A `bloq` of 0 has a bitwidth of 1. (2^0 bits; can represent 2 values.)
54+
55+A `bloq` of 1 has a bitwidth of 2. (2^1 bits; can represent 4 values.)
56+
57+A `bloq` of 2 has a bitwidth of 4. (2^2 bits; can represent 16 values.)
58+
59+A `bloq` of 3 has a bitwidth of 8. (2^3 bits; can represent 256 values.)
60+
61+And so on.
62+
63+See the [bit arithmetic](../2c) section for operations that use `bloq`s.
2764
2865***
2966
3067### `++each`
3168
32−Mold of fork between two
69+Mold of fork between two types
3370
34−mold generator: produces a discriminated fork between two types.
71+A mold generator. Produces a discriminated fork between two types, defaulting to
72+`a`.
3573
36−Source
37−------
74+#### Source
3875
3976 ++ each
40− |* {a/$-(* *) b/$-(* *)} :: either a or b
41− $%({$& p/a} {$| p/b}) :: a default
77+ |*([a=mold b=mold] $%([$| p=b] [$& p=a]))
4278
4379
44−Examples
45−--------
80+#### Examples
4681
4782 > ? *(each cord time)
4883 ?({$.y p/@t} {$.n p/@da})
4984 [%.y p='']
5085
86+ > ? *(each * tape)
87+ ?({$.y p/*} {$.n p/""})
88+ [%.y p=0]
89+
5190***
5291### `++gate`
5392
5493Function
5594
56−A core with one arm, `$`--the empty name--which transforms a sample noun into a product
57−noun. If used dryly as a type, the subject must have a sample type of `*`.
95+A core with one arm, `$`--the empty name--which transforms a sample noun into a
96+product noun. If used dryly as a type, the subject must have a sample type of
97+`*`.
5898
5999
60−Source
61−------
100+#### Source
62101
63− ++ gate $-(* *) :: general gate
102+ ++ gate
103+ $-(* *)
64104
65105
66−Examples
67−--------
68−
69−See also: `++lift`, `++cork`
106+#### Examples
70107
71108 > ? gate
72− <1.ybc {* <110.jyx 1.ztu $151>}>
73− <1.ybc {* <110.jyx 1.ztu $151>}>
109+ <1.rdl {* <31.ohr 1.jmk $143>}>
110+ <1.rdl {* <31.ohr 1.jmk $143>}>
111+
112+ > (`gate`|=(a=* [a 'b']) 1)
113+ [1 98]
114+
115+ > (`gate`|=(a=@ [a 'b']) 1)
116+ ! nest-fail
117+ ! exit
74118
75− > (`gate`|=(a/* [a 'b']) 1)
76− [1 'b']
119+#### Discussion
77120
121+A `gate` is analogous to a function in other programming languages. We created
122+this new jargon because other constructs in Urbit are "functions" in the
123+mathematical sense. Any `gate` normalizes to an iron `gate`.
78124
125+See also: [`++lift`](../2a), [`++cork`](../2n)
79126
80127***
81128### `++list`
82129
83130List
84131
85−mold generator. `++list` generates a mold of a null-termanated list of a
132+A mold generator. Generates a mold of a null-terminated list of a
86133homogenous type.
87134
88135
89−Source
90−------
136+#### Source
91137
92− ++ list |* a/$-(* *) :: null-term list
93− $@($~ {i/a t/(list a)}) ::
138+ ++ list
139+ |*(a=mold $@($~ (lest a)))
94140
95141
96−Examples
97−--------
98−
99−See also: `++turn`, `++snag`
142+#### Examples
100143
101144 > *(list)
102145 ~
146+
103147 > `(list @)`"abc"
104148 ~[97 98 99]
149+
105150 > (snag 0 "abc")
106151 'a'
107152
153+ > `(list @)`[1 2 'j' ~]
154+ ~[1 2 106]
108155
156+#### Discussion
157+
158+See also: [`++turn`](../2b), [`++snag`](../2b)
109159
110160***
111161### `++lone`
112162
113−`++lone` puts face of `p` on something.
163+Face on mold
164+
165+A mold generator. Puts face of `p` on the passed-in mold.
166+
167+#### Source
168+
169+ ++ lone
170+ |*(a=mold [p=a])
114171
115−XX unused
172+#### Examples
116173
117−Source
118−------
119174
120− ++ lone |*(a/$-(* *) p/a) :: just one thing
175+ > ? *cord
176+ @t
177+ ''
178+ > ? *(lone cord)
179+ p/@t
180+ p=''
181+
182+ > ? *(lone @)
183+ p/@
184+ p=0
185+ > ? *@
186+ @
187+ 0
121188
122189***
123190### `++pair`
124191
125192Mold of pair of types
126193
127−mold generator. Produces a tuple of two of the types passed in.
194+A mold generator. Produces a tuple of two of the types passed in.
128195
129196
130−Source
131−------
197+#### Source
132198
133− ++ pair |*({a/$-(* *) b/$-(* *)} {p/a q/b}) :: just a pair
199+ ++ pair
200+ |*([a=mold b=mold] [p=a q=b])
134201
135202
136203
137−Examples
138−--------
204+#### Examples
139205
140− > *(pair bean cord)
206+ > *(pair ? cord)
141207 [p=%.y q='']
142208
209+ > *(pair tape @)
210+ [p="" q=0]
143211
144212
145213***
@@ -147,105 +215,93 @@ Examples
147215
148216Faceless list
149217
150−A `++list` without the faces `i` and `t`.
218+A mold generator. A `list` without the faces `i` and `t`.
219+
220+#### Source
151221
152−Source
153−------
222+ ++ pole
223+ |*(a=mold $@($~ [a (pole a)]))
154224
155− ++ pole |* a/$-(* *) :: nameless list
156− $@($~ {a (pole a)}) ::
157225
158226
227+#### Examples
159228
160−Examples
161−--------
229+ > =/(a "asdf" ?>(?=(^ a) `(lest @tD)`a))
230+ [i='a' t=[i='s' t=[i='d' t=[i='f' t=~]]]]
162231
163232 > `(pole char)`"asdf"
164− [~~a [~~s [~~d [~~f ~]]]]
233+ ['a' ['s' ['d' ['f' ~]]]]
165234
166235
167236
168237***
169238### `++qual`
170239
171−Mold of 4 type tuple
240+Mold of 4-type tuple
172241
173−A `++qual` is a tuple of four of the types passed in.
242+A mold generator. Produces a tuple of four of the types passed in.
174243
175−Source
176−------
244+#### Source
177245
178− ++ qual |* {a/$-(* *) b/$-(* *) c/$-(* *) d/$-(* *)} :: just a quadruple
179− {p/a q/b r/c s/d} ::
246+ ++ qual
247+ |* [a=mold b=mold c=mold d=mold]
248+ [p=a q=b r=c s=d]
180249
181−Examples
182−--------
250+#### Examples
183251
184252 > *(qual date time tape cord)
185253 [p=[[a=%.y y=0] m=0 t=[d=0 h=0 m=0 s=0 f=~]] q=~292277024401-.1.1 r="" s='']
186254
187−
188−
189−***
190−### `++quid`
191−
192−For use with `=^` `:sip`.
193−
194−Mold generator. Produces a tuple of `a` and the mold of `b`.
195−
196−Source
197−------
198−
199− ++ quid |*({a/mold b/*} {a _b}) :: mixed for sip
200−
201−Examples
202−--------
203−
204− > *(quid @ 'hi')
205− [0 'hi']
206−
255+ > *(qual (list @) @u @ud @ux)
256+ [p=~ q=0 r=0 s=0x0]
207257
208258
209259***
210260### `++quip`
211261
212−For use with `=^` `:sip`.
262+Mold of pair of `list` and type
213263
214−Mold generator. Produces a tuple of a list of `a` and the mold of `b`.
264+A mold generator. Produces a tuple of a `list` of `a` and the mold of `b`.
215265
216−Source
217−------
266+#### Source
218267
219− ++ quip |*({a/mold b/*} {(list a) _b}) :: list-mixed for sip
268+ ++ quip
269+ |*([a=mold b=mold] [(list a) b])
220270
221−Examples
222−--------
271+#### Examples
223272
224− > *(quip @ 'hi')
273+ > *(quip @ _'hi')
225274 [~ 'hi']
226275
276+ > `(quip @ @ux)`[[1 2 3 4 ~] 0x10]
277+ [~[1 2 3 4] 0x10]
278+
279+#### Discussion
227280
281+A common pattern in Hoon code is to return a `list` of changes, along with a
282+new state. You'll often see `quip` used in Gall apps.
228283
229− ***
284+***
230285### `++trap`
231286
232287Core with one arm `$`
233288
234−A trap is a core with one arm `++$`.
289+A trap is a core with one arm `$`.
235290
236−Source
237−------
291+#### Source
238292
239− ++ trap |*(a/_* _|?(*a)) :: makes perfect sense
293+ ++ trap
294+ |*(a=mold _|?(*a))
240295
241296
242−Examples
243−--------
297+#### Examples
244298
245− > *trap
246− <1.mws 101.jzo 1.ypj %164>
247299 > (*trap)
300+ <1?dxy 1.oeg {a/<1|rbb {* <31.ohr 1.jmk $143>}> <31.ohr 1.jmk $143>}>
301+
302+ > *(*trap)
248303 0
304+
249305 > (|.(42))
250306 42
251307
@@ -256,20 +312,18 @@ Examples
256312
257313Tree mold generator
258314
259−A `++tree` can be empty, or contain a node of a type and
260−left/right sub `++tree` of the same type. Pretty-printed with `{}`.
315+A mold generator. A `tree` can be empty, or contain a node of a type and
316+left/right sub `tree` of the same type. Pretty-printed with `{}`.
261317
262−Source
263−------
318+#### Source
264319
265− ++ tree |* a/$-(* *) :: binary tree
266− $@($~ {n/a l/(tree a) r/(tree a)}) ::
320+ ++ tree
321+ |*(a=mold $@($~ [n=a l=(tree a) r=(tree a)]))
267322
268323
269−Examples
270−--------
324+#### Examples
271325
272− > `(tree {@ tape})`[[1 "hi"] [[2 "bye"] ~ ~] ~]
326+ > `(tree [@ tape])`[[1 "hi"] [[2 "bye"] ~ ~] ~]
273327 {[2 "bye"] [1 "hi"]}
274328
275329
@@ -279,21 +333,21 @@ Examples
279333
280334Mold of three types
281335
282−`++mold` of the tuple of the three types passed in.
336+A mold generator. A mold of the tuple of the three types passed in.
283337
284−Source
285−------
338+#### Source
286339
287− ++ trel |* {a/$-(* *) b/$-(* *) c/$-(* *)} :: just a triple
288− {p/a q/b r/c} ::
340+ ++ trel
341+ |*([a=mold b=mold c=mold] [p=a q=b r=c])
289342
290343
291−Examples
292−--------
344+#### Examples
293345
294346 > *(trel @ud @t @s)
295347 [p=0 q='' r=--0]
296348
349+ > *(trel cord bloq tape)
350+ [p='' q=0 r=""]
297351
298352
299353***
@@ -301,32 +355,33 @@ Examples
301355
302356Maybe
303357
304−mold generator. A `++unit` is either `~` or `[~ u=a]` where `a` is the
358+A mold generator. A `unit` is either `~` or `[~ u=a]`, where `a` is the
305359type that was passed in.
306360
307361
308−Source
309−------
310−
311− ++ unit |* a/$-(* *) :: maybe
312− $@($~ {$~ u/a}) ::
362+#### Source
313363
364+ ++ unit
365+ |*(a=mold $@($~ [$~ u=a]))
314366
315−Examples
316−--------
367+#### Examples
317368
318−See also: `++bind`
319369
320370 > ? *(unit time)
321− ?({$~ u/@da} $~)
322− ~
371+ ?({$~ u/@da} $~)
372+ ~
323373
324− > > =a |= a/@
325− ^- (unit @)
326− ?~ a ~
327− [~ a]
374+ > =a |= a=@
375+ ^- (unit @)
376+ ?~ a ~
377+ [~ a]
328378 > (a 2)
329379 [~ u=2]
330380
381+#### Discussion
382+
383+Using a `unit` allows you to specify something that may not be there.
384+
385+See also: [`++bind`](../2b)
331386
332387***