git.iko.soy/urbit.org
on c19b089 help sign in
urbit.org/hoon/reference/stdlib/2a.md
449 lines 6.5 kB history raw
1+++
2title = "2a: Unit Logic"
3weight = 4
4template = "doc.html"
5+++
7### `++biff`
9Unit as argument
11Applies a function `b` that produces a unit to the unwrapped value of ++unit
12`a` (`u.a`). If `a` is empty, `~` is produced.
14#### Accepts
16`a` is a unit.
18`b` is a function that accepts a noun and produces a unit.
20#### Produces
22A 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, producing unit
49Applies a function `b` to the value (`u.a`) of a ++unit `a`, producing
50a unit. Used when you want a function that does not accept or produce a
51unit to both accept and produce a unit.
53#### Accepts
55`a` is a unit.
57`b` is a function.
59#### Produces
61A 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 `b` with the product of a called trap
91`a`. If the unit is not empty, then the original unit is produced.
93#### Accepts
95`a` is a trap.
97`b` is a unit.
99#### Produces
101Either the product of `a` or the value inside of 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 values into pair
131Produces `~` if either `a` or `b` are empty. Otherwise, produces a
132++unit whose value is a cell of the values of two input units `a` and
133`b`.
135#### Accepts
137`a` is a unit.
139`b` is a unit.
141#### Produces
143A 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
170Applies a binary function `c`--which does not usually accept or produce a
171`++unit`-- to the values of two units, `a` and `b`, producing a unit.
173#### Accepts
175`a` is a unit.
177`b` is a unit.
179`c` is a function that performs a binary operation.
181#### Produces
183A 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`
215Unit to list
217Makes a ++list of the unwrapped value (`u.a`) of a `++unit` `a`.
219#### Accepts
221`a` is a 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 a default value
254Produces a default value `b` for a `++unit` `a` in cases where `a` is null.
256#### Accepts
258`a` is a unit.
260`b` is a noun that's used as the default value.
262#### Produces
264Either a noun `b` or the unwrapped value of 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`
289`b` to which it applies `a`. Used when you want a function that does not accept
290or produce a unit to both accept and produce a unit.
292#### Accepts
294`a` is a gate.
296`b` is a unit.
298#### Produces
300A 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 `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.
337`b` is a unit.
339#### Produces
341A 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
379Retrieve the value from a `++unit` and crash if the unit is null.
381#### Accepts
383`a` is a 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
420Takes any noun `a` and produces a `++unit` with the value set to `a`.
422#### Accepts
424`a` is a noun.
426#### Produces
428A 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---