:-  :~  navhome/'/docs/'
        sort/'12'
        title/'2i: Map Logic'
    ==

;>

# 2i: map logic

### `++by`

Map operations

Container arm for map operation arms. A map is a set of key-value pairs. The
contained arms inherit its sample map, `a`.

### Accepts

`a` is a map.

#### Source

```
    ++  by
      ~/  %by
      =|  a=(tree (pair))
      =*  node  ?>(?=(^ a) n.a)
```

#### Examples

```
    > ~(. by (my [%a 1] [%b 2] ~))
    < 27.zjr
    {   a
      ?(
        { n/{?(p/$a p/$b) q/@ud}
          l/nlr({p/?($b $a) q/@ud})
          r/nlr({p/?($b $a) q/@ud})
        }
        $~
      )
      <119.wim 31.ohr 1.jmk $143>
    }
```

---
### `+-all:by`

Logical AND

Computes the logical AND on the results of slamming every element in map `a`
with gate `b`.

#### Accepts

`a` is a map.

`b` is a wet gate.

#### Produces

A flag.

#### Source

```
      +-  all
        ~/  %all
        |*  b=$-(* ?)
        |-  ^-  ?
        ?~  a
          &
        ?&((b q.n.a) $(a l.a) $(a r.a))
```

#### Examples

```
    > =b (my [['a' 1] ['b' [2 3]] ~])
    > (~(all by b) |=(a=* ?@(a & |)))
    %.n

    > =a (my [['a' 1] ['b' 2] ['c' 3] ['d' 4] ['e' 5] ~])
    > (~(all by a) |=(a=@ (lte a 6)))
    %.y

    > (~(all by a) |=(a=@ (lte a 4)))
    %.n
```

---
### `+-any:by`

Logical OR

Computes the logical OR on the results of slamming every element with
gate `b`.

#### Accepts

`a` is a map.

`b` is a wet gate.

#### Produces

A flag.

#### Source

```
      +-  any
        ~/  %any
        |*  b=$-(* ?)
        |-  ^-  ?
        ?~  a
          |
        ?|((b q.n.a) $(a l.a) $(a r.a))
```

#### Examples

```
    > =b (my [['a' 1] ['b' [2 3]] ~])
    > (~(any by b) |=(a=* ?@(a & |)))
    %.y

    > =a (my [['a' 1] ['b' 2] ['c' 3] ['d' 4] ['e' 5] ~])
    > (~(any by a) |=(a=@ (lte a 4)))
    %.y
```

---
###`+-apt:by`

Check correctness

Computes whether `a` has a correct horizontal order and a correct vertical
order, producing a flag.

#### Accepts

`a` is a map.

#### Produces

A flag.

#### Source

