git.iko.soy/urbit.org
on 91ef98f help sign in
urbit.org/reference/library/2a.md
448 lines 6.4 kB history raw
1+++
2title = "2a: Unit Logic"
3weight = 4
4template = "doc.html"
5+++
6### `++biff`
8Unit as argument
10Applies a function `b` that produces a unit to the unwrapped value of ++unit
11`a` (`u.a`). If `a` is empty, `~` is produced.
13#### Accepts
15`a` is a unit.
17`b` is a function that accepts a noun and produces a unit.
19#### Produces
21A unit.
23#### Source
25```
26 ++ biff
27 |* [a=(unit) b=$-(* (unit))]
28 ?~ a ~
29 (b u.a)
30```
32#### Examples
34```
35 > (biff (some 5) |=(a=@ (some (add a 2))))
36 [~ u=7]
38 > (biff ~ |=(a=@ (some (add a 2))))
39 ~
40```
43---
44### `++bind`
46Non-unit function to unit, producing unit
48Applies a function `b` to the value (`u.a`) of a ++unit `a`, producing
49a unit. Used when you want a function that does not accept or produce a
50unit to both accept and produce a unit.
52#### Accepts
54`a` is a unit.
56`b` is a function.
58#### Produces
60A unit.
62#### Source
64```
65 ++ bind
66 |* [a=(unit) b=gate]
67 ?~ a ~
68 [~ u=(b u.a)]
69```
72#### Examples
74```
75 > (bind ((unit @) [~ 97]) ,@t)
76 [~ u='a']
78 > =a |=(a=@ (add a 1))
79 > (bind ((unit @) [~ 2]) a)
80 [~ u=3]
81```
84---
85### `++bond`
87Replace null
89Replaces an empty ++unit `b` with the product of a called trap
90`a`. If the unit is not empty, then the original unit is produced.
92#### Accepts
94`a` is a trap.
96`b` is a unit.
98#### Produces
100Either the product of `a` or the value inside of unit `b`.
102#### Source
104```
105 ++ bond
106 |* a=(trap)
107 |* b=(unit)
108 ?~ b $:a
109 u.b
110```
112#### Examples
114```
115 > (bex 10)
116 1.024
117 > ((bond |.((bex 10))) ~)
118 1.024
120 > ((bond |.((bex 10))) (slaw %ud '123'))
121 123
122```
125---
126### `++both`
128Group unit values into pair
130Produces `~` if either `a` or `b` are empty. Otherwise, produces a
131++unit whose value is a cell of the values of two input units `a` and
132`b`.
134#### Accepts
136`a` is a unit.
138`b` is a unit.
140#### Produces
142A unit of the two initial values.
144#### Source
146```
147 ++ both
148 |* [a=(unit) b=(unit)]
149 ?~ a ~
150 ?~ b ~
151 [~ u=[u.a u.b]]
152```
154#### Examples
156```
157 > (both (some 1) (some %b))
158 [~ u=[1 %b]]
160 > (both ~ (some %b))
161 ~
162```
164---
165### `++clap`
167Apply function to two units
169Applies a binary function `c`--which does not usually accept or produce a
170`++unit`-- to the values of two units, `a` and `b`, producing a unit.
172#### Accepts
174`a` is a unit.
176`b` is a unit.
178`c` is a function that performs a binary operation.
180#### Produces
182A unit.
184#### Source
186```
187 ++ clap :: combine
188 |* [a=(unit) b=(unit) c=_|=(^ +<-)]
189 ?~ a b
190 ?~ b a
191 [~ u=(c u.a u.b)]
192```
194#### Examples
196```
197 > =u ((unit @t) [~ 'a'])
198 > =v ((unit @t) [~ 'b'])
199 > (clap u v |=([a=@t b=@t] (welp (trip a) (trip b))))
200 [~ u="ab"]
202 > =a ((unit @u) [~ 1])
203 > =b ((unit @u) [~ 2])
204 > =c |=([a=@ b=@] (add a b))
206 > (clap a b c)
207 [~ 3]
208```
211---
212### `++drop`
214Unit to list
216Makes a ++list of the unwrapped value (`u.a`) of a `++unit` `a`.
218#### Accepts
220`a` is a unit.
222#### Produces
224A list.
226#### Source
228```
229 ++ drop :: enlist
230 |* a=(unit)
231 ?~ a ~
232 [i=u.a t=~]
233```
235#### Examples
237```
238 > =a ((unit @) [~ 97])
239 > (drop a)
240 [i=97 t=~]
242 > =a ((unit @) [~])
243 > (drop a)
244 ~
245```
248---
249### `++fall`
251Give unit a default value
253Produces a default value `b` for a `++unit` `a` in cases where `a` is null.
255#### Accepts
257`a` is a unit.
259`b` is a noun that's used as the default value.
261#### Produces
263Either a noun `b` or the unwrapped value of unit `a`.
265#### Source
267```
268 ++ fall :: default
269 |* [a=(unit) b=*]
270 ?~(a b u.a)
271```
273#### Examples
275```
276 > (fall ~ `a`)
277 `a`
278 > (fall [~ u=0] `a`)
279 0
280```
282---
283### `++lift`
285Curried bind
287Accepts a `++gate` `a` and produces a function that accepts `++unit`
288`b` to which it applies `a`. Used when you want a function that does not accept
289or produce a unit to both accept and produce a unit.
291#### Accepts
293`a` is a gate.
295`b` is a unit.
297#### Produces
299A unit.
301#### Source
303```
304 ++ lift :: lift gate (fmap)
305 |* a=gate :: flipped
306 |* b=(unit) :: curried
307 (bind b a) :: bind
308```
310#### Examples
312```
313 > ((lift dec) `(unit @)`~)
314 ~
316 > ((lift dec) `(unit @)`[~ 20])
317 [~ 19]
318```
321---
322### `++mate`
324Choose
326Accepts two units `a` and `b` whose values are expected to be
327equivalent. If either is empty, then the value of the other is produced.
328If neither are empty, it asserts that both values are the same and
329produces that value. If the assertion fails, `++mate` crashes with
330`'mate'` in the stack trace.
332#### Accepts
334`a` is a unit.
336`b` is a unit.
338#### Produces
340A unit or crash.
342#### Source
344```
345 ++ mate :: choose
346 |* [a=(unit) b=(unit)]
347 ?~ b a
348 ?~ a b
349 ?.(=(u.a u.b) ~|('mate' !!) a)
350```
352#### Examples
354```
355 > =a ((unit @) [~ 97])
356 > =b ((unit @) [~ 97])
357 > (mate a b)
358 [~ 97]
360 > =a ((unit @) [~ 97])
361 > =b ((unit @) [~])
362 > (mate a b)
363 [~ 97]
365 > =a ((unit @) [~ 97])
366 > =b ((unit @) [~ 98])
367 > (mate a b)
368 ! 'mate'
369 ! exit
370```
373---
374### `++need`
376Unwrap unit
378Retrieve the value from a `++unit` and crash if the unit is null.
380#### Accepts
382`a` is a unit.
384#### Produces
386Either the unwrapped value of `a` (`u.a`), or crash.
388#### Source
390```
391 ++ need :: demand
392 |* a=(unit)
393 ?~ a ~|(%need !!)
394 u.a
395```
397#### Examples
399```
400 > =a ((unit [@t @t]) [~ ['a' 'b']])
401 > (need a)
402 ['a' 'b']
404 > =a ((unit @ud) [~ 17])
405 > (need a)
406 17
408 > =a ((unit @) [~])
409 > (need a)
410 ! exit
411```
414---
415### `++some`
417Wrap value in a unit
419Takes any atom `a` and produces a `++unit` with the value set to `a`.
421#### Accepts
423`a` is a noun.
425#### Produces
427A unit.
429#### Source
431```
432 ++ some :: lift (pure)
433 |* a=*
434 [~ u=a]
435```
437#### Examples
439```
440 > (some [`a` `b`])
441 [~ u=[`a` `b`]]
443 > (some &)
444 [~ u=%.y]
445```
448---