git.iko.soy/urbit.org
on 4fdc19d help sign in
urbit.org/content/docs/hoon/reference/stdlib/1c.md
538 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`this`.
115#### Source
117```hoon
118++ each
119 |$ [this that]
120 $% [%| p=that]
121 [%& p=this]
122 ==
123```
125#### Examples
127```
128> ? *(each cord time)
129 ?([%.y p=@t] [%.n p=@da])
130[%.y p='']
131```
133```
134> ? *(each * tape)
135 ?([%.y p=*] [%.n p=""])
136[%.y p=0]
137```
139---
141## `++gate`
143Function
145A [`core`](/docs/glossary/core) with one arm, `$`--the empty name--which transforms a sample noun into a
146product noun. If used dryly as a type, the subject must have a sample type of
147`*`.
149#### Source
151```hoon
152 ++ gate
153 $-(* *)
154```
156#### Examples
158```
159> ? gate
160 <1.ddq [* <46.hgz 1.pnw %140>]>
161<1.ddq [* <46.hgz 1.pnw %140>]>
162```
164```
165> (`gate`|=(a=* [a 'b']) 1)
166[1 98]
167```
169```
170> (`gate`|=(a=@ [a 'b']) 1)
171mint-nice
172-need.@
173-have.*
174nest-fail
175dojo: hoon expression failed
176```
178#### Discussion
180A `gate` is analogous to a function in other programming languages. We created
181this new jargon because other constructs in Urbit are "functions" in the
182mathematical sense. Any `gate` normalizes to an iron `gate`.
184See also: [`++lift`](/docs/hoon/reference/stdlib/2a#lift), [`++cork`](/docs/hoon/reference/stdlib/2n#cork)
186---
188## `++list`
190List
192A mold generator. Generates a mold of a null-terminated list of a
193homogenous type.
195#### Source
197```hoon
198++ list
199 |$ [item]
200 $@(~ [i=item t=(list item)])
201```
203#### Examples
205```
206> *(list)
208```
210```
211> `(list @)`"abc"
212~[97 98 99]
213```
215```
216> (snag 0 "abc")
217'a'
218```
220```
221> `(list @)`[1 2 'j' ~]
222~[1 2 106]
223```
225#### Discussion
227See also: [`++turn`](/docs/hoon/reference/stdlib/2b#turn), [`++snag`](/docs/hoon/reference/stdlib/2b#snag)
229---
231## `++lone`
233Face on mold
235A mold generator. Puts face of `p` on the passed-in mold.
237#### Source
239```hoon
240++ lone
241 |$ [item]
242 p=item
243```
245#### Examples
247```
248> ? *cord
249@t
250''
251```
253```
254> ? *(lone cord)
255 p=@t
256p=''
257```
259```
260> ? *(lone @)
261 p=@
262p=0
263```
265```
266> ? *@
267 @
269```
271---
273## `++pair`
275Mold of pair of types
277A mold generator. Produces a tuple of two of the types passed in.
279#### Source
281```hoon
282++ pair
283 |$ [head tail]
284 [p=head q=tail]
285```
287#### Examples
289```
290> *(pair ? cord)
291[p=%.y q='']
292```
294```
295> *(pair tape @)
296[p="" q=0]
297```
299---
301## `++pole`
303Faceless [`list`](/docs/hoon/reference/stdlib/1c#list)
305A mold generator. A [`list`](/docs/hoon/reference/stdlib/1c#list) without the faces `i` and `t`.
307#### Source
309```hoon
310++ pole
311 |$ [item]
312 $@(~ [item (pole item)])
313```
315#### Examples
317```
318> =/(a "asdf" ?>(?=(^ a) `(lest @tD)`a))
319[i='a' t=[i='s' t=[i='d' t=[i='f' t=~]]]]
320```
322```
323> `(pole char)`"asdf"
324['a' ['s' ['d' ['f' ~]]]]
325```
327---
329## `++qual`
331Mold of 4-type tuple
333A mold generator. Produces a tuple of four of the types passed in.
335#### Source
337```hoon
338++ qual
339 |$ [first second third fourth]
340 [p=first q=second r=third s=fourth]
341```
343#### Examples
345```
346> *(qual date time tape cord)
347[p=[[a=%.y y=0] m=0 t=[d=0 h=0 m=0 s=0 f=~]] q=~2000.1.1 r="" s='']
348```
350```
351> *(qual (list @) @u @ud @ux)
352[p=~ q=0 r=0 s=0x0]
353```
355---
357## `++quip`
359Mold of pair of [`list`](/docs/hoon/reference/stdlib/1c#list) and type
361A mold generator. Produces a tuple of a [`list`](/docs/hoon/reference/stdlib/1c#list) of `item` and the mold of `state`.
363#### Source
365```hoon
366++ quip
367 |$ [item state]
368 [(list item) state]
369```
371#### Examples
373```
374> *(quip @ _'hi')
375[~ 'hi']
376```
378```
379> `(quip @ @ux)`[[1 2 3 4 ~] 0x10]
380[~[1 2 3 4] 0x10]
381```
383#### Discussion
385A common pattern in Hoon code is to return a `list` of changes, along with a
386new state. You'll often see `quip` used in Gall apps.
388---
390## `++step`
392Atom size or offset, in [bloq](#bloq)s.
394#### Source
396```
397++ step
398 _`@u`1
399```
401#### Examples
403```
404> `step`0
406```
408```
409> `step`2
411```
413---
415## `++trap`
417[`Core`](/docs/glossary/core) with one arm `$`
419A trap is a [`core`](/docs/glossary/core) with one arm `$`.
421#### Source
423```hoon
424++ trap
425 |$ [product]
426 _|?($:product)
427```
429#### Examples
431```
432> (*trap)
433<1?ruo 1.mhl [product=<1|xpg [* * *]> <46.hgz 1.pnw %140>]>
434```
436```
437> *(*trap)
439```
441```
442> (|.(42))
44342
444```
446---
448## `++tree`
450Tree mold generator
452A mold generator. A `tree` can be empty, or contain a node of a type and
453left/right sub `tree` of the same type. Pretty-printed with `{}`.
455#### Source
457```hoon
458++ tree
459 |$ [node]
460 $@(~ [n=node l=(tree node) r=(tree node)])
461```
463#### Examples
465```
466> `(tree [@ tape])`[[1 "hi"] [[2 "bye"] ~ ~] ~]
467{[2 "bye"] [1 "hi"]}
468```
470---
472## `++trel`
474Mold of three types
476A mold generator. A mold of the tuple of the three types passed in.
478#### Source
480```hoon
481++ trel
482 |$ [first second third]
483 [p=first q=second r=third]
484```
486#### Examples
488```
489> *(trel @ud @t @s)
490[p=0 q='' r=--0]
491```
493```
494> *(trel cord bloq tape)
495[p='' q=0 r=""]
496```
498---
500## `++unit`
502Maybe
504A mold generator. A `unit` is either `~` or `[~ u=item]`, where `item` is the
505type that was passed in.
507#### Source
509```hoon
510++ unit
511 |$ [item]
512 $@(~ [~ u=item])
513```
515#### Examples
517```
518> ? *(unit time)
519 u(@da)
521```
523```
524> =a |= a=@
525 ^- (unit @)
526 ?~ a ~
527 [~ a]
528> (a 2)
529[~ 2]
530```
532#### Discussion
534Using a `unit` allows you to specify something that may not be there.
536See also: [`++bind`](/docs/hoon/reference/stdlib/2a#bind)
538---