git.iko.soy/urbit.org
on b00decd help sign in
urbit.org/content/docs/hoon/reference/stdlib/1c.md
459 lines 7.0 kB history raw
1+++
2title = "1c: Molds and Mold-Builders"
3weight = 3
4template = "doc.html"
5+++
7### `$bite`
9Atom slice specifier.
11Either a single atom representing block size, or a cell containing a block size
12and an atom representing the number of blocks, called `step`. If `step` is not
13supplied, it defaults to a value of 1.
15#### Source
17```hoon
18 +$ bite $@(bloq [=bloq =step])
19```
21#### Examples
23```
24 :: ++end gets the least significant bits of an atom.
26 > (end [1 1] 255)
27 3
29 > (end 1 255)
30 3
32 > (end 3 255)
33 255
35 > (end 3 65.535)
36 255
38 > (end [3 2] 65.535)
39 65.535
41 > (end [3 0] 65.535)
42 0
43```
45### `$bloq`
47Blocksize
49[`Atom`](/docs/glossary/atom) representing block size. A block of size `a` has a bitwidth of `2^a`.
51#### Source
53```hoon
54 ++ bloq @
55```
57#### Examples
59```
60 :: ++met measures how many a-bloqs long an atom is.
62 > (met 3 256)
63 2
65 > (met 3 255)
66 1
68 > (met 3 65.535)
69 2
71 > (met 2 65.536)
72 > 3
74 > (met 0 4)
75 3
77 > (met 1 4)
78 2
80 > (met 5 9.999.999.999)
81 2
83 > (met 2 0xb5)
84 2
85```
87#### Discussion
89You can think of `bloq` as a numeral system that can represent values of
90`a^2^2`, where `a` is the block size. That's because a block of size
91`a` contains `a^2` bits, and a binary number that is `b` bits wide can represent
92`b^2` values.
94A `bloq` of 0 has a bitwidth of 1. (2^0 bits; can represent 2 values.)
96A `bloq` of 1 has a bitwidth of 2. (2^1 bits; can represent 4 values.)
98A `bloq` of 2 has a bitwidth of 4. (2^2 bits; can represent 16 values.)
100A `bloq` of 3 has a bitwidth of 8. (2^3 bits; can represent 256 values.)
102And so on.
104See the [bit arithmetic](/docs/hoon/reference/stdlib/2c) section for operations that use `bloq`s.
106---
108### `++each`
110Mold of fork between two types
112A mold generator. Produces a discriminated fork between two types, defaulting to
113`a`.
115#### Source
117 ++ each
118 |*([a=mold b=mold] $%([$| p=b] [$& p=a]))
121#### Examples
123```
124 > ? *(each cord time)
125 ?({$.y p/@t} {$.n p/@da})
126 [%.y p='']
128 > ? *(each * tape)
129 ?({$.y p/*} {$.n p/""})
130 [%.y p=0]
131```
133---
134### `++gate`
136Function
138A [`core`](/docs/glossary/core) with one arm, `$`--the empty name--which transforms a sample noun into a
139product noun. If used dryly as a type, the subject must have a sample type of
140`*`.
143#### Source
145```hoon
146 ++ gate
147 $-(* *)
148```
150#### Examples
152```
153 > ? gate
154 <1.rdl {* <31.ohr 1.jmk $143>}>
155 <1.rdl {* <31.ohr 1.jmk $143>}>
157 > (`gate`|=(a=* [a 'b']) 1)
158 [1 98]
160 > (`gate`|=(a=@ [a 'b']) 1)
161 ! nest-fail
162 ! exit
163```
165#### Discussion
167A `gate` is analogous to a function in other programming languages. We created
168this new jargon because other constructs in Urbit are "functions" in the
169mathematical sense. Any `gate` normalizes to an iron `gate`.
171See also: [`++lift`](/docs/hoon/reference/stdlib/2a#lift), [`++cork`](/docs/hoon/reference/stdlib/2n#cork)
173---
174### `++list`
176List
178A mold generator. Generates a mold of a null-terminated list of a
179homogenous type.
182#### Source
184```hoon
185 ++ list
186 |*(a=mold $@($~ (lest a)))
187```
189#### Examples
191```
192 > *(list)
193 ~
195 > `(list @)`"abc"
196 ~[97 98 99]
198 > (snag 0 "abc")
199 'a'
201 > `(list @)`[1 2 'j' ~]
202 ~[1 2 106]
204```
205#### Discussion
207See also: [`++turn`](/docs/hoon/reference/stdlib/2b#turn), [`++snag`](/docs/hoon/reference/stdlib/2b#snag)
209---
210### `++lone`
212Face on mold
214A mold generator. Puts face of `p` on the passed-in mold.
216#### Source
218```hoon
219 ++ lone
220 |*(a=mold [p=a])
221```
223#### Examples
225```
226 > ? *cord
227 @t
228 ''
229 > ? *(lone cord)
230 p/@t
231 p=''
233 > ? *(lone @)
234 p/@
235 p=0
236 > ? *@
237 @
238 0
239```
241---
242### `++pair`
244Mold of pair of types
246A mold generator. Produces a tuple of two of the types passed in.
249#### Source
251```hoon
252 ++ pair
253 |*([a=mold b=mold] [p=a q=b])
254```
256#### Examples
258```
259 > *(pair ? cord)
260 [p=%.y q='']
262 > *(pair tape @)
263 [p="" q=0]
265```
267---
268### `++pole`
270Faceless [`list`](/docs/hoon/reference/stdlib/1c#list)
272A mold generator. A [`list`](/docs/hoon/reference/stdlib/1c#list) without the faces `i` and `t`.
274#### Source
276```hoon
277 ++ pole
278 |*(a=mold $@($~ [a (pole a)]))
279```
282#### Examples
284```
285 > =/(a "asdf" ?>(?=(^ a) `(lest @tD)`a))
286 [i='a' t=[i='s' t=[i='d' t=[i='f' t=~]]]]
288 > `(pole char)`"asdf"
289 ['a' ['s' ['d' ['f' ~]]]]
290```
293---
294### `++qual`
296Mold of 4-type tuple
298A mold generator. Produces a tuple of four of the types passed in.
300#### Source
302```hoon
303 ++ qual
304 |* [a=mold b=mold c=mold d=mold]
305 [p=a q=b r=c s=d]
306```
308#### Examples
310```
311 > *(qual date time tape cord)
312 [p=[[a=%.y y=0] m=0 t=[d=0 h=0 m=0 s=0 f=~]] q=~292277024401-.1.1 r="" s='']
314 > *(qual (list @) @u @ud @ux)
315 [p=~ q=0 r=0 s=0x0]
316```
318---
319### `++quip`
321Mold of pair of [`list`](/docs/hoon/reference/stdlib/1c#list) and type
323A mold generator. Produces a tuple of a [`list`](/docs/hoon/reference/stdlib/1c#list) of `a` and the mold of `b`.
325#### Source
327```hoon
328 ++ quip
329 |*([a=mold b=mold] [(list a) b])
330```
332#### Examples
334```
335 > *(quip @ _'hi')
336 [~ 'hi']
338 > `(quip @ @ux)`[[1 2 3 4 ~] 0x10]
339 [~[1 2 3 4] 0x10]
340```
342#### Discussion
344A common pattern in Hoon code is to return a `list` of changes, along with a
345new state. You'll often see `quip` used in Gall apps.
347---
348### `++trap`
350[`Core`](/docs/glossary/core) with one arm `$`
352A trap is a [`core`](/docs/glossary/core) with one arm `$`.
354#### Source
356```hoon
357 ++ trap
358 |*(a=mold _|?(*a))
359```
361#### Examples
363```
364 > (*trap)
365 <1?dxy 1.oeg {a/<1|rbb {* <31.ohr 1.jmk $143>}> <31.ohr 1.jmk $143>}>
367 > *(*trap)
368 0
370 > (|.(42))
371 42
372```
375---
376### `++tree`
378Tree mold generator
380A mold generator. A `tree` can be empty, or contain a node of a type and
381left/right sub `tree` of the same type. Pretty-printed with `{}`.
383#### Source
385```hoon
386 ++ tree
387 |*(a=mold $@($~ [n=a l=(tree a) r=(tree a)]))
388```
390#### Examples
392```
393 > `(tree [@ tape])`[[1 "hi"] [[2 "bye"] ~ ~] ~]
394 {[2 "bye"] [1 "hi"]}
395```
398---
399### `++trel`
401Mold of three types
403A mold generator. A mold of the tuple of the three types passed in.
405#### Source
407```hoon
408 ++ trel
409 |*([a=mold b=mold c=mold] [p=a q=b r=c])
410```
412#### Examples
414```
415 > *(trel @ud @t @s)
416 [p=0 q='' r=--0]
418 > *(trel cord bloq tape)
419 [p='' q=0 r=""]
420```
422---
423### `++unit`
425Maybe
427A mold generator. A `unit` is either `~` or `[~ u=a]`, where `a` is the
428type that was passed in.
431#### Source
433```hoon
434 ++ unit
435 |*(a=mold $@($~ [$~ u=a]))
436```
438#### Examples
440```
441 > ? *(unit time)
442 ?({$~ u/@da} $~)
443 ~
445 > =a |= a=@
446 ^- (unit @)
447 ?~ a ~
448 [~ a]
449 > (a 2)
450 [~ u=2]
451```
453#### Discussion
455Using a `unit` allows you to specify something that may not be there.
457See also: [`++bind`](/docs/hoon/reference/stdlib/2a#bind)
459---