git.iko.soy/urbit.org
on 140ac0e help sign in
urbit.org/docs/programming/reference/library/2a.md
452 lines 6.6 kB history raw
1# 2a: unit logic
2### `++biff`
4Unit as argument
6Applies a function `b` that produces a unit to the unwrapped value of ++unit
7`a` (`u.a`). If `a` is empty, `~` is produced.
9Accepts
10-------
12`a` is a unit.
14`b` is a function that accepts a noun and produces a unit.
16Produces
17--------
19A unit.
21Source
22------
24 ++ biff :: apply
25 |* {a/(unit) b/$-(* (unit))}
26 ?~ a ~
27 (b u.a)
30Examples
31--------
33 > (biff (some 5) |=(a/@ (some (add a 2))))
34 [~ u=7]
35 > (biff ~ |=(a/@ (some (add a 2))))
36 ~
40***
41### `++bind`
43Non-unit function to unit, producing unit
45Applies a function `b` to the value (`u.a`) of a ++unit `a`, producing
46a unit. Used when you want a function that does not accept or produce a
47unit to both accept and produce a unit.
49Accepts
50-------
52`a` is a unit.
54`b` is a function.
56Produces
57--------
59A unit.
61Source
62------
64 ++ bind :: argue
65 |* {a/(unit) b/gate}
66 ?~ a ~
67 [~ u=(b u.a)]
70Examples
71--------
73 > (bind ((unit @) [~ 97]) ,@t)
74 [~ `a`]
75 > =a |=(a/@ (add a 1))
76 > (bind ((unit @) [~ 2]) a)
77 [~ 3]
81***
82### `++bond`
84Replace null
86Replaces an empty ++unit `b` with the product of a called trap
87`a`. If the unit is not empty, then the original unit is produced.
89Accepts
90-------
92`a` is a trap.
94`b` is a unit.
96Produces
97--------
99Either the product of `a` or the value inside of unit `b`.
101Source
102------
104 ++ bond :: replace
105 |* a/(trap)
106 |* b/(unit)
107 ?~ b $:a
108 u.b
111Examples
112--------
114 > (bex 10)
115 1.024
116 > ((bond |.((bex 10))) ~)
117 1.024
118 > ((bond |.((bex 10))) (slaw %ud '123'))
119 123
123***
124### `++both`
126Group unit values into pair
128Produces `~` if either `a` or `b` are empty. Otherwise, produces a
129++unit whose value is a cell of the values of two input units `a` and
130`b`.
132Accepts
133-------
135`a` is a unit.
137`b` is a unit.
139Produces
140--------
142A unit of the two initial values.
144Source
145------
147 ++ both :: all the above
148 |* {a/(unit) b/(unit)}
149 ?~ a ~
150 ?~ b ~
151 [~ u=[u.a u.b]]
154Examples
155--------
157 > (both (some 1) (some %b))
158 [~ u=[1 %b]]
159 > (both ~ (some %b))
160 ~
163***
164### `++clap`
166Apply function to two units
168Applies a binary function `c`--which does not usually accept or produce a `++unit`--
169to the values of two units, `a` and `b`, producing a unit.
171Accepts
172-------
174`a` is a unit.
176`b` is a unit.
178`c` is a function that performs a binary operation.
180Produces
181--------
183A unit.
185Source
186------
188 ++ clap :: combine
189 |* {a/(unit) b/(unit) c/_|=(^ +<-)}
190 ?~ a b
191 ?~ b a
192 [~ u=(c u.a u.b)]
195Examples
196--------
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"]
202 > =a ((unit @u) [~ 1])
203 > =b ((unit @u) [~ 2])
204 > =c |=([a=@ b=@] (add a b))
205 > (clap a b c)
206 [~ 3]
210***
211### `++drop`
213Unit to list
215Makes a ++list of the unwrapped value (`u.a`) of a `++unit` `a`.
217Accepts
218-------
220`a` is a unit.
222Produces
223--------
225A list.
227Source
228------
230 ++ drop :: enlist
231 |* a/(unit)
232 ?~ a ~
233 [i=u.a t=~]
236Examples
237--------
239 > =a ((unit @) [~ 97])
240 > (drop a)
241 [i=97 t=~]
242 > =a ((unit @) [~])
243 > (drop a)
244 ~
248***
249### `++fall`
251Give unit a default value
253Produces a default value `b` for a `++unit` `a` in cases where `a` is null.
255Accepts
256-------
258`a` is a unit.
260`b` is a noun that's used as the default value.
262Produces
263--------
265Either a noun `b` or the unwrapped value of unit `a`.
267Source
268------
270 ++ fall :: default
271 |* {a/(unit) b/*}
272 ?~(a b u.a)
275Examples
276--------
278 > (fall ~ `a`)
279 `a`
280 > (fall [~ u=0] `a`)
281 0
285***
286### `++lift`
288Curried bind
290Accepts a `++gate` `a` and produces a function that accepts `++unit`
291`b` to which it applies `a`. Used when you want a function that does not accept
292or produce a unit to both accept and produce a unit.
294Accepts
295-------
297`a` is a gate.
299`b` is a unit.
301Produces
302--------
304A unit.
306Source
307------
309 ++ lift :: lift gate (fmap)
310 |* a/gate :: flipped
311 |* b/(unit) :: curried
312 (bind b a) :: bind
315Examples
316--------
318 > ((lift dec) `(unit @)`~)
319 ~
320 > ((lift dec) `(unit @)`[~ 20])
321 [~ 19]
325***
326### `++mate`
328Choose
330Accepts two units `a` and `b` whose values are expected to be
331equivalent. If either is empty, then the value of the other is produced.
332If neither are empty, it asserts that both values are the same and
333produces that value. If the assertion fails, `++mate` crashes with
334`'mate'` in the stack trace.
336Accepts
337-------
339`a` is a unit.
341`b` is a unit.
343Produces
344--------
346A unit or crash.
348Source
349------
351 ++ mate :: choose
352 |* {a/(unit) b/(unit)}
353 ?~ b a
354 ?~ a b
355 ?.(=(u.a u.b) ~|('mate' !!) a)
358Examples
359--------
361 > =a ((unit @) [~ 97])
362 > =b ((unit @) [~ 97])
363 > (mate a b)
364 [~ 97]
365 > =a ((unit @) [~ 97])
366 > =b ((unit @) [~])
367 > (mate a b)
368 [~ 97]
369 > =a ((unit @) [~ 97])
370 > =b ((unit @) [~ 98])
371 > (mate a b)
372 ! 'mate'
373 ! exit
377***
378### `++need`
380Unwrap unit
382Retrieve the value from a `++unit` and crash if the unit is null.
384Accepts
385-------
387`a` is a unit.
389Produces
390--------
392Either the unwrapped value of `a` (`u.a`), or crash.
394Source
395------
397 ++ need :: demand
398 |* a/(unit)
399 ?~ a ~|(%need !!)
400 u.a
403Examples
404--------
406 > =a ((unit [@t @t]) [~ ['a' 'b']])
407 > (need a)
408 ['a' 'b']
409 > =a ((unit @ud) [~ 17])
410 > (need a)
411 17
412 > =a ((unit @) [~])
413 > (need a)
414 ! exit
418***
419### `++some`
421Wrap value in a unit
423Takes any atom `a` and produces a [`++unit`]() with the value set to `a`.
425Accepts
426-------
428`a` is a [noun]().
430Produces
431--------
433A unit.
435Source
436------
438 ++ some :: lift (pure)
439 |* a=*
440 [~ u=a]
442Examples
443--------
445 > (some [`a` `b`])
446 [~ u=[`a` `b`]]
447 > (some &)
448 [~ u=%.y]
452***