on dc20522 help sign in
1138 lines 16 kB history raw
1+++
2title = "2i: Map Logic"
3weight = 12
4template = "doc.html"
5+++
7### `++by`
9Map operations
11Container arm for map operation arms. A map is a set of key-value pairs. The
12contained arms inherit its sample map, `a`.
14### Accepts
16`a` is a map.
18#### Source
20```hoon
21 ++ by
22 ~/ %by
23 =| a=(tree (pair))
24 =* node ?>(?=(^ a) n.a)
25```
27#### Examples
29```
30 > ~(. by (my [%a 1] [%b 2] ~))
31 < 27.zjr
32 { a
33 ?(
34 { n/{?(p/$a p/$b) q/@ud}
35 l/nlr({p/?($b $a) q/@ud})
36 r/nlr({p/?($b $a) q/@ud})
37 }
38 $~
39 )
40 <119.wim 31.ohr 1.jmk $143>
41 }
42```
44---
45### `+-all:by`
47Logical AND
49Computes the logical AND on the results of slamming every element in map `a`
50with gate `b`.
52#### Accepts
54`a` is a map.
56`b` is a wet gate.
58#### Produces
60A flag.
62#### Source
64```hoon
65 +- all
66 ~/ %all
67 |* b=$-(* ?)
68 |- ^- ?
69 ?~ a
70 &
71 ?&((b q.n.a) $(a l.a) $(a r.a))
72```
74#### Examples
76```
77 > =b (my [['a' 1] ['b' [2 3]] ~])
78 > (~(all by b) |=(a=* ?@(a & |)))
79 %.n
81 > =a (my [['a' 1] ['b' 2] ['c' 3] ['d' 4] ['e' 5] ~])
82 > (~(all by a) |=(a=@ (lte a 6)))
83 %.y
85 > (~(all by a) |=(a=@ (lte a 4)))
86 %.n
87```
89---
90### `+-any:by`
92Logical OR
94Computes the logical OR on the results of slamming every element with
95gate `b`.
97#### Accepts
99`a` is a map.
101`b` is a wet gate.
103#### Produces
105A flag.
107#### Source
109```hoon
110 +- any
111 ~/ %any
112 |* b=$-(* ?)
113 |- ^- ?
114 ?~ a
115 |
116 ?|((b q.n.a) $(a l.a) $(a r.a))
117```
119#### Examples
121```
122 > =b (my [['a' 1] ['b' [2 3]] ~])
123 > (~(any by b) |=(a=* ?@(a & |)))
124 %.y
126 > =a (my [['a' 1] ['b' 2] ['c' 3] ['d' 4] ['e' 5] ~])
127 > (~(any by a) |=(a=@ (lte a 4)))
128 %.y
129```
131---
132### `+-apt:by`
134Check correctness
136Computes whether `a` has a correct horizontal order and a correct vertical
137order, producing a flag.
139#### Accepts
141`a` is a map.
143#### Produces
145A flag.
147#### Source
149```hoon
150 +- apt
151 =| [l=(unit) r=(unit)]
152 |- ^- ?
153 ?~ a &
154 ?& ?~(l & (gor p.n.a u.l))
155 ?~(r & (gor u.r p.n.a))
156 ?~(l.a & ?&((vor p.n.a p.n.l.a) $(a l.a, l `p.n.a)))
157 ?~(r.a & ?&((vor p.n.a p.n.r.a) $(a r.a, r `p.n.a)))
158 ==
159```
161#### Examples
163```
164 > =a (my [['a' 1] ['b' [2 3]] ~])
165 > ~(apt by a)
166 %.y
168 > =s (my [[1 2] [3 4] ~])
169 > =z ?~ s ~ s(p.n 10)
170 > z
171 [n=[p=10 q=2] l={} r={[p=3 q=4]}]
173 > ~(apt by z)
174 %.n
175```
177#### Discussion
179See section [`2f`](@/docs/reference/library/2f.md) for more information on noun ordering.
181### `+-bif:by`
183Bifurcate
185Splits map `a` into two maps `l` and `r`, with the head at `b` discarded.
187#### Accepts
189`a` is a map.
191`b` is a noun.
193`c` is a noun.
195#### Produces
197A cell of two maps.
199#### Source
201```hoon
202 +- bif
203 ~/ %bif
204 |* [b=* c=*]
205 ^+ [l=a r=a]
206 =< +
207 |- ^+ a
208 ?~ a
209 [[b c] ~ ~]
210 ?: =(b p.n.a)
211 ?: =(c q.n.a)
212 a
213 [[b c] l.a r.a]
214 ?: (gor b p.n.a)
215 =+ d=$(a l.a)
216 ?> ?=(^ d)
217 [n.d l.d [n.a r.d r.a]]
218 =+ d=$(a r.a)
219 ?> ?=(^ d)
220 [n.d [n.a l.a l.d] r.d]
221```
223#### Examples
225```
226 > =a (my [['a' 1] ['b' 2] ['c' 3] ~])
228 > (~(bif by a) ['b' 2])
229 [l=[n=[p='c' q=3] l=[n=[p='a' q=1] l={} r={}] r=~] r=~]
230```
232### `+-def:by`
234Difference
236#### Accepts
238`a` is a map.
240`b` is a map.
242#### Produces
244A map.
246#### Source
248```hoon
249 +- def
250 |* b=_a
251 ^- (map _p:node (pair (unit _q:node) (unit _q:node)))
252 !!
253```
255#### Examples
257---
258### `+-dep:by`
260Difference as patch
263#### Accepts
265`a` is a map.
267`b` is a map.
269#### Produces
271A cell of maps.
273#### Source
275```hoon
276 +- dep
277 |* b=_a
278 ^+ [p=a q=a]
279 =+ c=~(tap by (def b))
280 =+ [d e]=[`_a`~ `_a`~]
281 |- ^+ [d e]
282 ?~ c [d e]
283 %= $
284 c t.c
285 d ?~(q.q.i.c d (~(put by d) p.i.c u.q.q.i.c))
286 e ?~(p.q.i.c e (~(put by e) p.i.c u.p.q.i.c))
287 ==
288```
290#### Examples
294---
295### `+-del:by`
297Delete
299Produces map `a` with the element located at key `b` removed.
301#### Accepts
303`a` is a map.
305`b` is a key as a noun.
307#### Produces
309A map.
311#### Source
313```hoon
314 +- del
315 ~/ %del
316 |* b=*
317 |- ^+ a
318 ?~ a
319 ~
320 ?. =(b p.n.a)
321 ?: (gor b p.n.a)
322 [n.a $(a l.a) r.a]
323 [n.a l.a $(a r.a)]
324 |- ^- [(~ _a)]
325 ?~ l.a r.a
326 ?~ r.a l.a
327 ?: (vor p.n.l.a p.n.r.a)
328 [n.l.a l.l.a $(l.a r.l.a)]
329 [n.r.a $(r.a l.r.a) r.r.a]
330```
332#### Examples
334```
335 > =b (my [['a' 1] ['b' [2 3]] ~])
336 > (~(del by b) 'a')
337 [n=[p='b' q=[2 3]] l=~ r=~]
338```
340---
341### `+-dig:by`
343Address of key
345Produce the address of key `b` within map `a`.
347#### Accepts
349`a` is a map.
351`b` is a key as a noun.
353#### Produces
355A unit.
357#### Source
359```hoon
360 +- dig
361 |= b=*
362 =+ c=1
363 |- ^- (unit @)
364 ?~ a ~
365 ?: =(b p.n.a) [~ u=(peg c 2)]
366 ?: (gor b p.n.a)
367 $(a l.a, c (peg c 6))
368 $(a r.a, c (peg c 7))
369```
371#### Examples
373```
374 > =b (my [['a' 1] ['b' [2 3]] ~])
375 > (~(dig by b) 'b')
376 [~ u=2]
377```
379---
380### `+-gas:by`
382Concatenate
384Insert a list of key-value pairs `b` into map `a`.
386#### Accepts
388`a` is a map.
390`b` is a list of cells of key-value nouns `p` and `q`.
392#### Produces
394A map.
396#### Source
398```hoon
399 +- gas
400 ~/ %gas
401 |* b=(list [p=* q=*])
402 => .(b `(list _?>(?=(^ a) n.a))`b)
403 |- ^+ a
404 ?~ b
405 a
406 $(b t.b, a (put p.i.b q.i.b))
407```
409#### Examples
411```
412 > =a (my [['a' 1] ['b' 2] ~])
413 > =b [['c' 3] ['d' 4] ~]
415 > (~(gas by a) b)
416 [n=[p='b' q=2] l=[n=[p='d' q=4] l={} r={[p='a' q=1] [p='c' q=3]}] r=~]
417```
419---
420### `+-get:by`
422Grab unit value
424Produce the unit value of the value located at key `b` within map `a`.
426#### Accepts
428`a` is a map.
430`b` is a key as a noun.
432#### Produces
434A unit.
436#### Source
438```hoon
439 +- get
440 ~/ %get
441 |= b=*
442 ^- [$@(~ [~ u=_?>(?=(^ a) q.n.a)])]
443 =+ 42
444 ?~ a
445 ~
446 ?: =(b p.n.a)
447 [~ u=q.n.a]
448 ?: (gor b p.n.a)
449 $(a l.a)
450 $(a r.a)
451```
453#### Examples
455```
456 > =b (my [['a' 1] ['b' [2 3]] ~])
457 > (~(get by b) 'b')
458 [~ u=[2 3]]
461 > =m (my [['a' 1] ['b' 2] ~])
462 > (~(get by m) 'a')
463 [~ u=1]
464```
466---
467### `+-got:by`
469Assert
471Produce the value located at key `b` within map `a`. Crash if key `b` does not
472exist.
474#### Accepts
476`a` is a map.
478`b` is a key as a noun.
480#### Produces
482A noun.
484#### Source
486```hoon
487 +- got
488 |* b=*
489 (need (get b))
490```
492#### Examples
494```
495 > =m (my [['a' 1] ['b' 2] ~])
496 > m
497 [n=[p='b' q=2] l={[p='a' q=1]} r={}]
499 > (~(got by m) 'a')
500 1
502 > (~(got by m) 'c')
503 ! exit
504```
506---
507### `+-has:by`
509Key existence check
511Checks whether map `a` contains an element with key `b`, producing a flag.
513#### Accepts
515`a` is a map.
517`b` is a key as a noun.
519#### Produces
521A flag.
523#### Source
525```hoon
526 +- has
527 ~/ %has
528 |* b=*
529 !=(~ (get b))
530```
532#### Examples
534```
535 > =b (my [['a' 1] ['b' [2 3]] ~])
536 > (~(has by b) 'b')
537 %.y
539 > (~(has by b) 'c')
540 %.n
541```
543---
544### `+-int:by`
546Intersection
548Produces a map of the (key) intersection between two maps of the same type, `a`
549and `b`. If both maps have an identical key that point to different values, the
550element from map `b` is used.
552#### Accepts
554`a` is a map.
556`b` is a map.
558#### Produces
560A map.
562#### Source
564```hoon
565 +- int
566 ~/ %int
567 |* b=_a
568 |- ^+ a
569 ?~ b
570 ~
571 ?~ a
572 ~
573 ?: (vor p.n.a p.n.b)
574 ?: =(p.n.b p.n.a)
575 [n.b $(a l.a, b l.b) $(a r.a, b r.b)]
576 ?: (gor p.n.b p.n.a)
577 %- uni(a $(a l.a, b [n.b l.b ~])) $(b r.b)
578 %- uni(a $(a r.a, b [n.b ~ r.b])) $(b l.b)
579 ?: =(p.n.a p.n.b)
580 [n.b $(b l.b, a l.a) $(b r.b, a r.a)]
581 ?: (gor p.n.a p.n.b)
582 %- uni(a $(b l.b, a [n.a l.a ~])) $(a r.a)
583 %- uni(a $(b r.b, a [n.a ~ r.a])) $(a l.a)
584```
586#### Examples
588```
589 > =n (my [['a' 1] ['c' 3] ~])
590 > =m (my [['a' 1] ['b' 2] ~])
592 > (~(int by m) n)
593 [n=[p='a' q=1] l=~ r=~]
595 > =p (my [['a' 2] ['b' 2] ~])
596 > p
597 [n=[p='b' q=2] l={[p='a' q=2]} r={}]
598 > (~(int by p) n)
599 [n=[p='a' q=1] l=~ r=~]
601 > =q (my [['a' 2] ['c' 2] ~])
602 > q
603 [n=[p='c' q=2] l={[p='a' q=2]} r={}]
604 > (~(int by p) q)
605 [n=[p='a' q=2] l=~ r=~]
607 > =o (my [['c' 3] ['d' 4] ~])
608 > (~(int by m) o)
609 ~
610```
612---
614### `++ key:by`
616Set of keys
618Produces a set of all keys in map `a` that is prepended to set `b`,
619which is empty by default.
621#### Accepts
623`a` is a map.
625`b` is a set.
627#### Produces
629A set.
631#### Source
633```hoon
634++ key
635 =+ b=`(set _?>(?=(^ a) p.n.a))`~
636 |- ^+ b
637 ?~ a b
638 $(a r.a, b $(a l.a, b (~(put in b) p.n.a)))
639```
641#### Examples
643```
644 > =m (my [['a' 1] ['b' 2] ~])
645 [n=[p='b' q=2] l={[p='a' q=1]} r={}]
647 > ~(key by m)
648 {'b' 'a'}
649```
651---
653### `+-mar:by`
655Assert and add
657Produces map `a` with the addition of a key-value pair, where the value is a
658nonempty unit.
660Accept a noun and a unit of a noun of the type of the map's keys and values,
661respectively. Validate that the value is not null and put the pair in the map.
662If the value is null, delete the key.
664#### Accepts
666`a` is a map.
668`b` is a unit.
670#### Produces
672A map.
674#### Assert and Add
676```hoon
677 +- mar
678 |* [b=_?>(?=(^ a) p.n.a) c=(unit ,_?>(?=(^ a) q.n.a))]
679 ?~ c
680 (del b)
681 (put b u.c)
682```
684#### Examples
686```
687 > =m (my [['a' 1] ['b' 2] ~])
688 > (~(mar by m) 'c' (some 3))
689 [n=[p='b' q=2] l=[n=[p='c' q=3] l=[n=[p='a' q=1] l={} r={}] r=~] r=~]
691 > (~(mar by m) 'c' ~)
692 [n=[p='b' q=2] l=[n=[p='a' q=1] l=~ r=~] r=~]
694 > (~(mar by m) 'b' ~)
695 [n=[p='a' q=1] l=~ r=~]
696```
698---
699### `+-put:by`
701Add key-value pair
703Produces `a` with the addition of the key-value pair of `b` and `c`.
705#### Accepts
707`a` is a map.
709`b` is a key of the same type as the keys in `a`.
711`c` is a value of the same type of the values in `a`.
713#### Produces
715A map.
717#### Source
719```hoon
720 +- put
721 ~/ %put
722 |* [b=* c=*]
723 |- ^+ a
724 ?~ a
725 [[b c] ~ ~]
726 ?: =(b p.n.a)
727 ?: =(c q.n.a)
728 a
729 [[b c] l.a r.a]
730 ?: (gor b p.n.a)
731 =+ d=$(a l.a)
732 ?> ?=(^ d)
733 ?: (vor p.n.a p.n.d)
734 [n.a d r.a]
735 [n.d l.d [n.a r.d r.a]]
736 =+ d=$(a r.a)
737 ?> ?=(^ d)
738 ?: (vor p.n.a p.n.d)
739 [n.a l.a d]
740 [n.d [n.a l.a l.d] r.d]
741```
743#### Examples
745```
746 > =m (my [['a' 1] ['b' 2] ~])
747 > (~(put by ~) 'c' 3)
748 [n=[p='b' q=2] l=[n=[p='c' q=3] l={[p='a' q=1]} r={}] r=~]
750 > (~(put by m) "zod" 26)
751 ! nest-fail
752 ! exit
754 > (~(put by m) 'a' 2)
755 [n=[p='b' q=2] l=[n=[p='a' q=2] l={} r={}] r=~]
757 > (put:by m 'a' 2)
758 {[p=[[98 2] [[97 1] 0 0] 0] q=[97 2]]}
759```
761---
762### `+-rep:by`
764Replace by product
766Accumulate elements of map `a` using gate `b`, producing a noun.
768#### Accepts
770`a` is a map.
772`b` is a wet gate.
774#### Produces
776A noun.
778#### Source
780```hoon
781 +- rep
782 |* b=_|=([* *] +<+)
783 |-
784 ?~ a +<+.b
785 $(a r.a, +<+.b $(a l.a, +<+.b (b n.a +<+.b)))
786```
788#### Examples
790```
791 > =m (my [['a' 1] ['b' 2] ~])
792 > (~(rep by m) |=(a=(pair * *) p.a))
793 q=[97 1]
794```
796---
797### `+-rib:by`
799Replace values with accumulator
801#### Accepts
803`a` is a map.
805`b` is a noun.
807`c` is a wet gate.
809####
811A cell of nouns.
813#### Source
815```hoon
816 +- rib
817 |* [b=* c=gate]
818 |- ^+ [b a]
819 ?~ a [b ~]
820 =+ d=(c n.a b)
821 =. n.a +.d
822 =+ e=$(a l.a, b -.d)
823 =+ f=$(a r.a, b -.e)
824 [-.f [n.a +.e +.f]]
825```
827#### Examples
829```
830 > =m (my [['a' 1] ['b' 2] ~])
831 > (~(rib by m) [1 2] (con by m))
833 > (~(rep by m) [1 2] |=(a=(pair * *) p.a))
834```
836---
837### `+-run:by`
839Transform values
841Iterates over every value in map `a` using gate `b`, producing a map.
843#### Accepts
845`a` is a map.
847`b` is a wet gate.
849#### Produces
851A map.
853#### Source
855```hoon
856 +- run
857 |* b=gate
858 |-
859 ?~ a a
860 [n=[p=p.n.a q=(b q.n.a)] l=$(a l.a) r=$(a r.a)]
861```
863#### Examples
865```
866 > =m (my [['a' 1] ['b' 2] ~])
868 > ^+(m (~(run by m) dec))
869 [n=[p='b' q=1] l={[p='a' q=0]} r={}]
871 > `(map @tas @t)`(~(run by m) (cury scot %ux))
872 {[p=%a q='0x1'] [p=%b q='0x2']}
873```
875---
876### `+-rut:by`
878Transform nodes
880Applies a gate `b` to nodes in map `a`.
882#### Accepts
884`a` is a map.
886`b` is a wet gate.
888#### Produces
890A map.
892#### Source
894```hoon
895 +- rut
896 |* b=gate
897 |-
898 ?~ a a
899 [n=[p=p.n.a q=(b p.n.a q.n.a)] l=$(a l.a) r=$(a r.a)]
900```
902#### Examples
904```
905 > =m (my [['a' 1] ['b' 2] ~])
906```
908---
909### `+-tap:by`
911Listify pairs
913Produces the list of all elements in map `a` that is prepended to list `b`,
914which is empty by default.
916#### Accepts
918`a` is a map.
920`b` is a list.
922#### Produces
924A list.
926#### Source
928```hoon
929 +- tap
930 =< $
931 ~/ %tap
932 =| b=(list _?>(?=(^ a) n.a))
933 |. ^+ b
934 ?~ a
935 b
936 $(a r.a, b [n.a $(a l.a)])
937```
939#### Examples
941```
942 > =m (my [['a' 1] ['b' 2] ~])
943 [n=[p='b' q=2] l={[p='a' q=1]} r={}]
944 > `*`m
945 [[98 2] [[97 1] 0 0] 0]
947 > ~(tap by m)
948 ~[[p='b' q=2] [p='a' q=1]]
949 > `*`~(tap by m)
950 [[98 2] [97 1] 0]
951```
953---
954### `+-uni:by`
956Union
958Produces a map of the union between the keys of `a` and `b`. If `b` shares a
959key with `a`, the tuple from `b` is preserved.
961#### Accepts
963`a` is a map.
965`b` is a map.
967#### Produces
969A map.
971#### Source
973```hoon
974 +- uni
975 ~/ %uni
976 |* b=_a
977 |- ^+ a
978 ?~ b
979 a
980 ?~ a
981 b
982 ?: (vor p.n.a p.n.b)
983 ?: =(p.n.b p.n.a)
984 [n.b $(a l.a, b l.b) $(a r.a, b r.b)]
985 ?: (gor p.n.b p.n.a)
986 $(a [n.a $(a l.a, b [n.b l.b ~]) r.a], b r.b)
987 $(a [n.a l.a $(a r.a, b [n.b ~ r.b])], b l.b)
988 ?: =(p.n.a p.n.b)
989 [n.b $(b l.b, a l.a) $(b r.b, a r.a)]
990 ?: (gor p.n.a p.n.b)
991 $(b [n.b $(b l.b, a [n.a l.a ~]) r.b], a r.a)
992 $(b [n.b l.b $(b r.b, a [n.a ~ r.a])], a l.a)
993```
995#### Examples
997```
998 > =m (my [['a' 1] ['b' 2] ~])
1000 > =o (my [['c' 3] ['d' 4] ~])
1002 > (~(uni by m) o)
1003 [n=[p='b' q=2] l=[n=[p='d' q=4] l={} r={[p='a' q=1] [p='c' q=3]}] r=~]
1005 > (~(uni by m) ~)
1006 {[p='a' q=1] [p='b' q=2]}
1008 > n
1009 {[p='a' q=1] [p='c' q=3]}
1010 > (~(uni by o) n)
1011 {[p='d' q=4] [p='a' q=1] [p='c' q=3]}
1012```
1014---
1015### `+-urn:by`
1017Turn (with key)
1019Iterates over every value in map `a` using gate `b`, which accepts both
1020the key and the value of each element as its sample.
1022#### Accepts
1024`a` is a map.
1026`b` is a wet gate that accepts two nouns.
1028#### Produces
1030A noun.
1032#### Source
1034```hoon
1035 +- urn
1036 |* b=$-({* *} *)
1037 |-
1038 ?~ a ~
1039 [n=[p=p.n.a q=(b p.n.a q.n.a)] l=$(a l.a) r=$(a r.a)
1040```
1042#### Examples
1044```
1045 > m
1046 {[p='a' q=1] [p='b' q=2]}
1048 > (~(urn by m) |=(a=(pair * *) q.a))
1049 {[p='a' q=1] [p='b' q=2]}
1051 > (~(urn by m) |=(a=(pair * *) 7))
1052 {[p='a' q=7] [p='b' q=7]}
1054 > (~(urn by m) |=(a=(pair * *) p.a))
1055 {[p='a' q=97] [p='b' q=98]}
1056```
1058---
1060### `+-wyt:by`
1062Depth
1064Produce the depth of the tree map `a`.
1066#### Accepts
1068`a` is a map.
1070#### Produces
1072An atom.
1074#### Source
1076```hoon
1077 +- wyt
1078 |- ^- @
1079 ?~(a 0 +((add $(a l.a) $(a r.a))))
1080```
1082#### Examples
1084```
1085 > =m (my [['a' 1] ['b' 2] ~])
1087 > =o (my [['c' 3] ['d' 4] ~])
1089 > ~(wyt by m)
1092 > ~(wyt by o)
1095 > ~(wyt by (~(uni by m) o))
1097```
1099---
1101### `++ val:by`
1103List of values
1105Produces a list of all values in map `a` that is prepended to list `b`,
1106which is empty by default.
1108#### Accepts
1110`a` is a map.
1112`b` is a list.
1114#### Produces
1116A list.
1118#### Source
1120```hoon
1121++ val
1122 =+ b=`(list _?>(?=(^ a) q.n.a))`~
1123 |- ^+ b
1124 ?~ a b
1125 $(a r.a, b [q.n.a $(a l.a)])
1126```
1128#### Examples
1130```
1131 > =m (my [['a' 1] ['b' 2] ~])
1132 [n=[p='b' q=2] l={[p='a' q=1]} r={}]
1134 > ~(val by m)
1135 ~[1 2]
1136```
1138---