git.iko.soy/urbit.org
on c19bc7a help sign in
urbit.org/docs/reference/library/2a.udon
453 lines 6.4 kB history raw
1:- :~ navhome/'/docs/'
2 sort/'4'
3 title/'2a: Unit Logic'
4 ==
6;>
9# 2a: unit logic
11### `++biff`
13Unit as argument
15Applies a function `b` that produces a unit to the unwrapped value of ++unit
16`a` (`u.a`). If `a` is empty, `~` is produced.
18#### Accepts
20`a` is a unit.
22`b` is a function that accepts a noun and produces a unit.
24#### Produces
26A unit.
28#### Source
30```
31 ++ biff
32 |* [a](unit) b]$-(* (unit))]
33 ?~ a ~
34 (b u.a)
35```
37#### Examples
39```
40 > (biff (some 5) |=(a]@ (some (add a 2))))
41 [~ u=7]
43 > (biff ~ |=(a]@ (some (add a 2))))
44 ~
45```
48---
49### `++bind`
51Non-unit function to unit, producing unit
53Applies a function `b` to the value (`u.a`) of a ++unit `a`, producing
54a unit. Used when you want a function that does not accept or produce a
55unit to both accept and produce a unit.
57#### Accepts
59`a` is a unit.
61`b` is a function.
63#### Produces
65A unit.
67#### Source
69```
70 ++ bind
71 |* [a=(unit) b=gate]
72 ?~ a ~
73 [~ u=(b u.a)]
74```
77#### Examples
79```
80 > (bind ((unit @) [~ 97]) ,@t)
81 [~ u='a']
83 > =a |=(a]@ (add a 1))
84 > (bind ((unit @) [~ 2]) a)
85 [~ u=3]
86```
89---
90### `++bond`
92Replace null
94Replaces an empty ++unit `b` with the product of a called trap
95`a`. If the unit is not empty, then the original unit is produced.
97#### Accepts
99`a` is a trap.
101`b` is a unit.
103#### Produces
105Either the product of `a` or the value inside of unit `b`.
107#### Source
109```
110 ++ bond
111 |* a=(trap)
112 |* b=(unit)
113 ?~ b $:a
114 u.b
115```
117#### Examples
119```
120 > (bex 10)
121 1.024
122 > ((bond |.((bex 10))) ~)
123 1.024
125 > ((bond |.((bex 10))) (slaw %ud '123'))
126 123
127```
130---
131### `++both`
133Group unit values into pair
135Produces `~` if either `a` or `b` are empty. Otherwise, produces a
136++unit whose value is a cell of the values of two input units `a` and
137`b`.
139#### Accepts
141`a` is a unit.
143`b` is a unit.
145#### Produces
147A unit of the two initial values.
149#### Source
151```
152 ++ both
153 |* [a=(unit) b=(unit)]
154 ?~ a ~
155 ?~ b ~
156 [~ u=[u.a u.b]]
157```
159#### Examples
161```
162 > (both (some 1) (some %b))
163 [~ u=[1 %b]]
165 > (both ~ (some %b))
166 ~
167```
169---
170### `++clap`
172Apply function to two units
174Applies a binary function `c`--which does not usually accept or produce a
175`++unit`-- to the values of two units, `a` and `b`, producing a unit.
177#### Accepts
179`a` is a unit.
181`b` is a unit.
183`c` is a function that performs a binary operation.
185#### Produces
187A unit.
189#### Source
191```
192 ++ clap :: combine
193 |* [a](unit) b=(unit) c=_|=(^ +<-)]
194 ?~ a b
195 ?~ b a
196 [~ u=(c u.a u.b)]
197```
199#### Examples
201```
202 > =u ((unit @t) [~ 'a'])
203 > =v ((unit @t) [~ 'b'])
204 > (clap u v |=([a=@t b=@t] (welp (trip a) (trip b))))
205 [~ u="ab"]
207 > =a ((unit @u) [~ 1])
208 > =b ((unit @u) [~ 2])
209 > =c |=([a=@ b=@] (add a b))
211 > (clap a b c)
212 [~ 3]
213```
216---
217### `++drop`
219Unit to list
221Makes a ++list of the unwrapped value (`u.a`) of a `++unit` `a`.
223#### Accepts
225`a` is a unit.
227#### Produces
229A list.
231#### Source
233```
234 ++ drop :: enlist
235 |* a=(unit)
236 ?~ a ~
237 [i=u.a t=~]
238```
240#### Examples
242```
243 > =a ((unit @) [~ 97])
244 > (drop a)
245 [i=97 t=~]
247 > =a ((unit @) [~])
248 > (drop a)
249 ~
250```
253---
254### `++fall`
256Give unit a default value
258Produces a default value `b` for a `++unit` `a` in cases where `a` is null.
260#### Accepts
262`a` is a unit.
264`b` is a noun that's used as the default value.
266#### Produces
268Either a noun `b` or the unwrapped value of unit `a`.
270#### Source
272```
273 ++ fall :: default
274 |* [a=(unit) b=*]
275 ?~(a b u.a)
276```
278#### Examples
280```
281 > (fall ~ `a`)
282 `a`
283 > (fall [~ u=0] `a`)
284 0
285```
287---
288### `++lift`
290Curried bind
292Accepts a `++gate` `a` and produces a function that accepts `++unit`
293`b` to which it applies `a`. Used when you want a function that does not accept
294or produce a unit to both accept and produce a unit.
296#### Accepts
298`a` is a gate.
300`b` is a unit.
302#### Produces
304A unit.
306#### Source
308```
309 ++ lift :: lift gate (fmap)
310 |* a=gate :: flipped
311 |* b=(unit) :: curried
312 (bind b a) :: bind
313```
315#### Examples
317```
318 > ((lift dec) `(unit @)`~)
319 ~
321 > ((lift dec) `(unit @)`[~ 20])
322 [~ 19]
323```
326---
327### `++mate`
329Choose
331Accepts two units `a` and `b` whose values are expected to be
332equivalent. If either is empty, then the value of the other is produced.
333If neither are empty, it asserts that both values are the same and
334produces that value. If the assertion fails, `++mate` crashes with
335`'mate'` in the stack trace.
337#### Accepts
339`a` is a unit.
341`b` is a unit.
343#### Produces
345A unit or crash.
347#### Source
349```
350 ++ mate :: choose
351 |* [a=(unit) b=(unit)]
352 ?~ b a
353 ?~ a b
354 ?.(=(u.a u.b) ~|('mate' !!) a)
355```
357#### Examples
359```
360 > =a ((unit @) [~ 97])
361 > =b ((unit @) [~ 97])
362 > (mate a b)
363 [~ 97]
365 > =a ((unit @) [~ 97])
366 > =b ((unit @) [~])
367 > (mate a b)
368 [~ 97]
370 > =a ((unit @) [~ 97])
371 > =b ((unit @) [~ 98])
372 > (mate a b)
373 ! 'mate'
374 ! exit
375```
378---
379### `++need`
381Unwrap unit
383Retrieve the value from a `++unit` and crash if the unit is null.
385#### Accepts
387`a` is a unit.
389#### Produces
391Either the unwrapped value of `a` (`u.a`), or crash.
393#### Source
395```
396 ++ need :: demand
397 |* a](unit)
398 ?~ a ~|(%need !!)
399 u.a
400```
402#### Examples
404```
405 > =a ((unit [@t @t]) [~ ['a' 'b']])
406 > (need a)
407 ['a' 'b']
409 > =a ((unit @ud) [~ 17])
410 > (need a)
411 17
413 > =a ((unit @) [~])
414 > (need a)
415 ! exit
416```
419---
420### `++some`
422Wrap value in a unit
424Takes any atom `a` and produces a `++unit` with the value set to `a`.
426#### Accepts
428`a` is a noun.
430#### Produces
432A unit.
434#### Source
436```
437 ++ some :: lift (pure)
438 |* a=*
439 [~ u=a]
440```
442#### Examples
444```
445 > (some [`a` `b`])
446 [~ u=[`a` `b`]]
448 > (some &)
449 [~ u=%.y]
450```
453---