> For the complete documentation index, see [llms.txt](https://docs.urbit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.urbit.org/hoon/stdlib/2j.md).
# 2j: Jar and Jug Logic
Operations for \`+jar\` (map of lists) and jug (map of sets) data structures.
## `+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 `$flag`.
#### 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}]}
```
***
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.urbit.org/hoon/stdlib/2j.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.