git.iko.soy/urbit.org
on 883cb21 help sign in
urbit.org/content/docs/hoon/reference/stdlib/2i.md
1417 lines 22 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)) :: (map)
24 =* node ?>(?=(^ a) n.a)
25 |@
26```
28#### Examples
30```
31> ~(. by (malt (limo ~[a+1 b+2 c+3])))
32< 27.jus
33 [ a
34 ?(
35 %~
36 [ n=[?(p=%a p=%b p=%c) q=@ud]
37 l=nlr([p=?(%a %b %c) q=@ud])
38 r=nlr([p=?(%a %b %c) q=@ud])
39 ]
40 )
41 <123.zao 46.hgz 1.pnw %140>
42 ]
44```
46---
48### `++all:by`
50Logical AND
52Computes the logical AND on the results of slamming every element in map `a`
53with gate `b`.
55#### Accepts
57`a` is a map, and is the sample of `+by`.
59`b` is a gate.
61#### Produces
63A flag.
65#### Source
67```hoon
68++ all
69 ~/ %all
70 |* b=$-(* ?)
71 |- ^- ?
72 ?~ a
73 &
74 ?&((b q.n.a) $(a l.a) $(a r.a))
75```
77#### Examples
79```
80> =a (malt (limo ~[a+1 b+[2 3]]))
82> (~(all by a) |=(a=* ?@(a & |)))
83%.n
84```
86```
87> =a (malt (limo ~[a+1 b+2 c+3 d+4 e+5]))
89> (~(all by a) |=(a=@ (lte a 6)))
90%.y
92> (~(all by a) |=(a=@ (lte a 4)))
93%.n
94```
96---
98### `++any:by`
100Logical OR
102Computes the logical OR on the results of slamming every element with
103gate `b`.
105#### Accepts
107`a` is a map, and is the sample of `+by`.
109`b` is a wet gate.
111#### Produces
113A flag.
115#### Source
117```hoon
118++ any
119 ~/ %any
120 |* b=$-(* ?)
121 |- ^- ?
122 ?~ a
123 |
124 ?|((b q.n.a) $(a l.a) $(a r.a))
125```
127#### Examples
129```
130> =a (malt (limo ~[a+1 b+[2 3]]))
132> (~(any by a) |=(a=* ?@(a & |)))
133%.y
134```
136```
137> =a (malt (limo ~[a+1 b+2 c+3 d+4 e+5]))
139> (~(any by a) |=(a=@ (lte a 4)))
140%.y
141```
143---
145### `++apt:by`
147Check correctness
149Computes whether `a` has a correct horizontal order and a correct vertical
150order, producing a flag.
152#### Accepts
154`a` is a map.
156#### Produces
158A flag.
160#### Source
162```hoon
163++ apt
164 =< $
165 ~/ %apt
166 =| [l=(unit) r=(unit)]
167 |. ^- ?
168 ?~ a &
169 ?& ?~(l & &((gor p.n.a u.l) !=(p.n.a u.l)))
170 ?~(r & &((gor u.r p.n.a) !=(u.r p.n.a)))
171 ?~ l.a &
172 &((mor p.n.a p.n.l.a) !=(p.n.a p.n.l.a) $(a l.a, l `p.n.a))
173 ?~ r.a &
174 &((mor p.n.a p.n.r.a) !=(p.n.a p.n.r.a) $(a r.a, r `p.n.a))
175 ==
176```
178#### Examples
180```
181> =a (malt `(list [@tas @])`~[a+1 b+2 c+3 d+4 e+5])
183> ~(apt by a)
184%.y
186> =z ?~(a ~ a(p.n `@tas`%z))
188> z
189[n=[p=%z q=2] l={[p=%e q=5]} r={[p=%d q=4] [p=%a q=1] [p=%c q=3]}]
191> ~(apt by z)
192%.n
193```
195#### Discussion
197See section [`2f`](/docs/hoon/reference/stdlib/2f) for more information on noun ordering.
199### `++bif:by`
201Bifurcate
203Splits map `a` into two maps `l` and `r`, which contain the items either side of key `b` with value `c` but not including `b`-`c`.
205#### Accepts
207`a` is a map, and is the sample of `+by`.
209`b` is a noun.
211`c` is a noun.
213#### Produces
215A cell of two maps.
217#### Source
219```hoon
220++ bif
221 ~/ %bif
222 |* [b=* c=*]
223 ^+ [l=a r=a]
224 =< +
225 |- ^+ a
226 ?~ a
227 [[b c] ~ ~]
228 ?: =(b p.n.a)
229 ?: =(c q.n.a)
230 a
231 a(n [b c])
232 ?: (gor b p.n.a)
233 =+ d=$(a l.a)
234 ?> ?=(^ d)
235 d(r a(l r.d))
236 =+ d=$(a r.a)
237 ?> ?=(^ d)
238 d(l a(r l.d))
239```
241#### Examples
243```
244> =a (malt `(list [@tas @])`~[a+1 b+2 c+3 d+4 e+5])
246> (~(bif by a) b+2)
247[l=[n=[p=%e q=5] l=~ r=~] r=[n=[p=%d q=4] l=~ r=[n=[p=%c q=3] l={[p=%a q=1]} r={}]]]
249> `[(map @tas @) (map @tas @)]`(~(bif by a) b+2)
250[{[p=%e q=5]} {[p=%d q=4] [p=%a q=1] [p=%c q=3]}]
251```
253#### Discussion
255Note that `map`s are horizontally ordered by the [mug](/docs/hoon/reference/stdlib/2e#mug) hash of their keys and vertically ordered by the double-`mug` hash of their keys. This means bifurcating the map `(malt ~[10^10 20^20 30^30 40^40 50^50])` at `30^30` will not produce `[{10^10 20^20} {40^40 50^50}]`, but rather `[{20^20} {10^10 40^40 50^50}]` due to the tree structure resulting from their `mug` hashes.
257---
259### `++del:by`
261Delete
263Produces map `a` with the element located at key `b` removed.
265#### Accepts
267`a` is a map, and is the sample of `+by`.
269`b` is a key as a noun.
271#### Produces
273A map.
275#### Source
277```hoon
278++ del
279 ~/ %del
280 |* b=*
281 |- ^+ a
282 ?~ a
283 ~
284 ?. =(b p.n.a)
285 ?: (gor b p.n.a)
286 a(l $(a l.a))
287 a(r $(a r.a))
288 |- ^- [$?(~ _a)]
289 ?~ l.a r.a
290 ?~ r.a l.a
291 ?: (mor p.n.l.a p.n.r.a)
292 l.a(r $(l.a r.l.a))
293 r.a(l $(r.a l.r.a))
294```
296#### Examples
298```
299> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
300> a
301{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
303> `(map @tas @)`(~(del by a) %z)
304{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
306> `(map @tas @)`(~(del by a) %b)
307{[p=%d q=4] [p=%a q=1] [p=%c q=3]}
308```
310---
312### `++dif:by`
314Difference
316Computes the difference between `a` and `b`, producing the map of key-value pairs in `a` whose keys are not in `b`.
318#### Accepts
320`a` is a `map`, and is the sample of `+by`.
322`b` is a `map`.
324#### Produces
326A `map`.
328#### Source
330```hoon
331++ dif
332 ~/ %dif
333 =+ b=a
334 |@
335 ++ $
336 |- ^+ a
337 ?~ b
338 a
339 =+ c=(bif p.n.b q.n.b)
340 ?> ?=(^ c)
341 =+ d=$(a l.c, b l.b)
342 =+ e=$(a r.c, b r.b)
343 |- ^- [$?(~ _a)]
344 ?~ d e
345 ?~ e d
346 ?: (mor p.n.d p.n.e)
347 d(r $(d r.d))
348 e(l $(e l.e))
349 --
350```
352#### Examples
354```
355> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
356> =b `(map @tas @)`(malt (limo ~[c+3 d+4 e+5 f+6]))
357> a
358{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
359> b
360{[p=%e q=5] [p=%d q=4] [p=%f q=6] [p=%c q=3]}
362> `(map @tas @)`(~(dif by a) b)
363{[p=%b q=2] [p=%a q=1]}
364```
366```
367> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
368> =b `(map @tas @)`(malt (limo ~[a+2 e+4 f+5]))
369> a
370{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
371> b
372{[p=%e q=4] [p=%f q=5] [p=%a q=2]}
374> `(map @tas @)`(~(dif by a) b)
375{[p=%b q=2] [p=%d q=4] [p=%c q=3]}
376```
378#### Discussion
380This only compares keys, so if both maps contain the same key with different values, that key-value pair is not considered a difference and will not be included in the resulting map.
382---
384### `++dig:by`
386Address of key
388Produce the address of key `b` within map `a`.
390#### Accepts
392`a` is a map, and is the sample of `+by`.
394`b` is a key as a noun.
396#### Produces
398A unit.
400#### Source
402```hoon
403++ dig
404 |= b=*
405 =+ c=1
406 |- ^- (unit @)
407 ?~ a ~
408 ?: =(b p.n.a) [~ u=(peg c 2)]
409 ?: (gor b p.n.a)
410 $(a l.a, c (peg c 6))
411 $(a r.a, c (peg c 7))
412```
414#### Examples
416```
417> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
419> (~(dig by a) %a)
420[~ 252]
422> (~(dig by a) %b)
423[~ 2]
425> (~(dig by a) %e)
427```
429---
431### `++gas:by`
433Concatenate
435Insert a list of key-value pairs `b` into map `a`. For a key which exists in both `a` and `b`, the value is replaced with the value in `b`.
437#### Accepts
439`a` is a map, and is the sample of `+by`.
441`b` is a list of cells of key-value nouns `p` and `q`.
443#### Produces
445A map.
447#### Source
449```hoon
450++ gas
451 ~/ %gas
452 |* b=(list [p=* q=*])
453 => .(b `(list _?>(?=(^ a) n.a))`b)
454 |- ^+ a
455 ?~ b
456 a
457 $(b t.b, a (put p.i.b q.i.b))
458```
460#### Examples
462```
463> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
464> a
465{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
467> `(map @tas @)`(~(gas by a) ~[e+5 f+6 g+7])
468{[p=%e q=5] [p=%b q=2] [p=%d q=4] [p=%f q=6] [p=%g q=7] [p=%a q=1] [p=%c q=3]}
469```
471```
472> =a `(map @tas @)`(malt (limo ~[a+1 b+2]))
473> a
474{[p=%b q=2] [p=%a q=1]}
476> `(map @tas @)`(~(gas by a) ~[a+100 b+200])
477{[p=%b q=200] [p=%a q=100]}
478```
480```
481> `(map @tas @)`(~(gas by `(map @tas @)`~) ~[a+100 b+200])
482{[p=%b q=200] [p=%a q=100]}
483```
485---
487### `++get:by`
489Grab unit value
491Produce the unit value of the value located at key `b` within map `a`.
493#### Accepts
495`a` is a map, and is the sample of `+by`.
497`b` is a key as a noun.
499#### Produces
501A unit.
503#### Source
505```hoon
506++ get
507 ~/ %get
508 |* b=*
509 => .(b `_?>(?=(^ a) p.n.a)`b)
510 |- ^- (unit _?>(?=(^ a) q.n.a))
511 ?~ a
512 ~
513 ?: =(b p.n.a)
514 (some q.n.a)
515 ?: (gor b p.n.a)
516 $(a l.a)
517 $(a r.a)
518```
520#### Examples
522```
523> a
524{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
526> (~(get by a) %a)
527[~ 1]
529> (~(get by a) %b)
530[~ 2]
532> (~(get by a) %z)
534```
536---
538### `++got:by`
540Assert
542Produce the value located at key `b` within map `a`. Crash if key `b` does not
543exist.
545#### Accepts
547`a` is a map, and is the sample of `+by`.
549`b` is a key as a noun.
551#### Produces
553A noun.
555#### Source
557```hoon
558++ got
559 |* b=*
560 (need (get b))
561```
563#### Examples
565```
566> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
567> a
568{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
570> (~(got by a) %a)
573> (~(got by a) %b)
576> (~(got by a) %z)
577dojo: hoon expression failed
578```
580---
582### `++gut:by`
584Grab value with default
586Produce the value located at key `b` within map `a`. Use default value `c` if
587key does not exist.
589#### Accepts
591`a` is a map, and is the sample of `+by`.
593`b` is a key as a noun.
595`c` is a noun.
597#### Produces
599A noun.
601#### Source
603```hoon
604++ gut
605 |* [b=* c=*]
606 (fall (get b) c)
607```
609#### Examples
611```
612> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
613> a
614{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
616> (~(gut by a) %a 9.999)
619> (~(gut by a) %b 9.999)
622> (~(gut by a) %z 9.999)
6239.999
624```
626---
628### `++has:by`
630Key existence check
632Checks whether map `a` contains an element with key `b`, producing a flag.
634#### Accepts
636`a` is a map, and is the sample of `+by`.
638`b` is a key as a noun.
640#### Produces
642A flag.
644#### Source
646```hoon
647++ has
648 ~/ %has
649 |* b=*
650 !=(~ (get b))
651```
653#### Examples
655```
656> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
657> a
658{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
660> (~(has by a) %a)
661%.y
662> (~(has by a) %z)
663%.n
664```
666---
668### `++int:by`
670Intersection
672Produces a map of the (key) intersection between two maps of the same type, `a`
673and `b`. If both maps have an identical key that point to different values, the
674element from map `b` is used.
676#### Accepts
678`a` is a map, and is the sample of `+by`.
680`b` is a map.
682#### Produces
684A map.
686#### Source
688```hoon
689++ int
690 ~/ %int
691 =+ b=a
692 |@
693 ++ $
694 |- ^+ a
695 ?~ b
696 ~
697 ?~ a
698 ~
699 ?: (mor p.n.a p.n.b)
700 ?: =(p.n.b p.n.a)
701 b(l $(a l.a, b l.b), r $(a r.a, b r.b))
702 ?: (gor p.n.b p.n.a)
703 %- uni(a $(a l.a, r.b ~)) $(b r.b)
704 %- uni(a $(a r.a, l.b ~)) $(b l.b)
705 ?: =(p.n.a p.n.b)
706 b(l $(b l.b, a l.a), r $(b r.b, a r.a))
707 ?: (gor p.n.a p.n.b)
708 %- uni(a $(b l.b, r.a ~)) $(a r.a)
709 %- uni(a $(b r.b, l.a ~)) $(a l.a)
710 --
711```
713#### Examples
715```
716> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
717> =b `(map @tas @)`(malt (limo ~[c+3 d+4 e+5 f+6]))
718> a
719{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
720> b
721{[p=%e q=5] [p=%d q=4] [p=%f q=6] [p=%c q=3]}
723> `(map @tas @)`(~(int by a) b)
724{[p=%d q=4] [p=%c q=3]}
725```
727```
728> =a `(map @tas @)`(malt (limo ~[a+1 b+2]))
729> =b `(map @tas @)`(malt (limo ~[a+100 b+200]))
730> a
731{[p=%b q=2] [p=%a q=1]}
732> b
733{[p=%b q=200] [p=%a q=100]}
735> `(map @tas @)`(~(int by a) b)
736{[p=%b q=200] [p=%a q=100]}
737```
739---
741### `++jab:by`
743Transform value
745Produce map `a` with the value at key `b` transformed by gate `c`.
747#### Accepts
749`a` is a `map`, and is the sample of `+by`.
751`b` is a noun, and a key in `a`.
753`c` is a `gate`.
755#### Produces
757A `map`.
759#### Source
761```hoon
762++ jab
763 ~/ %jab
764 |* [key=_?>(?=(^ a) p.n.a) fun=$-(_?>(?=(^ a) q.n.a) _?>(?=(^ a) q.n.a))]
765 ^+ a
766 ::
767 ?~ a !!
768 ::
769 ?: =(key p.n.a)
770 a(q.n (fun q.n.a))
771 ::
772 ?: (gor key p.n.a)
773 a(l $(a l.a))
774 ::
775 a(r $(a r.a))
776```
778#### Examples
780```
781> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
782> a
783{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
785> `(map @tas @)`(~(jab by a) %d |=(x=@ (pow x 2)))
786{[p=%b q=2] [p=%d q=16] [p=%a q=1] [p=%c q=3]}
788> (~(jab by a) %z |=(x=@ (pow x 2)))
789dojo: hoon expression failed
791> (~(jab by a) %d |=(a=@ [a a]))
792-need.?(%~ [n=[p=@tas q=@] l=nlr([p=@tas q=@]) r=nlr([p=@tas q=@])])
793-have.[n=[p=@tas q=[@ @]] l=nlr([p=@tas q=@]) r=nlr([p=@tas q=@])]
794nest-fail
795dojo: hoon expression failed
796```
798---
800### `++key:by`
802Set of keys
804Produces a set of all keys in map `a`.
806#### Accepts
808`a` is a map, and is the sample of `+by`.
810#### Produces
812A set.
814#### Source
816```hoon
817++ key
818 =< $
819 ~/ %key
820 =+ b=`(set _?>(?=(^ a) p.n.a))`~
821 |. ^+ b
822 ?~ a b
823 $(a r.a, b $(a l.a, b (~(put in b) p.n.a)))
824```
826#### Examples
828```
829> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
831> ~(key by a)
832{%b %d %a %c}
833```
835---
837### `++mar:by`
839Add with validation
841Produces map `a` with the addition of key-value pair `b` and `c`, where the value is a
842nonempty unit.
844Accept a noun and a unit of a noun of the type of the map's keys and values,
845respectively. Validate that the value is not null and put the pair in the map.
846If the value is null, delete the key.
848#### Accepts
850`a` is a `map`, and is the sample of `+by`.
852`b` is a noun.
854`c` is a `unit`.
856#### Produces
858A map.
860#### Source
862```hoon
863++ mar
864 |* [b=* c=(unit *)]
865 ?~ c
866 (del b)
867 (put b u.c)
868```
870#### Examples
872```
873> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
874> a
875{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
877> `(map @tas @)`(~(mar by a) %e (some 5))
878{[p=%e q=5] [p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
880> `(map @tas @)`(~(mar by a) %a (some 10))
881{[p=%b q=2] [p=%d q=4] [p=%a q=10] [p=%c q=3]}
883> `(map @tas @)`(~(mar by a) %a ~)
884{[p=%b q=2] [p=%d q=4] [p=%c q=3]}
885```
887---
889### `++put:by`
891Add key-value pair
893Produces `a` with the addition of the key-value pair of `b` and `c`.
895#### Accepts
897`a` is a map, and is the sample of `+by`.
899`b` is a key of the same type as the keys in `a`.
901`c` is a value of the same type of the values in `a`.
903#### Produces
905A map.
907#### Source
909```hoon
910++ put
911 ~/ %put
912 |* [b=* c=*]
913 |- ^+ a
914 ?~ a
915 [[b c] ~ ~]
916 ?: =(b p.n.a)
917 ?: =(c q.n.a)
918 a
919 a(n [b c])
920 ?: (gor b p.n.a)
921 =+ d=$(a l.a)
922 ?> ?=(^ d)
923 ?: (mor p.n.a p.n.d)
924 a(l d)
925 d(r a(l r.d))
926 =+ d=$(a r.a)
927 ?> ?=(^ d)
928 ?: (mor p.n.a p.n.d)
929 a(r d)
930 d(l a(r l.d))
931```
933#### Examples
935```
936> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3]))
937> a
938{[p=%b q=2] [p=%a q=1] [p=%c q=3]}
940> `(map @tas @)`(~(put by a) %d 4)
941{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
943> `(map @tas @)`(~(put by a) %a 10)
944{[p=%b q=2] [p=%a q=10] [p=%c q=3]}
946> (~(put by a) 42 'foo')
947mull-grow
948mull-nice
949-need.?(%~ [n=[p=@tas q=@] l=nlr([p=@tas q=@]) r=nlr([p=@tas q=@])])
950-have.[[@ud @t] %~ %~]
951nest-fail
952dojo: hoon expression failed
953```
955---
957### `++rep:by`
959Reduce to product
961Accumulate elements of map `a` using gate `b`, producing a noun.
963#### Accepts
965`a` is a map.
967`b` is a gate.
969#### Produces
971A noun.
973#### Source
975```hoon
976++ rep
977 ~/ %rep
978 |* b=_=>(~ |=([* *] +<+))
979 |-
980 ?~ a +<+.b
981 $(a r.a, +<+.b $(a l.a, +<+.b (b n.a +<+.b)))
982```
984#### Examples
986```
987> =a `(map @tas @)`(malt (limo ~[a+1 b+2 c+3 d+4]))
988> a
989{[p=%b q=2] [p=%d q=4] [p=%a q=1] [p=%c q=3]}
991> (~(rep by a) |=([p=[@tas @] q=@] ~&([p q] (add +.p q))))
992[[%b 2] 0]
993[[%d 4] 2]
994[[%c 3] 6]
995[[%a 1] 9]
996q=10
997```
999#### Discussion
1001The gate will iteratively be fed a cell whose head is a key-value pair from the map and whose tail is an accumulator, producing the final value of the accumulator.
1003---
1005### `++rib:by`
1007Transform + product
1009`c` is a gate with a sample like `[[key value] accumulator]` and a product like `[accumulator [key value]]`. Each key-value pair in map `a` is passed to `c` and replaced with the key-value pair `c` produced. The final value of the accumulator and the modified map are returned. `b` is the initial value of the accumulator.
1011#### Accepts
1013`a` is a map, and is the sample of `+by`.
1015`b` is a noun, and is the initial value of the accumulator.
1017`c` is a gate.
1019#### Produces
1021A cell of a noun and a map.
1023#### Source
1025```hoon
1026++ rib
1027 |* [b=* c=gate]
1028 |- ^+ [b a]
1029 ?~ a [b ~]
1030 =+ d=(c n.a b)
1031 =. n.a +.d
1032 =+ e=$(a l.a, b -.d)
1033 =+ f=$(a r.a, b -.e)
1034 [-.f a(l +.e, r +.f)]
1035```
1037#### Examples
1039In this example, all values less than three are changed to zero, and a list of their keys are produced along with the modified map.
1041```
1042> =a `(map @t @)`(malt ~[['a' 1] ['b' 2] ['c' 3] ['d' 4] ['e' 5]])
1043> a
1044{[p='e' q=5] [p='b' q=2] [p='d' q=4] [p='a' q=1] [p='c' q=3]}
1046> =c |= [[k=@t v=@] acc=(list @t)]
1047 ?: (lth v 3)
1048 [[k acc] [k 0]]
1049 [acc [k v]]
1051> `[(list @t) (map @t @)]`(~(rib by a) *(list @t) c)
1052[<|a b|> {[p='e' q=5] [p='b' q=0] [p='d' q=4] [p='a' q=0] [p='c' q=3]}]
1053```
1055#### Discussion
1057Key-value pairs in the map are transformed in their existing tree location. This means if you change the key, you'd likely produce a map with an incorrect order, so typically you should only change the value.
1059---
1061### `++run:by`
1063Transform values
1065Iterates over every value in map `a` using gate `b`, producing a map.
1067#### Accepts
1069`a` is a map, and is the sample of `+by`.
1071`b` is a gate.
1073#### Produces
1075A map.
1077#### Source
1079```hoon
1080++ run
1081 ~/ %run
1082 |* b=gate
1083 |-
1084 ?~ a a
1085 [n=[p=p.n.a q=(b q.n.a)] l=$(a l.a) r=$(a r.a)]
1086```
1088#### Examples
1090```
1091> =a `(map @t @)`(malt ~[['a' 1] ['b' 2] ['c' 3] ['d' 4] ['e' 5]])
1093> `(map @t @)`(~(run by a) dec)
1094{[p='e' q=4] [p='b' q=1] [p='d' q=3] [p='a' q=0] [p='c' q=2]}
1095```
1097---
1099### `++rut:by`
1101Transform nodes
1103Applies a gate `b` to nodes in map `a`. The sample of gate `b` is a key-value pair, and it produces a new value.
1105#### Accepts
1107`a` is a map, and is the sample of `+by`.
1109`b` is a gate.
1111#### Produces
1113A map.
1115#### Source
1117```hoon
1118++ rut
1119 |* b=gate
1120 |-
1121 ?~ a a
1122 [n=[p=p.n.a q=(b p.n.a q.n.a)] l=$(a l.a) r=$(a r.a)]
1123```
1125#### Examples
1127```
1128> =a `(map @ @)`(malt ~[[1 1] [2 2] [3 3] [4 4] [5 5]])
1130> =b |= [k=@ v=@]
1131 ?: (gth v 2)
1132 (mul k v)
1135> `(map @ @)`(~(rut by a) b)
1136{[p=5 q=25] [p=1 q=1] [p=2 q=2] [p=3 q=9] [p=4 q=16]}
1137```
1139---
1141### `++tap:by`
1143Listify pairs
1145Produces the list of all elements in map `a`.
1147#### Accepts
1149`a` is a map, and is the sample of `+by`.
1151#### Produces
1153A list.
1155#### Source
1157```hoon
1158++ tap
1159 =< $
1160 ~/ %tap
1161 =+ b=`(list _?>(?=(^ a) n.a))`~
1162 |. ^+ b
1163 ?~ a
1165 $(a r.a, b [n.a $(a l.a)])
1166```
1168#### Examples
1170```
1171> =a `(map @ @)`(malt ~[[1 1] [2 2] [3 3] [4 4] [5 5]])
1173> ~(tap by a)
1174~[[p=4 q=4] [p=3 q=3] [p=2 q=2] [p=1 q=1] [p=5 q=5]]
1175```
1177---
1179### `++uni:by`
1181Union, merge
1183Produces a map of the union between the keys of `a` and `b`. If `b` shares a
1184key with `a`, the tuple from `b` is preserved.
1186#### Accepts
1188`a` is a map, and is the sample `+by`.
1190`b` is a map.
1192#### Produces
1194A map.
1196#### Source
1198```hoon
1199++ uni
1200 ~/ %uni
1201 =+ b=a
1202 |@
1203 ++ $
1204 |- ^+ a
1205 ?~ b
1207 ?~ a
1209 ?: =(p.n.b p.n.a)
1210 b(l $(a l.a, b l.b), r $(a r.a, b r.b))
1211 ?: (mor p.n.a p.n.b)
1212 ?: (gor p.n.b p.n.a)
1213 $(l.a $(a l.a, r.b ~), b r.b)
1214 $(r.a $(a r.a, l.b ~), b l.b)
1215 ?: (gor p.n.a p.n.b)
1216 $(l.b $(b l.b, r.a ~), a r.a)
1217 $(r.b $(b r.b, l.a ~), a l.a)
1218 --
1219```
1221#### Examples
1223```
1224> =a `(map @ @)`(malt ~[[1 1] [2 2] [3 3]])
1225> =b `(map @ @)`(malt ~[[3 300] [4 400] [5 500]])
1226> a
1227{[p=1 q=1] [p=2 q=2] [p=3 q=3]}
1228> b
1229{[p=5 q=500] [p=3 q=300] [p=4 q=400]}
1231> `(map @ @)`(~(uni by a) b)
1232{[p=5 q=500] [p=1 q=1] [p=2 q=2] [p=3 q=300] [p=4 q=400]}
1233```
1235---
1237### `++uno:by`
1239General union
1241Produces a map of the union between the keys of `a` and `b`. If `b` shares a key with `a`, gate `meg` is applied to both and its product is used as the new value of the key in question.
1243#### Accepts
1245`a` is a `map`, and is the sample of `+by`.
1247`b` is a `map`, and is the sample of `~(uno by a)`.
1249`meg` is a gate, and is the sample of `(~(uno by a) b)`.
1251#### Produces
1253A `map`.
1255#### Source
1257```hoon
1258++ uno
1259 =+ b=a
1260 |@
1261 ++ $
1262 |= meg=$-([_p:node _q:node _q:node] _q:node)
1263 |- ^+ a
1264 ?~ b
1266 ?~ a
1268 ?: =(p.n.b p.n.a)
1269 :+ [p.n.a (meg p.n.a q.n.a q.n.b)]
1270 $(b l.b, a l.a)
1271 $(b r.b, a r.a)
1272 ?: (mor p.n.a p.n.b)
1273 ?: (gor p.n.b p.n.a)
1274 $(l.a $(a l.a, r.b ~), b r.b)
1275 $(r.a $(a r.a, l.b ~), b l.b)
1276 ?: (gor p.n.a p.n.b)
1277 $(l.b $(b l.b, r.a ~), a r.a)
1278 $(r.b $(b r.b, l.a ~), a l.a)
1279 --
1280```
1282#### Examples
1284```
1285> =a `(map @ @)`(malt ~[[1 1] [2 2] [3 3]])
1286> =b `(map @ @)`(malt ~[[3 3] [4 4] [5 5]])
1287> a
1288{[p=1 q=1] [p=2 q=2] [p=3 q=3]}
1289> b
1290{[p=5 q=5] [p=3 q=3] [p=4 q=4]}
1292> `(map @ @)`((~(uno by a) b) |=([k=@ v=@ w=@] (add v w)))
1293{[p=5 q=5] [p=1 q=1] [p=2 q=2] [p=3 q=6] [p=4 q=4]}
1294```
1296---
1298### `++urn:by`
1300Turn (with key)
1302Iterates over every value in map `a` using gate `b`, which accepts both
1303the key and the value of each element as its sample.
1305#### Accepts
1307`a` is a map.
1309`b` is a gate that accepts two nouns.
1311#### Produces
1313A `map`.
1315#### Source
1317```hoon
1318++ urn
1319 ~/ %urn
1320 |* b=$-([* *] *)
1321 |-
1322 ?~ a ~
1323 a(n n.a(q (b p.n.a q.n.a)), l $(a l.a), r $(a r.a))
1324```
1326#### Examples
1328```
1329> =a `(map @ @)`(malt ~[[1 1] [2 2] [3 3]])
1330> a
1331{[p=1 q=1] [p=2 q=2] [p=3 q=3]}
1333> (~(urn by a) |=([k=@ v=@] (pow v 2)))
1334{[p=1 q=1] [p=2 q=4] [p=3 q=9]}
1335```
1337---
1339### `++wyt:by`
1341Depth
1343Produce the depth of the tree map `a`.
1345#### Accepts
1347`a` is a map, and is the sample of `+by`.
1349#### Produces
1351An atom.
1353#### Source
1355```hoon
1356++ wyt
1357 =< $
1358 ~% %wyt + ~
1359 |. ^- @
1360 ?~(a 0 +((add $(a l.a) $(a r.a))))
1361```
1363#### Examples
1365```
1366> =a `(map @ @)`(malt ~[[1 1] [2 2] [3 3]])
1367> =b `(map @ @)`(malt ~[[1 1] [2 2] [3 3] [4 4] [5 5]])
1368> a
1369{[p=1 q=1] [p=2 q=2] [p=3 q=3]}
1370> b
1371{[p=5 q=5] [p=1 q=1] [p=2 q=2] [p=3 q=3] [p=4 q=4]}
1373> ~(wyt by a)
1376> ~(wyt by b)
1378```
1380---
1382### `++val:by`
1384List of values
1386Produces a list of all values in map `a`.
1388#### Accepts
1390`a` is a map.
1392#### Produces
1394A list.
1396#### Source
1398```hoon
1399++ val
1400 =+ b=`(list _?>(?=(^ a) q.n.a))`~
1401 |- ^+ b
1402 ?~ a b
1403 $(a r.a, b [q.n.a $(a l.a)])
1404```
1406#### Examples
1408```
1409> =a `(map @t @)`(malt ~[['a' 1] ['b' 2] ['c' 3]])
1410> a
1411{[p='b' q=2] [p='a' q=1] [p='c' q=3]}
1413> ~(val by a)
1414~[3 1 2]
1415```
1417---