on b00decd help sign in
1133 lines 17 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 :: logical AND
66 ~/ %all
67 |* b=$-(* ?)
68 |- ^- ?
69 ?~ a
70 &
71 ?&((b 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 :: logical OR
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 :: check correctness
151 =< $
152 ~/ %apt
153 =| [l=(unit) r=(unit)]
154 |. ^- ?
155 ?~ a &
156 ?& ?~(l & &((gor p.n.a u.l) !=(p.n.a u.l)))
157 ?~(r & &((gor u.r p.n.a) !=(u.r p.n.a)))
158 ?~ l.a &
159 &((mor p.n.a p.n.l.a) !=(p.n.a p.n.l.a) $(a l.a, l `p.n.a))
160 ?~ r.a &
161 &((mor p.n.a p.n.r.a) !=(p.n.a p.n.r.a) $(a r.a, r `p.n.a))
162 ==
163```
165#### Examples
167```
168 > =a (my [['a' 1] ['b' [2 3]] ~])
169 > ~(apt by a)
170 %.y
172 > =s (my [[1 2] [3 4] ~])
173 > =z ?~ s ~ s(p.n 10)
174 > z
175 [n=[p=10 q=2] l={} r={[p=3 q=4]}]
177 > ~(apt by z)
178 %.n
179```
181#### Discussion
183See section [`2f`](/docs/hoon/reference/stdlib/2f) for more information on noun ordering.
185### `++bif:by`
187Bifurcate
189Splits map `a` into two maps `l` and `r`, with the head at `b` discarded.
191#### Accepts
193`a` is a map.
195`b` is a noun.
197`c` is a noun.
199#### Produces
201A cell of two maps.
203#### Source
205```hoon
206 ++ bif :: splits a by b
207 ~/ %bif
208 |* [b=* c=*]
209 ^+ [l=a r=a]
210 =< +
211 |- ^+ a
212 ?~ a
213 [[b c] ~ ~]
214 ?: =(b p.n.a)
215 ?: =(c q.n.a)
216 a
217 a(n [b c])
218 ?: (gor b p.n.a)
219 =+ d=$(a l.a)
220 ?> ?=(^ d)
221 d(r a(l r.d))
222 =+ d=$(a r.a)
223 ?> ?=(^ d)
224 d(l a(r l.d))
225```
227#### Examples
229```
230 > =a (my [['a' 1] ['b' 2] ['c' 3] ~])
232 > (~(bif by a) ['b' 2])
233 [l=[n=[p='c' q=3] l=[n=[p='a' q=1] l={} r={}] r=~] r=~]
234```
237---
238### `++del:by`
240Delete
242Produces map `a` with the element located at key `b` removed.
244#### Accepts
246`a` is a map.
248`b` is a key as a noun.
250#### Produces
252A map.
254#### Source
256```hoon
257 ++ del :: delete at key b
258 ~/ %del
259 |* b=*
260 |- ^+ a
261 ?~ a
262 ~
263 ?. =(b p.n.a)
264 ?: (gor b p.n.a)
265 a(l $(a l.a))
266 a(r $(a r.a))
267 |- ^- [$?(~ _a)]
268 ?~ l.a r.a
269 ?~ r.a l.a
270 ?: (mor p.n.l.a p.n.r.a)
271 l.a(r $(l.a r.l.a))
272 r.a(l $(r.a l.r.a))
273```
275#### Examples
277```
278 > =b (my [['a' 1] ['b' [2 3]] ~])
279 > (~(del by b) 'a')
280 [n=[p='b' q=[2 3]] l=~ r=~]
281```
283---
284### `++dig:by`
286Address of key
288Produce the address of key `b` within map `a`.
290#### Accepts
292`a` is a map.
294`b` is a key as a noun.
296#### Produces
298A unit.
300#### Source
302```hoon
303 ++ dig :: axis of b key
304 |= b=*
305 =+ c=1
306 |- ^- (unit @)
307 ?~ a ~
308 ?: =(b p.n.a) [~ u=(peg c 2)]
309 ?: (gor b p.n.a)
310 $(a l.a, c (peg c 6))
311 $(a r.a, c (peg c 7))
312```
314#### Examples
316```
317 > =b (my [['a' 1] ['b' [2 3]] ~])
318 > (~(dig by b) 'b')
319 [~ u=2]
320```
322---
323### `++gas:by`
325Concatenate
327Insert a list of key-value pairs `b` into map `a`.
329#### Accepts
331`a` is a map.
333`b` is a list of cells of key-value nouns `p` and `q`.
335#### Produces
337A map.
339#### Source
341```hoon
342 ++ gas :: concatenate
343 ~/ %gas
344 |* b=(list [p=* q=*])
345 => .(b `(list _?>(?=(^ a) n.a))`b)
346 |- ^+ a
347 ?~ b
348 a
349 $(b t.b, a (put p.i.b q.i.b))
350```
352#### Examples
354```
355 > =a (my [['a' 1] ['b' 2] ~])
356 > =b [['c' 3] ['d' 4] ~]
358 > (~(gas by a) b)
359 [n=[p='b' q=2] l=[n=[p='d' q=4] l={} r={[p='a' q=1] [p='c' q=3]}] r=~]
360```
362---
363### `++get:by`
365Grab unit value
367Produce the unit value of the value located at key `b` within map `a`.
369#### Accepts
371`a` is a map.
373`b` is a key as a noun.
375#### Produces
377A unit.
379#### Source
381```hoon
382 ++ get :: grab value by key
383 ~/ %get
384 |* b=*
385 => .(b `_?>(?=(^ a) p.n.a)`b)
386 |- ^- (unit _?>(?=(^ a) q.n.a))
387 ?~ a
388 ~
389 ?: =(b p.n.a)
390 (some q.n.a)
391 ?: (gor b p.n.a)
392 $(a l.a)
393 $(a r.a)
394```
396#### Examples
398```
399 > =b (my [['a' 1] ['b' [2 3]] ~])
400 > (~(get by b) 'b')
401 [~ u=[2 3]]
404 > =m (my [['a' 1] ['b' 2] ~])
405 > (~(get by m) 'a')
406 [~ u=1]
407```
409---
410### `++got:by`
412Assert
414Produce the value located at key `b` within map `a`. Crash if key `b` does not
415exist.
417#### Accepts
419`a` is a map.
421`b` is a key as a noun.
423#### Produces
425A noun.
427#### Source
429```hoon
430 ++ got :: need value by key
431 |* b=*
432 (need (get b))
433```
435#### Examples
437```
438 > =m (my [['a' 1] ['b' 2] ~])
439 > m
440 [n=[p='b' q=2] l={[p='a' q=1]} r={}]
442 > (~(got by m) 'a')
443 1
445 > (~(got by m) 'c')
446 ! exit
447```
449---
450### `++gut:by`
452Grab value with default
454Produce the value located at key `b` within map `a`. Use default value `c` if
455key does not exist.
457#### Accepts
459`a` is a map.
461`b` is a key as a noun.
463`c` is a noun.
465#### Produces
467A noun.
469#### Source
471```hoon
472 ++ gut :: fall value by key
473 |* [b=* c=*]
474 (fall (get b) c)
476```
478#### Examples
480```
481 > =m (my [['a' 1] ['b' 2] ~])
482 > m
483 [n=[p='b' q=2] l={[p='a' q=1]} r={}]
485 > (~(gut by m) 'a' 0)
486 1
488 > (~(gut by m) 'c' 0)
489 0
490```
492---
493### `++has:by`
495Key existence check
497Checks whether map `a` contains an element with key `b`, producing a flag.
499#### Accepts
501`a` is a map.
503`b` is a key as a noun.
505#### Produces
507A flag.
509#### Source
511```hoon
512 ++ has :: key existence check
513 ~/ %has
514 |* b=*
515 !=(~ (get b))
516```
518#### Examples
520```
521 > =b (my [['a' 1] ['b' [2 3]] ~])
522 > (~(has by b) 'b')
523 %.y
525 > (~(has by b) 'c')
526 %.n
527```
529---
530### `++int:by`
532Intersection
534Produces a map of the (key) intersection between two maps of the same type, `a`
535and `b`. If both maps have an identical key that point to different values, the
536element from map `b` is used.
538#### Accepts
540`a` is a map.
542`b` is a map.
544#### Produces
546A map.
548#### Source
550```hoon
551 ++ int :: intersection
552 ~/ %int
553 =+ b=a
554 |@
555 ++ $
556 |- ^+ a
557 ?~ b
558 ~
559 ?~ a
560 ~
561 ?: (mor p.n.a p.n.b)
562 ?: =(p.n.b p.n.a)
563 b(l $(a l.a, b l.b), r $(a r.a, b r.b))
564 ?: (gor p.n.b p.n.a)
565 %- uni(a $(a l.a, r.b ~)) $(b r.b)
566 %- uni(a $(a r.a, l.b ~)) $(b l.b)
567 ?: =(p.n.a p.n.b)
568 b(l $(b l.b, a l.a), r $(b r.b, a r.a))
569 ?: (gor p.n.a p.n.b)
570 %- uni(a $(b l.b, r.a ~)) $(a r.a)
571 %- uni(a $(b r.b, l.a ~)) $(a l.a)
572 --
573```
575#### Examples
577```
578 > =n (my [['a' 1] ['c' 3] ~])
579 > =m (my [['a' 1] ['b' 2] ~])
581 > (~(int by m) n)
582 [n=[p='a' q=1] l=~ r=~]
584 > =p (my [['a' 2] ['b' 2] ~])
585 > p
586 [n=[p='b' q=2] l={[p='a' q=2]} r={}]
587 > (~(int by p) n)
588 [n=[p='a' q=1] l=~ r=~]
590 > =q (my [['a' 2] ['c' 2] ~])
591 > q
592 [n=[p='c' q=2] l={[p='a' q=2]} r={}]
593 > (~(int by p) q)
594 [n=[p='a' q=2] l=~ r=~]
596 > =o (my [['c' 3] ['d' 4] ~])
597 > (~(int by m) o)
598 ~
599```
601---
603### `++key:by`
605Set of keys
607Produces a set of all keys in map `a` that is prepended to set `b`,
608which is empty by default.
610#### Accepts
612`a` is a map.
614`b` is a set.
616#### Produces
618A set.
620#### Source
622```hoon
623++ key
624 =+ b=`(set _?>(?=(^ a) p.n.a))`~
625 |- ^+ b
626 ?~ a b
627 $(a r.a, b $(a l.a, b (~(put in b) p.n.a)))
628```
630#### Examples
632```
633 > =m (my [['a' 1] ['b' 2] ~])
634 [n=[p='b' q=2] l={[p='a' q=1]} r={}]
636 > ~(key by m)
637 {'b' 'a'}
638```
640---
642### `++mar:by`
644Assert and add
646Produces map `a` with the addition of a key-value pair, where the value is a
647nonempty unit.
649Accept a noun and a unit of a noun of the type of the map's keys and values,
650respectively. Validate that the value is not null and put the pair in the map.
651If the value is null, delete the key.
653#### Accepts
655`a` is a map.
657`b` is a unit.
659#### Produces
661A map.
663#### Assert and Add
665```hoon
666 ++ mar :: add with validation
667 |* [b=* c=(unit *)]
668 ?~ c
669 (del b)
670 (put b u.c)
671```
673#### Examples
675```
676 > =m (my [['a' 1] ['b' 2] ~])
677 > (~(mar by m) 'c' (some 3))
678 [n=[p='b' q=2] l=[n=[p='c' q=3] l=[n=[p='a' q=1] l={} r={}] r=~] r=~]
680 > (~(mar by m) 'c' ~)
681 [n=[p='b' q=2] l=[n=[p='a' q=1] l=~ r=~] r=~]
683 > (~(mar by m) 'b' ~)
684 [n=[p='a' q=1] l=~ r=~]
685```
687---
688### `++put:by`
690Add key-value pair
692Produces `a` with the addition of the key-value pair of `b` and `c`.
694#### Accepts
696`a` is a map.
698`b` is a key of the same type as the keys in `a`.
700`c` is a value of the same type of the values in `a`.
702#### Produces
704A map.
706#### Source
708```hoon
709 ++ put :: adds key-value pair
710 ~/ %put
711 |* [b=* c=*]
712 |- ^+ a
713 ?~ a
714 [[b c] ~ ~]
715 ?: =(b p.n.a)
716 ?: =(c q.n.a)
717 a
718 a(n [b c])
719 ?: (gor b p.n.a)
720 =+ d=$(a l.a)
721 ?> ?=(^ d)
722 ?: (mor p.n.a p.n.d)
723 a(l d)
724 d(r a(l r.d))
725 =+ d=$(a r.a)
726 ?> ?=(^ d)
727 ?: (mor p.n.a p.n.d)
728 a(r d)
729 d(l a(r l.d))
730```
732#### Examples
734```
735 > =m (my [['a' 1] ['b' 2] ~])
736 > (~(put by ~) 'c' 3)
737 [n=[p='b' q=2] l=[n=[p='c' q=3] l={[p='a' q=1]} r={}] r=~]
739 > (~(put by m) "zod" 26)
740 ! nest-fail
741 ! exit
743 > (~(put by m) 'a' 2)
744 [n=[p='b' q=2] l=[n=[p='a' q=2] l={} r={}] r=~]
746 > (put:by m 'a' 2)
747 {[p=[[98 2] [[97 1] 0 0] 0] q=[97 2]]}
748```
750---
751### `++rep:by`
753Replace by product
755Accumulate elements of map `a` using gate `b`, producing a noun.
757#### Accepts
759`a` is a map.
761`b` is a wet gate.
763#### Produces
765A noun.
767#### Source
769```hoon
770 ++ rep :: reduce to product
771 ~/ %rep
772 |* b=_=>(~ |=([* *] +<+))
773 |-
774 ?~ a +<+.b
775 $(a r.a, +<+.b $(a l.a, +<+.b (b n.a +<+.b)))
776```
778#### Examples
780```
781 > =m (my [['a' 1] ['b' 2] ~])
782 > (~(rep by m) |=(a=(pair * *) p.a))
783 q=[97 1]
784```
786---
787### `++rib:by`
789Replace values with accumulator
791#### Accepts
793`a` is a map.
795`b` is a noun.
797`c` is a wet gate.
799####
801A cell of nouns.
803#### Source
805```hoon
806 ++ rib :: transform + product
807 |* [b=* c=gate]
808 |- ^+ [b a]
809 ?~ a [b ~]
810 =+ d=(c n.a b)
811 =. n.a +.d
812 =+ e=$(a l.a, b -.d)
813 =+ f=$(a r.a, b -.e)
814 [-.f a(l +.e, r +.f)]
815```
817#### Examples
819```
820 > =m (my [['a' 1] ['b' 2] ~])
821 > (~(rib by m) [1 2] (con by m))
823 > (~(rep by m) [1 2] |=(a=(pair * *) p.a))
824```
826---
827### `++run:by`
829Transform values
831Iterates over every value in map `a` using gate `b`, producing a map.
833#### Accepts
835`a` is a map.
837`b` is a wet gate.
839#### Produces
841A map.
843#### Source
845```hoon
846 ++ run :: apply gate to values
847 ~/ %run
848 |* b=gate
849 |-
850 ?~ a a
851 [n=[p=p.n.a q=(b q.n.a)] l=$(a l.a) r=$(a r.a)]
852```
854#### Examples
856```
857 > =m (my [['a' 1] ['b' 2] ~])
859 > ^+(m (~(run by m) dec))
860 [n=[p='b' q=1] l={[p='a' q=0]} r={}]
862 > `(map @tas @t)`(~(run by m) (cury scot %ux))
863 {[p=%a q='0x1'] [p=%b q='0x2']}
864```
866---
867### `++rut:by`
869Transform nodes
871Applies a gate `b` to nodes in map `a`.
873#### Accepts
875`a` is a map.
877`b` is a wet gate.
879#### Produces
881A map.
883#### Source
885```hoon
886 ++ rut :: apply gate to nodes
887 |* b=gate
888 |-
889 ?~ a a
890 [n=[p=p.n.a q=(b p.n.a q.n.a)] l=$(a l.a) r=$(a r.a)]
891```
893#### Examples
895```
896 > =m (my [['a' 1] ['b' 2] ~])
897```
899---
900### `++tap:by`
902Listify pairs
904Produces the list of all elements in map `a` that is prepended to list `b`,
905which is empty by default.
907#### Accepts
909`a` is a map.
911`b` is a list.
913#### Produces
915A list.
917#### Source
919```hoon
920 ++ tap :: listify pairs
921 =< $
922 ~/ %tap
923 =+ b=`(list _?>(?=(^ a) n.a))`~
924 |. ^+ b
925 ?~ a
926 b
927 $(a r.a, b [n.a $(a l.a)])
928```
930#### Examples
932```
933 > =m (my [['a' 1] ['b' 2] ~])
934 [n=[p='b' q=2] l={[p='a' q=1]} r={}]
935 > `*`m
936 [[98 2] [[97 1] 0 0] 0]
938 > ~(tap by m)
939 ~[[p='b' q=2] [p='a' q=1]]
940 > `*`~(tap by m)
941 [[98 2] [97 1] 0]
942```
944---
945### `++uni:by`
947Union
949Produces a map of the union between the keys of `a` and `b`. If `b` shares a
950key with `a`, the tuple from `b` is preserved.
952#### Accepts
954`a` is a map.
956`b` is a map.
958#### Produces
960A map.
962#### Source
964```hoon
965 ++ uni :: union, merge
966 ~/ %uni
967 =+ b=a
968 |@
969 ++ $
970 |- ^+ a
971 ?~ b
972 a
973 ?~ a
974 b
975 ?: =(p.n.b p.n.a)
976 b(l $(a l.a, b l.b), r $(a r.a, b r.b))
977 ?: (mor p.n.a p.n.b)
978 ?: (gor p.n.b p.n.a)
979 $(l.a $(a l.a, r.b ~), b r.b)
980 $(r.a $(a r.a, l.b ~), b l.b)
981 ?: (gor p.n.a p.n.b)
982 $(l.b $(b l.b, r.a ~), a r.a)
983 $(r.b $(b r.b, l.a ~), a l.a)
984 --
985```
987#### Examples
989```
990 > =m (my [['a' 1] ['b' 2] ~])
992 > =o (my [['c' 3] ['d' 4] ~])
994 > (~(uni by m) o)
995 [n=[p='b' q=2] l=[n=[p='d' q=4] l={} r={[p='a' q=1] [p='c' q=3]}] r=~]
997 > (~(uni by m) ~)
998 {[p='a' q=1] [p='b' q=2]}
1000 > n
1001 {[p='a' q=1] [p='c' q=3]}
1002 > (~(uni by o) n)
1003 {[p='d' q=4] [p='a' q=1] [p='c' q=3]}
1004```
1006---
1007### `++urn:by`
1009Turn (with key)
1011Iterates over every value in map `a` using gate `b`, which accepts both
1012the key and the value of each element as its sample.
1014#### Accepts
1016`a` is a map.
1018`b` is a wet gate that accepts two nouns.
1020#### Produces
1022A noun.
1024#### Source
1026```hoon
1027 ++ urn :: apply gate to nodes
1028 ~/ %urn
1029 |* b=$-([* *] *)
1030 |-
1031 ?~ a ~
1032 a(n n.a(q (b p.n.a q.n.a)), l $(a l.a), r $(a r.a))
1033```
1035#### Examples
1037```
1038 > m
1039 {[p='a' q=1] [p='b' q=2]}
1041 > (~(urn by m) |=(a=(pair * *) q.a))
1042 {[p='a' q=1] [p='b' q=2]}
1044 > (~(urn by m) |=(a=(pair * *) 7))
1045 {[p='a' q=7] [p='b' q=7]}
1047 > (~(urn by m) |=(a=(pair * *) p.a))
1048 {[p='a' q=97] [p='b' q=98]}
1049```
1051---
1053### `++wyt:by`
1055Depth
1057Produce the depth of the tree map `a`.
1059#### Accepts
1061`a` is a map.
1063#### Produces
1065An atom.
1067#### Source
1069```hoon
1070 ++ wyt :: depth of map
1071 =< $
1072 ~% %wyt + ~
1073 |. ^- @
1074 ?~(a 0 +((add $(a l.a) $(a r.a))))
1075```
1077#### Examples
1079```
1080 > =m (my [['a' 1] ['b' 2] ~])
1082 > =o (my [['c' 3] ['d' 4] ~])
1084 > ~(wyt by m)
1087 > ~(wyt by o)
1090 > ~(wyt by (~(uni by m) o))
1092```
1094---
1096### `++val:by`
1098List of values
1100Produces a list of all values in map `a` that is prepended to list `b`,
1101which is empty by default.
1103#### Accepts
1105`a` is a map.
1107`b` is a list.
1109#### Produces
1111A list.
1113#### Source
1115```hoon
1116++ val
1117 =+ b=`(list _?>(?=(^ a) q.n.a))`~
1118 |- ^+ b
1119 ?~ a b
1120 $(a r.a, b [q.n.a $(a l.a)])
1121```
1123#### Examples
1125```
1126 > =m (my [['a' 1] ['b' 2] ~])
1127 [n=[p='b' q=2] l={[p='a' q=1]} r={}]
1129 > ~(val by m)
1130 ~[1 2]
1131```
1133---