```
      +-  apt
        =|  [l=(unit) r=(unit)]
        |-  ^-  ?
        ?~  a   &
        ?&  ?~(l & (gor p.n.a u.l))
            ?~(r & (gor u.r p.n.a))
            ?~(l.a & ?&((vor p.n.a p.n.l.a) $(a l.a, l `p.n.a)))
            ?~(r.a & ?&((vor p.n.a p.n.r.a) $(a r.a, r `p.n.a)))
        ==
```

#### Examples

```
    > =a (my [['a' 1] ['b' [2 3]] ~])
    > ~(apt by a)
    %.y

    > =s (my [[1 2] [3 4] ~])
    > =z ?~  s  ~  s(p.n 10)
    > z
    [n=[p=10 q=2] l={} r={[p=3 q=4]}]

    > ~(apt by z)
    %.n
```

#### Discussion

See section [`2f`](../2f) for more information on noun ordering.

###`+-bif:by`

Bifurcate

Splits map `a` into two maps `l` and `r`, with the head at `b` discarded.

#### Accepts

`a` is a map.

`b` is a noun.

`c` is a noun.

#### Produces

A cell of two maps.

#### Source

```
      +-  bif
        ~/  %bif
        |*  [b=* c=*]
        ^+  [l=a r=a]
        =<  +
        |-  ^+  a
        ?~  a
          [[b c] ~ ~]
        ?:  =(b p.n.a)
          ?:  =(c q.n.a)
            a
          [[b c] l.a r.a]
        ?:  (gor b p.n.a)
          =+  d=$(a l.a)
          ?>  ?=(^ d)
          [n.d l.d [n.a r.d r.a]]
        =+  d=$(a r.a)
        ?>  ?=(^ d)
        [n.d [n.a l.a l.d] r.d]
```

#### Examples

```
    > =a (my [['a' 1] ['b' 2] ['c' 3] ~])

    > (~(bif by a) ['b' 2])
    [l=[n=[p='c' q=3] l=[n=[p='a' q=1] l={} r={}] r=~] r=~]
```

###`+-def:by`

Difference

#### Accepts

`a` is a map.

`b` is a map.

#### Produces

A map.

#### Source

```
      +-  def
        |*  b=_a
        ^-  (map _p:node (pair (unit _q:node) (unit _q:node)))
        !!
```

#### Examples

---
###`+-dep:by`

Difference as patch


#### Accepts

`a` is a map.

`b` is a map.

#### Produces

A cell of maps.

#### Source

```
      +-  dep
        |*  b=_a
        ^+  [p=a q=a]
        =+  c=~(tap by (def b))
        =+  [d e]=[`_a`~ `_a`~]
        |-  ^+  [d e]
        ?~  c  [d e]
        %=  $
          c  t.c
          d  ?~(q.q.i.c d (~(put by d) p.i.c u.q.q.i.c))
          e  ?~(p.q.i.c e (~(put by e) p.i.c u.p.q.i.c))
        ==
```

#### Examples



---
### `+-del:by`

Delete

Produces map `a` with the element located at key `b` removed.

#### Accepts

`a` is a map.

`b` is a key as a noun.

#### Produces

A map.

#### Source

```
      +-  del
        ~/  %del
        |*  b=*
        |-  ^+  a
        ?~  a
          ~
        ?.  =(b p.n.a)
          ?:  (gor b p.n.a)
            [n.a $(a l.a) r.a]
          [n.a l.a $(a r.a)]
        |-  ^-  [(~ _a)]
        ?~  l.a  r.a
        ?~  r.a  l.a
        ?:  (vor p.n.l.a p.n.r.a)
          [n.l.a l.l.a $(l.a r.l.a)]
        [n.r.a $(r.a l.r.a) r.r.a]
```

#### Examples

```
    > =b (my [['a' 1] ['b' [2 3]] ~])
    > (~(del by b) 'a')
    [n=[p='b' q=[2 3]] l=~ r=~]
```

---
### `+-dig:by`

Address of key

Produce the address of key `b` within map `a`.

#### Accepts

`a` is a map.

`b` is a key as a noun.

#### Produces

A unit.

#### Source

```
      +-  dig
        |=  b=*
        =+  c=1
        |-  ^-  (unit @)
        ?~  a  ~
        ?:  =(b p.n.a)  [~ u=(peg c 2)]
        ?:  (gor b p.n.a)
          $(a l.a, c (peg c 6))
        $(a r.a, c (peg c 7))
```

#### Examples

```
        > =b (my [['a' 1] ['b' [2 3]] ~])
        > (~(dig by b) 'b')
        [~ u=2]
```

---
### `+-gas:by`

Concatenate

Insert a list of key-value pairs `b` into map `a`.

#### Accepts

`a` is a map.

`b` is a list of cells of key-value nouns `p` and `q`.

#### Produces

A map.

#### Source

```
      +-  gas
        ~/  %gas
        |*  b=(list [p=* q=*])
        =>  .(b `(list _?>(?=(^ a) n.a))`b)
        |-  ^+  a
        ?~  b
          a
        $(b t.b, a (put p.i.b q.i.b))
```

#### Examples

```
    > =a (my [['a' 1] ['b' 2] ~])
    > =b [['c' 3] ['d' 4] ~]

    > (~(gas by a) b)
    [n=[p='b' q=2] l=[n=[p='d' q=4] l={} r={[p='a' q=1] [p='c' q=3]}] r=~]
```

---
### `+-get:by`

Grab unit value

Produce the unit value of the value located at key `b` within map `a`.

#### Accepts

`a` is a map.

`b` is a key as a noun.

#### Produces

A unit.

#### Source

```
      +-  get
        ~/  %get
        |=  b=*
        ^-  [$@(~ [~ u=_?>(?=(^ a) q.n.a)])]
        =+  42
        ?~  a
          ~
        ?:  =(b p.n.a)
          [~ u=q.n.a]
        ?:  (gor b p.n.a)
          $(a l.a)
        $(a r.a)
```

#### Examples

```
    > =b (my [['a' 1] ['b' [2 3]] ~])
    > (~(get by b) 'b')
    [~ u=[2 3]]


    > =m (my [['a' 1] ['b' 2] ~])
    > (~(get by m) 'a')
    [~ u=1]
```

---
### `+-got:by`

Assert

Produce the value located at key `b` within map `a`. Crash if key `b` does not
exist.

#### Accepts

`a` is a map.

`b` is a key as a noun.

#### Produces

A noun.

####  Source

```
      +-  got
        |*  b=*
        (need (get b))
```

#### Examples

```
    > =m (my [['a' 1] ['b' 2] ~])
    > m
    [n=[p='b' q=2] l={[p='a' q=1]} r={}]

    > (~(got by m) 'a')
    1

    > (~(got by m) 'c')
    ! exit
```

---
### `+-has:by`

Key existence check

Checks whether map `a` contains an element with key `b`, producing a flag.

#### Accepts

`a` is a map.

`b` is a key as a noun.

#### Produces

A flag.

#### Source

```
    +-  has
      ~/  %has
      |*  b=*
      !=(~ (get b))
```

#### Examples

```
    > =b (my [['a' 1] ['b' [2 3]] ~])
    > (~(has by b) 'b')
    %.y

    > (~(has by b) 'c')
    %.n
```

---
### `+-int:by`

Intersection

Produces a map of the (key) intersection between two maps of the same type, `a`
and `b`. If both maps have an identical key that point to different values, the
element from map `b` is used.

#### Accepts

`a` is a map.

`b` is a map.

#### Produces

A map.

#### Source

```
      +-  int
        ~/  %int
        |*  b=_a
        |-  ^+  a
        ?~  b
          ~
        ?~  a
          ~
        ?:  (vor p.n.a p.n.b)
          ?:  =(p.n.b p.n.a)
            [n.b $(a l.a, b l.b) $(a r.a, b r.b)]
          ?:  (gor p.n.b p.n.a)
            %-  uni(a $(a l.a, b [n.b l.b ~]))  $(b r.b)
          %-  uni(a $(a r.a, b [n.b ~ r.b]))  $(b l.b)
        ?:  =(p.n.a p.n.b)
          [n.b $(b l.b, a l.a) $(b r.b, a r.a)]
        ?:  (gor p.n.a p.n.b)
          %-  uni(a $(b l.b, a [n.a l.a ~]))  $(a r.a)
        %-  uni(a $(b r.b, a [n.a ~ r.a]))  $(a l.a)
```

#### Examples

```
    > =n (my [['a' 1] ['c' 3] ~])
    > =m (my [['a' 1] ['b' 2] ~])

    > (~(int by m) n)
    [n=[p='a' q=1] l=~ r=~]

    > =p (my [['a' 2] ['b' 2] ~])
    > p
    [n=[p='b' q=2] l={[p='a' q=2]} r={}]
    > (~(int by p) n)
    [n=[p='a' q=1] l=~ r=~]

    > =q (my [['a' 2] ['c' 2] ~])
    > q
    [n=[p='c' q=2] l={[p='a' q=2]} r={}]
    > (~(int by p) q)
    [n=[p='a' q=2] l=~ r=~]

    > =o (my [['c' 3] ['d' 4] ~])
    > (~(int by m) o)
    ~
```

---
### `+-mar:by`

Assert and add

Produces map `a` with the addition of a key-value pair, where the value is a
nonempty unit.

Accept a noun and a unit of a noun of the type of the map's keys and values,
respectively. Validate that the value is not null and put the pair in the map.
If the value is null, delete the key.

#### Accepts

`a` is a map.

`b` is a unit.

#### Produces

A map.

#### Assert and Add

```
      +-  mar
        |*  [b=_?>(?=(^ a) p.n.a) c=(unit ,_?>(?=(^ a) q.n.a))]
        ?~  c
          (del b)
        (put b u.c)
```

#### Examples

```
    > =m (my [['a' 1] ['b' 2] ~])
    > (~(mar by m) 'c' (some 3))
    [n=[p='b' q=2] l=[n=[p='c' q=3] l=[n=[p='a' q=1] l={} r={}] r=~] r=~]

    > (~(mar by m) 'c' ~)
    [n=[p='b' q=2] l=[n=[p='a' q=1] l=~ r=~] r=~]

    > (~(mar by m) 'b' ~)
    [n=[p='a' q=1] l=~ r=~]
```

---
### `+-put:by`

Add key-value pair

Produces `a` with the addition of the key-value pair of `b` and `c`.

#### Accepts

`a` is a map.

`b` is a key of the same type as the keys in `a`.

`c` is a value of the same type of the values in `a`.

#### Produces

A map.

#### Source

```
      +-  put
        ~/  %put
        |*  [b=* c=*]
        |-  ^+  a
        ?~  a
          [[b c] ~ ~]
        ?:  =(b p.n.a)
          ?:  =(c q.n.a)
            a
          [[b c] l.a r.a]
        ?:  (gor b p.n.a)
          =+  d=$(a l.a)
          ?>  ?=(^ d)
          ?:  (vor p.n.a p.n.d)
            [n.a d r.a]
          [n.d l.d [n.a r.d r.a]]
        =+  d=$(a r.a)
        ?>  ?=(^ d)
        ?:  (vor p.n.a p.n.d)
          [n.a l.a d]
        [n.d [n.a l.a l.d] r.d]
```

#### Examples

```
    > =m (my [['a' 1] ['b' 2] ~])
    > (~(put by ~) 'c' 3)
    [n=[p='b' q=2] l=[n=[p='c' q=3] l={[p='a' q=1]} r={}] r=~]

    > (~(put by m) "zod" 26)
    ! nest-fail
    ! exit

    > (~(put by m) 'a' 2)
    [n=[p='b' q=2] l=[n=[p='a' q=2] l={} r={}] r=~]

    > (put:by m 'a' 2)
    {[p=[[98 2] [[97 1] 0 0] 0] q=[97 2]]}
```

---
### `+-rep:by`

Replace by product

Accumulate elements of map `a` using gate `b`, producing a noun.

#### Accepts

`a` is a map.

`b` is a wet gate.

#### Produces

A noun.

#### Source

```
      +-  rep
        |*  b=_|=([* *] +<+)
        |-
        ?~  a  +<+.b
        $(a r.a, +<+.b $(a l.a, +<+.b (b n.a +<+.b)))
```

#### Examples

```
    > =m (my [['a' 1] ['b' 2] ~])
    > (~(rep by m) |=(a=(pair * *) p.a))
    q=[97 1]
```

---
### `+-rib:by`

Replace values with accumulator

#### Accepts

`a` is a map.

`b` is a noun.

`c` is a wet gate.

####

A cell of nouns.

#### Source

```
      +-  rib
        |*  [b=* c=gate]
        |-  ^+  [b a]
        ?~  a  [b ~]
        =+  d=(c n.a b)
        =.  n.a  +.d
        =+  e=$(a l.a, b -.d)
        =+  f=$(a r.a, b -.e)
        [-.f [n.a +.e +.f]]
```

#### Examples

```
    > =m (my [['a' 1] ['b' 2] ~])
    > (~(rib by m) [1 2] (con by m))

    > (~(rep by m) [1 2] |=(a=(pair * *) p.a))
```

---
### `+-run:by`

Transform values

Iterates over every value in map `a` using gate `b`, producing a map.

#### Accepts

`a` is a map.

`b` is a wet gate.

#### Produces

A map.

#### Source

```
      +-  run
        |*  b=gate
        |-
        ?~  a  a
        [n=[p=p.n.a q=(b q.n.a)] l=$(a l.a) r=$(a r.a)]
```

#### Examples

```
    > =m (my [['a' 1] ['b' 2] ~])

    > ^+(m (~(run by m) dec))
    [n=[p='b' q=1] l={[p='a' q=0]} r={}]

    > `(map @tas @t)`(~(run by m) (cury scot %ux))
    {[p=%a q='0x1'] [p=%b q='0x2']}
```

---
### `+-rut:by`

Transform nodes

Applies a gate `b` to nodes in map `a`.

#### Accepts

`a` is a map.

`b` is a wet gate.

#### Produces

A map.

#### Source

```
    +-  rut
      |*  b=gate
      |-
      ?~  a  a
      [n=[p=p.n.a q=(b p.n.a q.n.a)] l=$(a l.a) r=$(a r.a)]
```

#### Examples

```
    > =m (my [['a' 1] ['b' 2] ~])
```

---
### `+-tap:by`

Listify pairs

Produces the list of all elements in map `a` that is prepended to list `b`,
which is empty by default.

#### Accepts

`a` is a map.

`b` is a list.

#### Produces

A list.

#### Source

```
      +-  tap
        =<  $
        ~/  %tap
        =|  b=(list _?>(?=(^ a) n.a))
        |.  ^+  b
        ?~  a
          b
        $(a r.a, b [n.a $(a l.a)])
```

#### Examples

```
    > =m (my [['a' 1] ['b' 2] ~])
    [n=[p='b' q=2] l={[p='a' q=1]} r={}]
    > `*`m
    [[98 2] [[97 1] 0 0] 0]

    > ~(tap by m)
    ~[[p='b' q=2] [p='a' q=1]]
    > `*`~(tap by m)
    [[98 2] [97 1] 0]
```

---
### `+-uni:by`

Union

Produces a map of the union between the keys of `a` and `b`. If `b` shares a
key with `a`, the tuple from `b` is preserved.

#### Accepts

`a` is a map.

`b` is a map.

#### Produces

A map.

#### Source

```
      +-  uni
        ~/  %uni
        |*  b=_a
        |-  ^+  a
        ?~  b
          a
        ?~  a
          b
        ?:  (vor p.n.a p.n.b)
          ?:  =(p.n.b p.n.a)
            [n.b $(a l.a, b l.b) $(a r.a, b r.b)]
          ?:  (gor p.n.b p.n.a)
            $(a [n.a $(a l.a, b [n.b l.b ~]) r.a], b r.b)
          $(a [n.a l.a $(a r.a, b [n.b ~ r.b])], b l.b)
        ?:  =(p.n.a p.n.b)
          [n.b $(b l.b, a l.a) $(b r.b, a r.a)]
        ?:  (gor p.n.a p.n.b)
          $(b [n.b $(b l.b, a [n.a l.a ~]) r.b], a r.a)
        $(b [n.b l.b $(b r.b, a [n.a ~ r.a])], a l.a)
```

#### Examples

```
    > =m (my [['a' 1] ['b' 2] ~])

    > =o (my [['c' 3] ['d' 4] ~])

    > (~(uni by m) o)
    [n=[p='b' q=2] l=[n=[p='d' q=4] l={} r={[p='a' q=1] [p='c' q=3]}] r=~]

    > (~(uni by m) ~)
    {[p='a' q=1] [p='b' q=2]}

    > n
    {[p='a' q=1] [p='c' q=3]}
    > (~(uni by o) n)
    {[p='d' q=4] [p='a' q=1] [p='c' q=3]}
```

---
### `+-urn:by`

Turn (with key)

Iterates over every value in map `a` using gate `b`, which accepts both
the key and the value of each element as its sample.

#### Accepts

`a` is a map.

`b` is a wet gate that accepts two nouns.

#### Produces

A noun.

#### Source

```
      +-  urn
        |*  b=$-({* *} *)
        |-
        ?~  a  ~
        [n=[p=p.n.a q=(b p.n.a q.n.a)] l=$(a l.a) r=$(a r.a)
```

#### Examples

```
    > m
    {[p='a' q=1] [p='b' q=2]}

    > (~(urn by m) |=(a=(pair * *) q.a))
    {[p='a' q=1] [p='b' q=2]}

    > (~(urn by m) |=(a=(pair * *) 7))
    {[p='a' q=7] [p='b' q=7]}

    > (~(urn by m) |=(a=(pair * *) p.a))
    {[p='a' q=97] [p='b' q=98]}
```

---

### `+-wyt:by`

Depth

Produce the depth of the tree map `a`.

#### Accepts

`a` is a map.

#### Produces

An atom.

#### Source

```
      +-  wyt
        |-  ^-  @
        ?~(a 0 +((add $(a l.a) $(a r.a))))
```

#### Examples

```
    > =m (my [['a' 1] ['b' 2] ~])

    > =o (my [['c' 3] ['d' 4] ~])

    > ~(wyt by m)
    2

    > ~(wyt by o)
    2

    > ~(wyt by (~(uni by m) o))
    4
```

---