git.iko.soy/urbit.org
on 883cb21 help sign in
urbit.org/content/docs/hoon/reference/stdlib/2a.md
616 lines 10 kB history raw
1+++
2title = "2a: Unit Logic"
3weight = 4
4template = "doc.html"
5+++
7## `++biff`
9[`Unit`](/docs/hoon/reference/stdlib/1c#unit) as argument
11Applies a function `b` that produces a [`unit`](/docs/hoon/reference/stdlib/1c#unit) to the unwrapped value of [`unit`](/docs/hoon/reference/stdlib/1c#unit)
12`a` (`u.a`). If `a` is empty, `~` is produced.
14#### Accepts
16`a` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
18`b` is a function that accepts a [`noun`](/docs/glossary/noun) and produces a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
20#### Produces
22A [`unit`](/docs/hoon/reference/stdlib/1c#unit).
24#### Source
26```hoon
27++ biff
28 |* [a=(unit) b=$-(* (unit))]
29 ?~ a ~
30 (b u.a)
31```
33#### Examples
35```
36> (biff (some 5) |=(a=@ (some (add a 2))))
37[~ u=7]
38```
40```
41> (biff ~ |=(a=@ (some (add a 2))))
43```
45---
47## `++bind`
49Non-unit function to [`unit`](/docs/hoon/reference/stdlib/1c#unit), producing [`unit`](/docs/hoon/reference/stdlib/1c#unit)
51Applies a function `b` to the value (`u.a`) of a [`unit`](/docs/hoon/reference/stdlib/1c#unit) `a`, producing
52a [`unit`](/docs/hoon/reference/stdlib/1c#unit). Used when you want a function that does not accept or produce a
53[`unit`](/docs/hoon/reference/stdlib/1c#unit) to both accept and produce a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
55#### Accepts
57`a` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
59`b` is a function.
61#### Produces
63A [`unit`](/docs/hoon/reference/stdlib/1c#unit).
65#### Source
67```hoon
68++ bind
69 |* [a=(unit) b=gate]
70 ?~ a ~
71 [~ u=(b u.a)]
72```
74#### Examples
76```
77> (bind ((unit @) [~ 97]) ,@t)
78[~ u='a']
79```
81```
82> =a |=(a=@ (add a 1))
83> (bind ((unit @) [~ 2]) a)
84[~ u=3]
85```
87---
89## `++bond`
91Replace null
93Replaces an empty [`unit`](/docs/hoon/reference/stdlib/1c#unit) `b` with the product of a called [`trap`](/docs/glossary/trap)
94`a`. If the [`unit`](/docs/hoon/reference/stdlib/1c#unit) is not empty, then the original [`unit`](/docs/hoon/reference/stdlib/1c#unit) is produced.
96#### Accepts
98`a` is a [`trap`](/docs/glossary/trap).
100`b` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
102#### Produces
104Either the product of `a` or the value inside of [`unit`](/docs/hoon/reference/stdlib/1c#unit) `b`.
106#### Source
108```hoon
109++ bond
110 |* a=(trap)
111 |* b=(unit)
112 ?~ b $:a
113 u.b
114```
116#### Examples
118```
119 > (bex 10)
120 1.024
121 > ((bond |.((bex 10))) ~)
122 1.024
123```
125```
126 > ((bond |.((bex 10))) (slaw %ud '123'))
127 123
128```
130---
132## `++both`
134Group [`unit`](/docs/hoon/reference/stdlib/1c#unit) values into pair
136Produces `~` if either `a` or `b` are empty. Otherwise, produces a
137[`unit`](/docs/hoon/reference/stdlib/1c#unit) whose value is a cell of the values of two input [`units`](/docs/hoon/reference/stdlib/1c#unit) `a` and
138`b`.
140#### Accepts
142`a` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
144`b` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
146#### Produces
148A [`unit`](/docs/hoon/reference/stdlib/1c#unit) of the two initial values.
150#### Source
152```hoon
153++ both
154 |* [a=(unit) b=(unit)]
155 ?~ a ~
156 ?~ b ~
157 [~ u=[u.a u.b]]
158```
160#### Examples
162```
163> (both (some 1) (some %b))
164[~ u=[1 %b]]
165```
167```
168> (both ~ (some %b))
170```
172---
174## `++clap`
176Combine two [`units`](/docs/hoon/reference/stdlib/1c#unit) with function
178Applies a binary function `c`--which does not usually accept or produce a
179[`unit`](/docs/hoon/reference/stdlib/1c#unit)-- to the values of two [`units`](/docs/hoon/reference/stdlib/1c#unit), `a` and `b`, producing a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
181If `a` is null, produces `b`. If `b` is null, produces `a`. Otherwise, produces the produce of `c` in a `unit`.
183#### Accepts
185`a` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
187`b` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
189`c` is a function that performs a binary operation.
191#### Produces
193A [`unit`](/docs/hoon/reference/stdlib/1c#unit).
195#### Source
197```hoon
198++ clap
199 |* [a=(unit) b=(unit) c=_=>(~ |=(^ +<-))]
200 ?~ a b
201 ?~ b a
202 [~ u=(c u.a u.b)]
203```
205#### Examples
207```
208> (clap ~ `'b' |=([a=@tD b=@tD] `tape`[a b ~]))
209[~ u='b']
210```
212```
213> (clap `'a' ~ |=([a=@tD b=@tD] `tape`[a b ~]))
214[~ u='a']
215```
217```
218> (clap `'a' `'b' |=([a=@tD b=@tD] `tape`[a b ~]))
219[~ u="ab"]
220```
222---
224## `++clef`
226Compose two [`units`](/docs/hoon/reference/stdlib/1c#unit) with function
228Applies a binary function `c`--which does not usually accept [`units`](/docs/hoon/reference/stdlib/1c#unit)-- to the values of two [`units`](/docs/hoon/reference/stdlib/1c#unit), `a` and `b`, producing a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
230If `a` or `b` are null, produces null. Otherwise, produces the produce of `c`.
232#### Accepts
234`a` is a `unit`.
236`b` is a `unit`.
238`c` is a `gate` that takes a `cell` and produces a `unit`.
240#### Produces
242A `unit`.
244#### Source
246```hoon
247++ clef
248 |* [a=(unit) b=(unit) c=_=>(~ |=(^ `+<-))]
249 ?~ a ~
250 ?~ b ~
251 (c u.a u.b)
252```
254#### Examples
256```
257> (clef ~ `'b' |=([a=@tD b=@tD] `(unit tape)`[~ [a b ~]]))
259```
261```
262> (clef `'a' ~ |=([a=@tD b=@tD] `(unit tape)`[~ [a b ~]]))
264```
266```
267> (clef `'a' `'b' |=([a=@tD b=@tD] `(unit tape)`[~ [a b ~]]))
268[~ "ab"]
269```
271---
273## `++drop`
275[`Unit`](/docs/hoon/reference/stdlib/1c#unit) to list
277Makes a [`++list`](/docs/hoon/reference/stdlib/1c#list) of the unwrapped value (`u.a`) of a [`unit`](/docs/hoon/reference/stdlib/1c#unit) `a`.
279#### Accepts
281`a` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
283#### Produces
285A list.
287#### Source
289```hoon
290++ drop
291 |* a=(unit)
292 ?~ a ~
293 [i=u.a t=~]
294```
296#### Examples
298```
299> =a ((unit @) [~ 97])
300> (drop a)
301[i=97 t=~]
302```
304```
305> =a ((unit @) [~])
306> (drop a)
308```
310---
312## `++fall`
314Give [`unit`](/docs/hoon/reference/stdlib/1c#unit) a default value
316Produces a default value `b` for a [`unit`](/docs/hoon/reference/stdlib/1c#unit) `a` in cases where `a` is null.
318#### Accepts
320`a` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
322`b` is a [`noun`](/docs/glossary/noun) that's used as the default value.
324#### Produces
326Either a [`noun`](/docs/glossary/noun) `b` or the unwrapped value of [`unit`](/docs/hoon/reference/stdlib/1c#unit) `a`.
328#### Source
330```hoon
331++ fall
332 |* [a=(unit) b=*]
333 ?~(a b u.a)
334```
336#### Examples
338```
339> (fall ~ 'a')
340'a'
341> (fall [~ u=0] 'a')
343```
345---
347## `++flit`
349Make filter
351Accepts gate `a` which produces a `?`. Applies `a` to `b`, producing `b` wrapped in a `unit` if true, otherwise produces null.
353`+flit` is a wet gate that takes `a` and produces a new wet gate that takes `b`.
355#### Accepts
357`a` is a `gate` which produces `?`, and is the sample of the outer wet gate.
359`b` is any `noun`, and is the sample of the inner wet gate.
361#### Produces
363`(unit [type])`, where `[type]` is the type of `b`.
365#### Source
367```hoon
368++ flit
369 |* a=$-(* ?)
370 |* b=*
371 ?.((a b) ~ [~ u=b])
372```
374#### Examples
376```
377> =f (flit |=(=@ud ?:(=(ud 1) %.y %.n)))
378> (f 1)
379[~ 1]
380> (f 2)
382```
384---
386## `++hunt`
388First of units
390Apply binary gate `ord`, which produces a `?`, to units `a` and `b`. Produce `a` if true and `b` if false. If `a` is null, produce `b`. If `b` is null, produce `a`.
392This allows selecting between two units by some rule.
394#### Accepts
396`ord` is a `$-(^ ?)` - a binary gate that produces `?`.
398`a` is a `unit`.
400`b` is a `unit`.
402#### Produces
404A `unit`.
406#### Source
408```hoon
409++ hunt
410 |* [ord=$-(^ ?) a=(unit) b=(unit)]
411 ^- %- unit
412 $? _?>(?=(^ a) u.a)
413 _?>(?=(^ b) u.b)
414 ==
415 ?~ a b
416 ?~ b a
417 ?:((ord u.a u.b) a b)
418```
420#### Examples
422```
423> (hunt gte ~ `20)
424[~ 20]
425```
427```
428> (hunt gte `10 ~)
429[~ 10]
430```
432```
433> (hunt gte `10 `20)
434[~ 20]
435```
437---
439## `++lift`
441Curried bind
443Accepts function `a` and produces a function that accepts [`unit`](/docs/hoon/reference/stdlib/1c#unit)
444`b` to which it applies `a`. Used when you want a function that does not accept
445or produce a [`unit`](/docs/hoon/reference/stdlib/1c#unit) to both accept and produce a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
447#### Accepts
449`a` is a `mold`.
451`b` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
453#### Produces
455A [`unit`](/docs/hoon/reference/stdlib/1c#unit).
457#### Source
459```hoon
460++ lift
461 |* a=mold
462 |* b=(unit)
463 (bind b a)
464```
466#### Examples
468```
469> ((lift dec) `(unit @)`~)
471```
473```
474> ((lift dec) `(unit @)`[~ 20])
475[~ 19]
476```
478---
480## `++mate`
482Choose
484Accepts two [`units`](/docs/hoon/reference/stdlib/1c#unit) `a` and `b` whose values are expected to be
485equivalent. If either is empty, then the value of the other is produced.
486If neither are empty, it asserts that both values are the same and
487produces that value. If the assertion fails, `++mate` crashes with
488`'mate'` in the stack trace.
490#### Accepts
492`a` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
494`b` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
496#### Produces
498A [`unit`](/docs/hoon/reference/stdlib/1c#unit) or crash.
500#### Source
502```hoon
503++ mate
504 |* [a=(unit) b=(unit)]
505 ?~ b a
506 ?~ a b
507 ?.(=(u.a u.b) ~>(%mean.'mate' !!) a)
508```
510#### Examples
512```
513> =a ((unit @) [~ 97])
514> =b ((unit @) [~ 97])
515> (mate a b)
516[~ 97]
517```
519```
520> =a ((unit @) [~ 97])
521> =b ((unit @) [~])
522> (mate a b)
523[~ 97]
524```
526```
527> =a ((unit @) [~ 97])
528> =b ((unit @) [~ 98])
529> (mate a b)
530! 'mate'
531! exit
532```
534---
536## `++need`
538Unwrap [`unit`](/docs/hoon/reference/stdlib/1c#unit)
540Retrieve the value from a [`unit`](/docs/hoon/reference/stdlib/1c#unit) and crash if the [`unit`](/docs/hoon/reference/stdlib/1c#unit) is null.
542#### Accepts
544`a` is a [`unit`](/docs/hoon/reference/stdlib/1c#unit).
546#### Produces
548Either the unwrapped value of `a` (`u.a`), or crash.
550#### Source
552```hoon
553++ need
554 ~/ %need
555 |* a=(unit)
556 ?~ a ~>(%mean.'need' !!)
557 u.a
558```
560#### Examples
562```
563> =a ((unit [@t @t]) [~ ['a' 'b']])
564> (need a)
565['a' 'b']
566```
568```
569> =a ((unit @ud) [~ 17])
570> (need a)
57117
572```
574```
575> =a ((unit @) [~])
576> (need a)
577! exit
578```
580---
582## `++some`
584Wrap value in a [`unit`](/docs/hoon/reference/stdlib/1c#unit)
586Takes any [`noun`](/docs/glossary/noun) `a` and produces a [`unit`](/docs/hoon/reference/stdlib/1c#unit) with the value set to `a`.
588#### Accepts
590`a` is a [`noun`](/docs/glossary/noun).
592#### Produces
594A [`unit`](/docs/hoon/reference/stdlib/1c#unit).
596#### Source
598```hoon
599++ some
600 |* a=*
601 [~ u=a]
602```
604#### Examples
606```
607> (some ['a' 'b'])
608[~ u=['a' 'b']]
609```
611```
612> (some &)
613[~ u=%.y]
614```
616---