git.iko.soy/urbit.org
on fee2eb2 help sign in
urbit.org/hoon/reference/stdlib/2a.md
449 lines 9.1 kB history raw
1+++
2title = "2a: Unit Logic"
3weight = 4
4template = "doc.html"
5+++
7### `++biff`
9[`Unit`](@/docs/hoon/reference/stdlib/1c.md#unit) as argument
11Applies a function `b` that produces a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) to the unwrapped value of [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit)
12`a` (`u.a`). If `a` is empty, `~` is produced.
14#### Accepts
16`a` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
18`b` is a function that accepts a [`noun`](@/docs/glossary/noun.md) and produces a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
20#### Produces
22A [`unit`](@/docs/hoon/reference/stdlib/1c.md#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]
39 > (biff ~ |=(a=@ (some (add a 2))))
40 ~
41```
44---
45### `++bind`
47Non-unit function to [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit), producing [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit)
49Applies a function `b` to the value (`u.a`) of a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) `a`, producing
50a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit). Used when you want a function that does not accept or produce a
51[`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) to both accept and produce a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
53#### Accepts
55`a` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
57`b` is a function.
59#### Produces
61A [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
63#### Source
65```hoon
66 ++ bind
67 |* [a=(unit) b=gate]
68 ?~ a ~
69 [~ u=(b u.a)]
70```
73#### Examples
75```
76 > (bind ((unit @) [~ 97]) ,@t)
77 [~ u='a']
79 > =a |=(a=@ (add a 1))
80 > (bind ((unit @) [~ 2]) a)
81 [~ u=3]
82```
85---
86### `++bond`
88Replace null
90Replaces an empty [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) `b` with the product of a called [`trap`](@/docs/glossary/trap.md)
91`a`. If the [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) is not empty, then the original [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) is produced.
93#### Accepts
95`a` is a [`trap`](@/docs/glossary/trap.md).
97`b` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
99#### Produces
101Either the product of `a` or the value inside of [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) `b`.
103#### Source
105```hoon
106 ++ bond
107 |* a=(trap)
108 |* b=(unit)
109 ?~ b $:a
110 u.b
111```
113#### Examples
115```
116 > (bex 10)
117 1.024
118 > ((bond |.((bex 10))) ~)
119 1.024
121 > ((bond |.((bex 10))) (slaw %ud '123'))
122 123
123```
126---
127### `++both`
129Group [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) values into pair
131Produces `~` if either `a` or `b` are empty. Otherwise, produces a
132[`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) whose value is a cell of the values of two input [`units`](@/docs/hoon/reference/stdlib/1c.md#unit) `a` and
133`b`.
135#### Accepts
137`a` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
139`b` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
141#### Produces
143A [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) of the two initial values.
145#### Source
147```hoon
148 ++ both
149 |* [a=(unit) b=(unit)]
150 ?~ a ~
151 ?~ b ~
152 [~ u=[u.a u.b]]
153```
155#### Examples
157```
158 > (both (some 1) (some %b))
159 [~ u=[1 %b]]
161 > (both ~ (some %b))
162 ~
163```
165---
166### `++clap`
168Apply function to two [`units`](@/docs/hoon/reference/stdlib/1c.md#unit)
170Applies a binary function `c`--which does not usually accept or produce a
171[`unit`](@/docs/hoon/reference/stdlib/1c.md#unit)-- to the values of two [`units`](@/docs/hoon/reference/stdlib/1c.md#unit), `a` and `b`, producing a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
173#### Accepts
175`a` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
177`b` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
179`c` is a function that performs a binary operation.
181#### Produces
183A [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
185#### Source
187```hoon
188 ++ clap :: combine
189 |* [a=(unit) b=(unit) c=_|=(^ +<-)]
190 ?~ a b
191 ?~ b a
192 [~ u=(c u.a u.b)]
193```
195#### Examples
197```
198 > =u ((unit @t) [~ 'a'])
199 > =v ((unit @t) [~ 'b'])
200 > (clap u v |=([a=@t b=@t] (welp (trip a) (trip b))))
201 [~ u="ab"]
203 > =a ((unit @u) [~ 1])
204 > =b ((unit @u) [~ 2])
205 > =c |=([a=@ b=@] (add a b))
207 > (clap a b c)
208 [~ 3]
209```
212---
213### `++drop`
215[`Unit`](@/docs/hoon/reference/stdlib/1c.md#unit) to list
217Makes a [`++list`](@/docs/hoon/reference/stdlib/1c.md#list) of the unwrapped value (`u.a`) of a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) `a`.
219#### Accepts
221`a` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
223#### Produces
225A list.
227#### Source
229```hoon
230 ++ drop :: enlist
231 |* a=(unit)
232 ?~ a ~
233 [i=u.a t=~]
234```
236#### Examples
238```
239 > =a ((unit @) [~ 97])
240 > (drop a)
241 [i=97 t=~]
243 > =a ((unit @) [~])
244 > (drop a)
245 ~
246```
249---
250### `++fall`
252Give [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) a default value
254Produces a default value `b` for a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) `a` in cases where `a` is null.
256#### Accepts
258`a` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
260`b` is a [`noun`](@/docs/glossary/noun.md) that's used as the default value.
262#### Produces
264Either a [`noun`](@/docs/glossary/noun.md) `b` or the unwrapped value of [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) `a`.
266#### Source
268```hoon
269 ++ fall :: default
270 |* [a=(unit) b=*]
271 ?~(a b u.a)
272```
274#### Examples
276```
277 > (fall ~ 'a')
278 'a'
279 > (fall [~ u=0] 'a')
280 0
281```
283---
284### `++lift`
286Curried bind
288Accepts a `++gate` `a` and produces a function that accepts [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit)
289`b` to which it applies `a`. Used when you want a function that does not accept
290or produce a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) to both accept and produce a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
292#### Accepts
294`a` is a gate.
296`b` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
298#### Produces
300A [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
302#### Source
304```hoon
305 ++ lift :: lift gate (fmap)
306 |* a=gate :: flipped
307 |* b=(unit) :: curried
308 (bind b a) :: bind
309```
311#### Examples
313```
314 > ((lift dec) `(unit @)`~)
315 ~
317 > ((lift dec) `(unit @)`[~ 20])
318 [~ 19]
319```
322---
323### `++mate`
325Choose
327Accepts two [`units`](@/docs/hoon/reference/stdlib/1c.md#unit) `a` and `b` whose values are expected to be
328equivalent. If either is empty, then the value of the other is produced.
329If neither are empty, it asserts that both values are the same and
330produces that value. If the assertion fails, `++mate` crashes with
331`'mate'` in the stack trace.
333#### Accepts
335`a` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
337`b` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
339#### Produces
341A [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) or crash.
343#### Source
345```hoon
346 ++ mate :: choose
347 |* [a=(unit) b=(unit)]
348 ?~ b a
349 ?~ a b
350 ?.(=(u.a u.b) ~|('mate' !!) a)
351```
353#### Examples
355```
356 > =a ((unit @) [~ 97])
357 > =b ((unit @) [~ 97])
358 > (mate a b)
359 [~ 97]
361 > =a ((unit @) [~ 97])
362 > =b ((unit @) [~])
363 > (mate a b)
364 [~ 97]
366 > =a ((unit @) [~ 97])
367 > =b ((unit @) [~ 98])
368 > (mate a b)
369 ! 'mate'
370 ! exit
371```
374---
375### `++need`
377Unwrap [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit)
379Retrieve the value from a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) and crash if the [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) is null.
381#### Accepts
383`a` is a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
385#### Produces
387Either the unwrapped value of `a` (`u.a`), or crash.
389#### Source
391```hoon
392 ++ need :: demand
393 |* a=(unit)
394 ?~ a ~|(%need !!)
395 u.a
396```
398#### Examples
400```
401 > =a ((unit [@t @t]) [~ ['a' 'b']])
402 > (need a)
403 ['a' 'b']
405 > =a ((unit @ud) [~ 17])
406 > (need a)
407 17
409 > =a ((unit @) [~])
410 > (need a)
411 ! exit
412```
415---
416### `++some`
418Wrap value in a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit)
420Takes any [`noun`](@/docs/glossary/noun.md) `a` and produces a [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit) with the value set to `a`.
422#### Accepts
424`a` is a [`noun`](@/docs/glossary/noun.md).
426#### Produces
428A [`unit`](@/docs/hoon/reference/stdlib/1c.md#unit).
430#### Source
432```hoon
433 ++ some :: lift (pure)
434 |* a=*
435 [~ u=a]
436```
438#### Examples
440```
441 > (some ['a' 'b'])
442 [~ u=['a' 'b']]
444 > (some &)
445 [~ u=%.y]
446```
449---