+++
title = "2j: Jar and Jug Logic"
weight = 13
template = "doc.html"
+++

## `++ja`

Jar engine

A container arm for `jar` operation arms. A `jar` is a `map` of
`list`s. The contained arms inherit the sample jar.

#### Accepts

`a` is a jar.

#### Produces

A core.

#### Source

```hoon
++  ja
  =|  a=(tree (pair * (list)))  ::  (jar)
  |@
```

#### Examples

```
> ~(. ja (my [a+1 b+2 ~]))
< 2.ngd
  [   a
    ?(
      %~
      [ n=[?(p=%a p=%b) q=@ud]
        l=nlr([p=?(%a %b) q=@ud])
        r=nlr([p=?(%a %b) q=@ud])
      ]
    )
    <123.zao 46.hgz 1.pnw %140>
  ]
>
```

---

### `++get:ja`

Grab value by key

Produces the list at key `b` in jar `a`.

#### Accepts

`a` is a `jar`, and is the sample of `+ja`.

`b` is a noun.

#### Produces

A `list`.

#### Source

```hoon
++  get
  |*  b=*
  =+  c=(~(get by a) b)
  ?~(c ~ u.c)
```

#### Examples

```
> =j `(jar @t @ud)`(malt ~[['a' `(list @ud)`~[1 2 3]] ['b' `(list @ud)`~[4 5 6]]])
> j
{[p='b' q=~[4 5 6]] [p='a' q=~[1 2 3]]}

> `(list @ud)`(~(get ja j) 'a')
~[1 2 3]

> `(list @ud)`(~(get ja j) 'b')
~[4 5 6]

> `(list @ud)`(~(get ja j) 'c')
~
```

---

### `++add:ja`

Prepend to list

Adds `c` to the head of the list at key `b` in jar `a`. If `b` does not exist in `a`, a new key-value pair is added with a list containing `c`.

#### Accepts

`a` is a `jar`, and is the sample of `+ja`.

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

`c` is a noun of the same type the lists in `a` contain.

#### Produces

A `jar`.

#### Source

```hoon
++  add
  |*  [b=* c=*]
  =+  d=(get b)
  (~(put by a) b [c d])
```

#### Examples

```
> =j `(jar @t @ud)`(malt ~[['a' `(list @ud)`~[1 2 3]] ['b' `(list @ud)`~[4 5 6]]])
> j
{[p='b' q=~[4 5 6]] [p='a' q=~[1 2 3]]}

> `(jar @t @ud)`(~(add ja j) 'b' 7)
{[p='b' q=~[7 4 5 6]] [p='a' q=~[1 2 3]]}

> `(jar @t @ud)`(~(add ja j) 'c' 8)
{[p='b' q=~[4 5 6]] [p='a' q=~[1 2 3]] [p='c' q=~[8]]}
```

---

## `++ju`

Jug operations

Container arm for jug operation arms. A `jug` is a `map` of
`set`s. The contained arms inherit its sample jug, `a`.

#### Accepts

`a` is a `jug`.

#### Produces

A core.

#### Source

```hoon
++  ju
  =|  a=(tree (pair * (tree)))  ::  (jug)
  |@
```

#### Example

```
> =j `(jug @t @ud)`(malt ~[['a' (silt ~[1 2 3])] ['b' (silt ~[4 5 6])]])
> j
{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}

> ~(. ju j)
<5.cws [a=nlr([p=@t q=nlr(@ud)]) <123.zao 46.hgz 1.pnw %140>]>
```

---

### `++del:ju`

Remove

Produces jug `a` with value `c` removed from set located at key `b`.

#### Accepts

`a` is a jug, and is the sample of `+ju`.

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

`c` is a noun of the same type as the sets in `a` contain.

#### Source

```hoon
++  del
  |*  [b=* c=*]
  ^+  a
  =+  d=(get b)
  =+  e=(~(del in d) c)
  ?~  e
    (~(del by a) b)
  (~(put by a) b e)
```

