git.iko.soy/urbit.org
on 8564483 help sign in
urbit.org/docs/hoon/library/2a.md
457 lines 6.6 kB history raw
1---
2navhome: /docs
3---
6# 2a: unit logic
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.
14Accepts
15-------
17`a` is a unit.
19`b` is a function that accepts a noun and produces a unit.
21Produces
22--------
24A unit.
26Source
27------
29 ++ biff :: apply
30 |* {a/(unit) b/$-(* (unit))}
31 ?~ a ~
32 (b u.a)
35Examples
36--------
38 > (biff (some 5) |=(a/@ (some (add a 2))))
39 [~ u=7]
40 > (biff ~ |=(a/@ (some (add a 2))))
41 ~
45***
46### `++bind`
48Non-unit function to unit, producing unit
50Applies a function `b` to the value (`u.a`) of a ++unit `a`, producing
51a unit. Used when you want a function that does not accept or produce a
52unit to both accept and produce a unit.
54Accepts
55-------
57`a` is a unit.
59`b` is a function.
61Produces
62--------
64A unit.
66Source
67------
69 ++ bind :: argue
70 |* {a/(unit) b/gate}
71 ?~ a ~
72 [~ u=(b u.a)]
75Examples
76--------
78 > (bind ((unit @) [~ 97]) ,@t)
79 [~ `a`]
80 > =a |=(a/@ (add a 1))
81 > (bind ((unit @) [~ 2]) a)
82 [~ 3]
86***
87### `++bond`
89Replace null
91Replaces an empty ++unit `b` with the product of a called trap
92`a`. If the unit is not empty, then the original unit is produced.
94Accepts
95-------
97`a` is a trap.
99`b` is a unit.
101Produces
102--------
104Either the product of `a` or the value inside of unit `b`.
106Source
107------
109 ++ bond :: replace
110 |* a/(trap)
111 |* b/(unit)
112 ?~ b $:a
113 u.b
116Examples
117--------
119 > (bex 10)
120 1.024
121 > ((bond |.((bex 10))) ~)
122 1.024
123 > ((bond |.((bex 10))) (slaw %ud '123'))
124 123
128***
129### `++both`
131Group unit values into pair
133Produces `~` if either `a` or `b` are empty. Otherwise, produces a
134++unit whose value is a cell of the values of two input units `a` and
135`b`.
137Accepts
138-------
140`a` is a unit.
142`b` is a unit.
144Produces
145--------
147A unit of the two initial values.
149Source
150------
152 ++ both :: all the above
153 |* {a/(unit) b/(unit)}
154 ?~ a ~
155 ?~ b ~
156 [~ u=[u.a u.b]]
159Examples
160--------
162 > (both (some 1) (some %b))
163 [~ u=[1 %b]]
164 > (both ~ (some %b))
165 ~
168***
169### `++clap`
171Apply function to two units
173Applies a binary function `c`--which does not usually accept or produce a `++unit`--
174to the values of two units, `a` and `b`, producing a unit.
176Accepts
177-------
179`a` is a unit.
181`b` is a unit.
183`c` is a function that performs a binary operation.
185Produces
186--------
188A unit.
190Source
191------
193 ++ clap :: combine
194 |* {a/(unit) b/(unit) c/_|=(^ +<-)}
195 ?~ a b
196 ?~ b a
197 [~ u=(c u.a u.b)]
200Examples
201--------
203 > =u ((unit @t) [~ 'a'])
204 > =v ((unit @t) [~ 'b'])
205 > (clap u v |=([a=@t b=@t] (welp (trip a) (trip b))))
206 [~ u="ab"]
207 > =a ((unit @u) [~ 1])
208 > =b ((unit @u) [~ 2])
209 > =c |=([a=@ b=@] (add a b))
210 > (clap a b c)
211 [~ 3]
215***
216### `++drop`
218Unit to list
220Makes a ++list of the unwrapped value (`u.a`) of a `++unit` `a`.
222Accepts
223-------
225`a` is a unit.
227Produces
228--------
230A list.
232Source
233------
235 ++ drop :: enlist
236 |* a/(unit)
237 ?~ a ~
238 [i=u.a t=~]
241Examples
242--------
244 > =a ((unit @) [~ 97])
245 > (drop a)
246 [i=97 t=~]
247 > =a ((unit @) [~])
248 > (drop a)
249 ~
253***
254### `++fall`
256Give unit a default value
258Produces a default value `b` for a `++unit` `a` in cases where `a` is null.
260Accepts
261-------
263`a` is a unit.
265`b` is a noun that's used as the default value.
267Produces
268--------
270Either a noun `b` or the unwrapped value of unit `a`.
272Source
273------
275 ++ fall :: default
276 |* {a/(unit) b/*}
277 ?~(a b u.a)
280Examples
281--------
283 > (fall ~ `a`)
284 `a`
285 > (fall [~ u=0] `a`)
286 0
290***
291### `++lift`
293Curried bind
295Accepts a `++gate` `a` and produces a function that accepts `++unit`
296`b` to which it applies `a`. Used when you want a function that does not accept
297or produce a unit to both accept and produce a unit.
299Accepts
300-------
302`a` is a gate.
304`b` is a unit.
306Produces
307--------
309A unit.
311Source
312------
314 ++ lift :: lift gate (fmap)
315 |* a/gate :: flipped
316 |* b/(unit) :: curried
317 (bind b a) :: bind
320Examples
321--------
323 > ((lift dec) `(unit @)`~)
324 ~
325 > ((lift dec) `(unit @)`[~ 20])
326 [~ 19]
330***
331### `++mate`
333Choose
335Accepts two units `a` and `b` whose values are expected to be
336equivalent. If either is empty, then the value of the other is produced.
337If neither are empty, it asserts that both values are the same and
338produces that value. If the assertion fails, `++mate` crashes with
339`'mate'` in the stack trace.
341Accepts
342-------
344`a` is a unit.
346`b` is a unit.
348Produces
349--------
351A unit or crash.
353Source
354------
356 ++ mate :: choose
357 |* {a/(unit) b/(unit)}
358 ?~ b a
359 ?~ a b
360 ?.(=(u.a u.b) ~|('mate' !!) a)
363Examples
364--------
366 > =a ((unit @) [~ 97])
367 > =b ((unit @) [~ 97])
368 > (mate a b)
369 [~ 97]
370 > =a ((unit @) [~ 97])
371 > =b ((unit @) [~])
372 > (mate a b)
373 [~ 97]
374 > =a ((unit @) [~ 97])
375 > =b ((unit @) [~ 98])
376 > (mate a b)
377 ! 'mate'
378 ! exit
382***
383### `++need`
385Unwrap unit
387Retrieve the value from a `++unit` and crash if the unit is null.
389Accepts
390-------
392`a` is a unit.
394Produces
395--------
397Either the unwrapped value of `a` (`u.a`), or crash.
399Source
400------
402 ++ need :: demand
403 |* a/(unit)
404 ?~ a ~|(%need !!)
405 u.a
408Examples
409--------
411 > =a ((unit [@t @t]) [~ ['a' 'b']])
412 > (need a)
413 ['a' 'b']
414 > =a ((unit @ud) [~ 17])
415 > (need a)
416 17
417 > =a ((unit @) [~])
418 > (need a)
419 ! exit
423***
424### `++some`
426Wrap value in a unit
428Takes any atom `a` and produces a [`++unit`]() with the value set to `a`.
430Accepts
431-------
433`a` is a [noun]().
435Produces
436--------
438A unit.
440Source
441------
443 ++ some :: lift (pure)
444 |* a=*
445 [~ u=a]
447Examples
448--------
450 > (some [`a` `b`])
451 [~ u=[`a` `b`]]
452 > (some &)
453 [~ u=%.y]
457***