#### Examples

```
> j
{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}

> `(jug @t @ud)`(~(del ju j) 'b' 6)
{[p='b' q={5 4}] [p='a' q={1 2 3}]}

> `(jug @t @ud)`(~(del ju j) 'b' 10)
{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}

> `(jug @t @ud)`(~(del ju j) 'c' 10)
{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
```

---

### `++gas:ju`

Concatenate

Add each of the key-value pairs in list `b` to jug `a`. The values in `b` are the type the sets in `a` contain. For keys in `b` that exist in `a`, the values will be added to their sets. For keys in `b` that don't exist in `a`, new keys and sets will be added.

#### Accepts

`a` is a `jug`, and is the sample of `+ju`.

`b` is a `(list [p q])`, where:

- `p` is a noun, the type of the keys in `a`.
- `q` is a noun, the type the sets in `a` contain.

#### Produces

A `jug`.

#### Source

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

#### Examples

```
> =j `(jug @t @ud)`(malt ~[['a' (silt ~[1 2 3])] ['b' (silt ~[4 5 6])]])
> j
{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}

> `(jug @t @ud)`(~(gas ju j) ~[['a' 10] ['a' 42] ['b' 999] ['c' 7]])
{[p='b' q={5 6 4 999}] [p='a' q={10 42 1 2 3}] [p='c' q={7}]}
```

---

### `++get:ju`

Retrieve set

Produces a set retrieved from jug `a` using key `b`.

#### Accepts

`a` is a jug, and the sample of `+ju`.

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

#### Produces

A `set`.

#### Source

```hoon
++  get
  |*  b=*
  =+  c=(~(get by a) b)
  ?~(c ~ u.c)
```

#### Examples

```
> =j `(jug @t @ud)`(malt ~[['a' (silt ~[1 2 3])] ['b' (silt ~[4 5 6])]])
> j
{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}

> `(set @ud)`(~(get ju j) 'a')
{1 2 3}

> `(set @ud)`(~(get ju j) 'b')
{5 6 4}

> `(set @ud)`(~(get ju j) 'c')
{}
```

---

### `++has:ju`

Check contents

Computes whether a value `c` exists within the set located at key `b`
with jug `a`, producing a flag.

#### Accepts

`a` is a `jug`, and the sample of `+ju`.

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

`c` is a noun of the same type as the sets in `a` contain.

#### Produces

A `?`.

#### Source

```hoon
++  has
  |*  [b=* c=*]
  ^-  ?
  (~(has in (get b)) c)
```

#### Examples

```
> =j `(jug @t @ud)`(malt ~[['a' (silt ~[1 2 3])] ['b' (silt ~[4 5 6])]])
> j
{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}

> (~(has ju j) 'b' 5)
%.y

> (~(has ju j) 'b' 10)
%.n

> (~(has ju j) 'c' 10)
%.n
```

---

### `++put:ju`

Add key-set pair

Produces jug `a` with `c` added to the set located at key `b`. If `b` isn't a key in `a`, it will be added and a new set created containing `c`.

#### Accepts

`a` is a `jug`.

`b` is a noun, the type of the keys in `a`.

`c` is a noun, the type the sets in `a` contain.

#### Produces

A `jug`.

#### Source

```hoon
++  put
  |*  [b=* c=*]
  ^+  a
  =+  d=(get b)
  (~(put by a) b (~(put in d) c))
```

#### Examples

```
> j
{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}

> `(jug @t @ud)`(~(put ju j) 'c' 5)
{[p='b' q={5 6 4}] [p='a' q={1 2 3}] [p='c' q={5}]}

> `(jug @t @ud)`(~(put ju j) 'a' 4)
{[p='b' q={5 6 4}] [p='a' q={1 2 3 4}]}

> `(jug @t @ud)`(~(put ju j) 'a' 1)
{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
```

---