# 2b: List Logic

## `+bake` <a href="#bake" id="bake"></a>

**Note:** This function isn't specifically a `+list` function but is included in section 2b of the standard library so is documented here for completeness.

Convert wet `$gate` `.f` to a dry `$gate` by specifying argument mold `.a`.

`+bake` is a wet `$gate` that takes a wet `$gate` and produces a dry `$gate`.

#### Accepts

`.f` is a `$gate`.

`.a` is a `$mold`.

#### Produces

A dry `$gate` whose sample type is `.a`.

#### Source

```hoon
++  bake
  |*  [f=gate a=mold]
  |=  arg=a
  (f arg)
```

#### Examples

```
> =wet-gate |*(a=* [a a])
> (wet-gate 42)
[42 42]
> (wet-gate ['foo' 'bar'])
[['foo' 'bar'] 'foo' 'bar']
> =dry-gate (bake wet-gate @ud)
> (dry-gate 42)
[42 42]
> (dry-gate ['foo' 'bar'])
-need.@ud
-have.[@t @t]
nest-fail
```

***

## `+fand` <a href="#fand" id="fand"></a>

All indices in `+list`.

Produces the indices of all occurrences of `.nedl` in `.hstk` as a `+list` of `$atom`s.

#### Accepts

`.nedl` is a `+list`.

`.hstk` is a `+list`.

#### Produces

A `+list`.

#### Source

```hoon
++  fand
  ~/  %fand
  |=  [nedl=(list) hstk=(list)]
  =|  i=@ud
  =|  fnd=(list @ud)
  |-  ^+  fnd
  =+  [n=nedl h=hstk]
  |-
  ?:  |(?=(~ n) ?=(~ h))
    (flop fnd)
  ?:  =(i.n i.h)
    ?~  t.n
      ^$(i +(i), hstk +.hstk, fnd [i fnd])
    $(n t.n, h t.h)
  ^$(i +(i), hstk +.hstk)
```

#### Examples

```
> (fand ~[3] ~[1 2 3])
~[2]
```

```
> (fand ~[4] ~[1 2 3])
~
```

```
> (fand ~['a'] "cbabab")
~[2 4]
```

```
> (fand "ba" "cbabab")
~[1 3]
```

***

## `+find` <a href="#find" id="find"></a>

First index in `+list`.

Produces the index of the first occurrence of `.nedl` in `.hstk` as the `+unit` of an `$atom`.

#### Accepts

`.nedl` is a `+list`.

`.hstk` is a `+list`.

#### Produces

The `+unit` of an `$atom`.

#### Source

```hoon
++  find
  ~/  %find
  |=  [nedl=(list) hstk=(list)]
  =|  i=@ud
  |-   ^-  (unit @ud)
  =+  [n=nedl h=hstk]
  |-
  ?:  |(?=(~ n) ?=(~ h))
     ~
  ?:  =(i.n i.h)
    ?~  t.n
      `i
    $(n t.n, h t.h)
  ^$(i +(i), hstk +.hstk)
```

#### Examples

```
> (find [3]~ ~[1 2 3])
[~ u=2]
```

```
> (find [4]~ ~[1 2 3])
~
```

```
> (find ['c']~ "cbabab")
[~ u=0]
```

```
> (find "ab" "cbabab")
[~ u=2]
```

```
> (find "bab" "cbabab")
[~ u=1]
```

***

## `+flop` <a href="#flop" id="flop"></a>

Produces the `+list` `.a` in reverse order.

#### Accepts

`.a` is a `+list`.

#### Produces

A `+list`.

#### Source

```hoon
++  flop
  ~/  %flop
  |*  a=(list)
  =>  .(a (homo a))
  ^+  a
  =+  b=`_a`~
  |-
  ?~  a  b
  $(a t.a, b [i.a b])
```

#### Examples

```
> =a [1 2 3 ~]
> (flop a)
~[3 2 1]
```

```
> (flop (flop a))
~[1 2 3]
```

***

## `+gulf` <a href="#gulf" id="gulf"></a>

List from range.

Produces a `+list` composed of each consecutive integer starting from `.a` and ending with `.b`. `.a` and `.b` are themselves included.

#### Accepts

`.a` is an `$atom`.

`.b` is an `$atom`.

#### Produces

A `+list`.

#### Source

```hoon
++  gulf
  |=  [a=@ b=@]
  ?>  (lte a b)
  |-  ^-  (list @)
  ?:(=(a +(b)) ~ [a $(a +(a))])
```

#### Examples

```
> (gulf 1 6)
~[1 2 3 4 5 6]
```

```
> `(list @t)`(gulf 99 106)
<|c d e f g h i j|>
```

***

## `+homo` <a href="#homo" id="homo"></a>

Homogenize.

Produces a `+list` whose type is a fork of all the contained types in the `+list` `.a`. Used when you want to make all the types of the elements of a `+list` the same.

#### Accepts

`.a` is a `+list`.

#### Produces

A `+list`.

#### Source

```hoon
++  homo
  |*  a=(list)
  ^+  =<  $
    |@  ++  $  ?:(*? ~ [i=(snag 0 a) t=$])
    --
  a
```

#### Examples

```
> lyst
[i=1 t=[i=97 t=[i=2 t=[i=98 t=[i=[~ u=10] t=~]]]]]
> (homo lyst)
~[1 97 2 98 [~ u=10]]
```

```
> =a (limo [1 2 3 ~])
> a
[i=1 t=[i=2 t=[i=3 t=~]]]
> (homo a)
~[1 2 3]
```

***

## `+into` <a href="#into" id="into"></a>

Insert item at index.

Accepts a `+list` `.a`, an `$atom` `.b`, and a `$noun` `.c`, producing the `+list` of `.a` with the item `.c` inserted at index `.b`.

#### Accepts

`.a` is a `+list`.

`.b` is an `$atom`.

`.c` is a `$noun`.

#### Produces

The `+list` of `.a` with the item `.c` inserted at index `.b`.

#### Source

```hoon
++  into
  ~/  %into
  |*  [a=(list) b=@ c=*]
  ^+  a
  (weld (scag b a) [c (slag b a)])
```

#### Examples

```
> (into (limo ~[2 3 4]) 1 11)
~[2 11 3 4]
```

***

## `+join` <a href="#join" id="join"></a>

Constructs a new `+list`, placing `.sep` between every element of `.lit`.

#### Accepts

`.sep` is a `$noun`.

`.lit` is a `+list`.

#### Produces

A `+list`.

#### Source

```hoon
++  join
  |*  [sep=* lit=(list)]
  =.  sep  `_?>(?=(^ lit) i.lit)`sep
  ?~  lit  ~
  =|  out=(list _?>(?=(^ lit) i.lit))
  |-  ^+  out
  ?~  t.lit
    (flop [i.lit out])
  $(out [sep i.lit out], lit t.lit)
```

#### Examples

```
> (join ' ' "hoon")
"h o o n"
```

```
> (join 0 `(list @)`~[1 2 3])
~[1 0 2 0 3]
```

***

## `+lent` <a href="#lent" id="lent"></a>

List length.

Produces the length of any `+list` `.a` as an `$atom`.

#### Accepts

`.a` is a `+list`.

#### Produces

An `$atom`.

#### Source

```hoon
++  lent
  ~/  %lent
  |=  a=(list)
  ^-  @
  =+  b=0
  |-
  ?~  a  b
  $(a t.a, b +(b))
```

#### Examples

```
> (lent [1 2 3 4 ~]))
4
```

```
> (lent [1 'a' 2 'b' (some 10) ~])
5
```

***

## `+levy` <a href="#levy" id="levy"></a>

Logical "and" on `+list`.

Computes the `$flag` logical "and" on the results of `$gate` `.b` applied to each individual element in `+list` `.a`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$gate`.

#### Produces

A `$flag`.

#### Source

```hoon
++  levy
  ~/  %levy
  |*  [a=(list) b=$-(* ?)]
  |-  ^-  ?
  ?~  a  &
  ?.  (b i.a)  |
  $(a t.a)
```

#### Examples

```
> =a |=(a=@ (lte a 1))
> (levy `(list @)`[0 1 2 1 ~] a)
%.n
```

```
> =a |=(a=@ (lte a 3))
> (levy `(list @)`[0 1 2 1 ~] a)
%.y
```

***

## `+lien` <a href="#lien" id="lien"></a>

Logical "or" on `+list`.

Computes the `$flag` logical "or" on the results of applying `$gate` `.b` to every element of `+list` `.a`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$gate`.

#### Source

```hoon
++  lien
  ~/  %lien
  |*  [a=(list) b=$-(* ?)]
  |-  ^-  ?
  ?~  a  |
  ?:  (b i.a)  &
  $(a t.a)
```

#### Examples

```
> =a |=(a=@ (gte a 1))
> (lien `(list @)`[0 1 2 1 ~] a)
%.y
```

```
> =a |=(a=@ (gte a 3))
> (lien `(list @)`[0 1 2 1 ~]) a)
%.n
```

***

## `+limo` <a href="#limo" id="limo"></a>

List Constructor.

Turns a null-terminated tuple into a `+list`.

#### Accepts

`.a` is a null-terminated tuple.

#### Produces

A `+list`.

#### Source

```hoon
++  limo
  |*  a=*
  ^+  =<  $
    |@  ++  $  ?~(a ~ ?:(*? [i=-.a t=$] $(a +.a)))
    --
  a
```

#### Examples

```
> (limo [1 2 3 ~])
[i=1 t=[i=2 t=[i=3 t=~]]]
```

***

## `+murn` <a href="#murn" id="murn"></a>

Maybe transform.

Passes each member of `+list` `.a` to `$gate` `.b`, which must produce a `+unit`. Produces a new `+list` with all the results that do not produce `~`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$gate` that produces a `+unit`.

#### Produces

A `+list`.

#### Source

```hoon
++  murn
  ~/  %murn
  |*  [a=(list) b=$-(* (unit))]
  =>  .(a (homo a))
  |-  ^-  (list _?>(?=(^ a) (need (b i.a))))
  ?~  a  ~
  =/  c  (b i.a)
  ?~  c  $(a t.a)
  [+.c $(a t.a)]
```

#### Examples

```
> =a |=(a=@ ?.((gte a 2) ~ (some (add a 10))))
> (murn `(list @)`[0 1 2 3 ~] a)
[i=12 t=[i=13 t=~]]
```

***

## `+oust` <a href="#oust" id="oust"></a>

Remove.

Removes elements from `+list` `.c` beginning at inclusive index `.a`, removing `.b` number of elements.

#### Accepts

`.c` is a `+list`.

#### Produces

A `+list`.

#### Source

```hoon
++  oust
  ~/  %oust
  |*  [[a=@ b=@] c=(list)]
  (weld (scag +<-< c) (slag (add +<-< +<->) c))
```

#### Examples

```
> (oust [4 5] "good day, urbit!")
"good urbit!"
```

```
> (oust [2 2] `(list @)`[1 2 3 4 ~])
~[1 2]
```

***

## `+reap` <a href="#reap" id="reap"></a>

Replicate.

Produces a `+list` containing `.a` copies of `.b`.

#### Accepts

`.a` is an `$atom`.

`.b` is a `$noun`.

#### Produces

A `+list`.

#### Source

```hoon
++  reap
  ~/  %reap
  |*  [a=@ b=*]
  |-  ^-  (list _b)
  ?~  a  ~
  [b $(a (dec a))]
```

#### Examples

```
> (reap 20 %a)
~[%a %a %a %a %a %a %a %a %a %a %a %a %a %a %a %a %a %a %a %a]
```

```
> (reap 5 ~s1)
~[~s1 ~s1 ~s1 ~s1 ~s1]
> `@dr`(roll (reap 5 ~s1) add)
~s5
```

***

## `+rear` <a href="#rear" id="rear"></a>

Last item of `+list`.

Produces the last item in `+list` `.a`, crashing if `.a` is null.

#### Accepts

`.a` is a `+list`.

#### Produces

The type of the last element in `.a`.

#### Source

```hoon
++  rear
  ~/  %rear
  |*  a=(list)
  ^-  _?>(?=(^ a) i.a)
  ?>  ?=(^ a)
  ?:  =(~ t.a)  i.a
  $(a t.a)
```

#### Examples

```
> (rear ~[1 2 3])
3
```

```
> (rear ~)
dojo: hoon expression failed
```

***

## `+reel` <a href="#reel" id="reel"></a>

Right fold.

Moves right to left across a `+list` `.a`, recursively slamming a binary `$gate` `.b` with an element from `.a` and an accumulator, producing the final value of the accumulator.

(To "slam" means to call a `$gate` and give it a sample/samples. In this instance, `.a` is the `+list` of samples that are given to the `$gate` `.b`.)

The initial value of the accumulator is the bunt of `.b`'s second argument (`+<+`). This can occasionally produce undesired behavior (see examples). If you need more control over the initial value, try making use of `$_` and `|:`, or perhaps [`+spin`](#spin) or [`+spun`](#spun).

#### Accepts

`.a` is a `+list`.

`.b` is a binary `$gate`.

#### Produces

The accumulator, which is a `$noun`.

#### Source

```hoon
++  reel
  ~/  %reel
  |*  [a=(list) b=_=>(~ |=([* *] +<+))]
  |-  ^+  ,.+<+.b
  ?~  a
    +<+.b
  (b i.a $(a t.a))
```

#### Examples

```
> (reel `(list @)`[1 2 3 4 5 ~] add)
15
```

```
> (reel `(list @)`[6 3 1 ~] sub)
4
```

```
> (reel `(list @)`[3 6 1 ~] sub)
! subtract-underflow
! exit
```

`+mul`'s default sample is `1`, so calling `+reel` with `+mul` yields the expected behavior:

```
> *mul
1
```

```
> (reel `(list @)`~[1 2 3 4] mul)
24
```

However, if you build a `$gate` that uses `+mul` like so, the sample defaults to `0` since that is the bunt of `@`:

```
> (reel `(list @)`~[1 2 3 4] |=([a=@ b=@] (mul a b)))
0
```

We can fix this with `|:`:

```
> (reel `(list @)`~[1 2 3 4] |:([a=1 b=1] (mul a b)))
24
```

If you check the definition of `+mul`, you'll see that it also utilizes this pattern.

We can check explicitly what sequence of operations `+reel` performs like this:

```
> =f |:  [l='e_l' r='e_r']
      ^-  @t
      :((cury cat 3) '(' l '*' r ')')
> (reel "abcde" f)
'(a*(b*(c*(d*(e*e_r)))))'
```

***

## `+roll` <a href="#roll" id="roll"></a>

Left fold.

Moves left to right across a `+list` `.a`, recursively slamming a binary `$gate` `.b` with an element from the `+list` and an accumulator, producing the final value of the accumulator.

(To "slam" means to call a `$gate` and give it a sample/samples. In this instance, `.a` is the `+list` of samples that are given to the `$gate` `.b`.)

The initial value of the accumulator is `.b`'s second argument (`+<+`). This can occasionally produce undesired behavior (see examples). If you need more control over the initial value, try making use of `$_` and `|:`, or perhaps [`+spin`](#spin) or [`+spun`](#spun).

#### Accepts

`.a` is a `+list`.

`.b` is a binary `$gate`.

#### Produces

The accumulator, which is a `$noun`.

#### Source

```hoon
++  roll
  ~/  %roll
  |*  [a=(list) b=_=>(~ |=([* *] +<+))]
  |-  ^+  ,.+<+.b
  ?~  a
    +<+.b
  $(a t.a, b b(+<+ (b i.a +<+.b)))
```

#### Examples

```
> (roll `(list @)`[1 2 3 4 5 ~] add)
q=15
```

```
> (roll `(list @)`[6 3 1 ~] sub)
! subtract-underflow
! exit
```

```
> (roll `(list @)`[1 3 6 ~] sub)
q=4
```

`+mul`'s default sample is `1`, so calling `+roll` with `+mul` yields the expected behavior:

```
> *mul
1
```

```
> (roll `(list @)`~[1 2 3 4] mul)
24
```

However, if you build a `$gate` that uses `+mul` like so, the sample defaults to `0` since that is the bunt of `@`:

```
> (roll `(list @)`~[1 2 3 4] |=([a=@ b=@] (mul a b)))
0
```

We can fix this with `|:`:

```
> (roll `(list @)`~[1 2 3 4] |:([a=1 b=1] (mul a b)))
24
```

If you check the definition of `+mul`, you'll see that it also utilizes this pattern.

We can check explicitly what sequence of operations `+roll` performs like this:

```
> =f |:  [l='e_l' r='e_r']
      ^-  @t
      :((cury cat 3) '(' l '*' r ')')
> (roll "abcde" f)
'(e*(d*(c*(b*(a*e_r)))))
```

This is in contrast to what one might expect:

```
> =foldl
    |*  [l=(list) f=$-([* *] *)]
    ^-  f
    ?~  l  +<-.f
    %=  $
      +<-.f  (f +<-.f i.l)
      l      t.l
      ==
> (foldl "abcde" f)
'(((((e_l*a)*b)*c)*d)*e)'
```

***

## `+scag` <a href="#scag" id="scag"></a>

Prefix.

Accepts an `$atom` `.a` and `+list` `.b`, producing the first `.a` elements of the front of the `+list`.

#### Accepts

`.a` is an `$atom`.

`.b` is a `+list`.

#### Produces

A `+list` of the same type as `.b`.

#### Source

```hoon
++  scag
  ~/  %scag
  |*  [a=@ b=(list)]
  |-  ^+  b
  ?:  |(?=(~ b) =(0 a))  ~
  [i.b $(b t.b, a (dec a))]
```

#### Examples

```
> (scag 2 `(list @)`[1 2 3 4 ~])
[i=1 t=~[2]]
```

```
> (scag 10 `(list @)`[1 2 3 4 ~])
[i=1 t=~[2 3 4]]
```

***

## `+skid` <a href="#skid" id="skid"></a>

Separate.

Separates a `+list` `.a` into two `+list`s: those elements of `.a` who produce `%.y` when slammed to `$gate` `.b`, and those who produce `%.n`.

(To "slam" means to call a `$gate` and give it a sample/samples. In this instance, `.a` is the `+list` of samples that are given to the `$gate` `.b`.)

#### Accepts

`.a` is a `+list`.

`.b` is a `$gate` that accepts one argument and produces a `$flag`.

#### Produces

A cell of two `+list`s.

#### Source

```hoon
++  skid
  ~/  %skid
  |*  [a=(list) b=$-(* ?)]
  |-  ^+  [p=a q=a]
  ?~  a  [~ ~]
  =+  c=$(a t.a)
  ?:((b i.a) [[i.a p.c] q.c] [p.c [i.a q.c]])
```

#### Examples

```
> =a |=(a=@ (gth a 1))
> (skid `(list @)`[0 1 2 3 ~] a)
[p=[i=2 t=~[3]] q=[i=0 t=~[1]]]
```

***

## `+skim` <a href="#skim" id="skim"></a>

Filter.

Cycles through the members of a `+list` `.a`, passing them to a `$gate` `.b` and producing a `+list` of all of the members that produce `%.y`. Inverse of `+skip`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$gate` that accepts one argument and produces a `$flag`.

#### Produces

A `+list`.

#### Source

```hoon
++  skim
  ~/  %skim
  |*  [a=(list) b=$-(* ?)]
  |-
  ^+  a
  ?~  a  ~
  ?:((b i.a) [i.a $(a t.a)] $(a t.a))
```

#### Examples

```
> =a |=(a=@ (gth a 1))
> (skim `(list @)`[0 1 2 3 ~] a)
[i=2 t=~[3]]
```

***

## `+skip` <a href="#skip" id="skip"></a>

Except.

Cycles through the members of `+list` `.a`, passing them to a `$gate` `.b`. Produces a `+list` of all of the members that produce `%.n`. Inverse of `+skim`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$gate` that accepts one argument and produces a `$flag`.

#### Produces

A `+list` of the same type as `.a`.

#### Source

```hoon
++  skip
  ~/  %skip
  |*  [a=(list) b=$-(* ?)]
  |-
  ^+  a
  ?~  a  ~
  ?:((b i.a) $(a t.a) [i.a $(a t.a)])
```

#### Examples

```
> =a |=(a=@ (gth a 1))
> (skip `(l)`[0 1 2 3 ~]) a)
[i=0 t=[i=1 t=~]]
```

***

## `+slag` <a href="#slag" id="slag"></a>

Suffix.

Accepts an `$atom` `.a` and `+list` `.b`, producing the remaining elements from `.b` starting at `.a`.

#### Accepts

`.a` is an `$atom`.

`.b` is a `+list`.

#### Produces

A `+list` of the same type as `.b`.

#### Source

```hoon
++  slag
  ~/  %slag
  |*  [a=@ b=(list)]
  |-  ^+  b
  ?:  =(0 a)  b
  ?~  b  ~
  $(b t.b, a (dec a))
```

#### Examples

```
> (slag 2 (limo [1 2 3 4 ~]))
[i=3 t=[i=4 t=~]]
> (slag 1 (limo [1 2 3 4 ~]))
[i=2 t=[i=3 t=[i=4 t=~]]]
```

***

## `+snag` <a href="#snag" id="snag"></a>

Index.

Accepts an `$atom` `.a` and a `+list` `.b`, producing the element at the index of `.a`and failing if the `+list` is null. `+list`s are 0-indexed.

#### Accepts

`.a` is an `$atom`.

`.b` is a `+list`.

#### Produces

Produces an element of `.b`, or crashes if no element exists at that index.

#### Source

```hoon
++  snag
  ~/  %snag
  |*  [a=@ b=(list)]
  |-  ^+  ?>(?=(^ b) i.b)
  ?~  b
    ~_  leaf+"snag-fail"
    !!
  ?:  =(0 a)  i.b
  $(b t.b, a (dec a))
```

#### Examples

```
> (snag 2 "asdf")
'd'
```

```
> (snag 0 `(list @ud)`~[1 2 3 4])
1
```

***

## `+snap` <a href="#snap" id="snap"></a>

Replace item at index.

Accepts a `+list` `.a`, an `$atom` `.b`, and a `$noun` `.c`, producing the `+list` of `.a` with the item at index `.b` replaced with `.c`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$atom`.

`.c` is a `$noun`.

#### Produces

The `+list` of `.a` with the item at index `.b` replaced with `.c`.

#### Source

```hoon
++  snap
  ~/  %snap
  |*  [a=(list) b=@ c=*]
  ^+  a
  (weld (scag b a) [c (slag +(b) a)])
```

#### Examples

```
> (snap (limo ~[2 3 4]) 1 11)
~[2 11 4]
```

***

## `+snip` <a href="#snip" id="snip"></a>

Drop tail off `+list`.

Removes the last element from `+list` `.a`.

#### Accepts

`.a` is a `+list`.

#### Produces

A `+list`.

#### Source

```hoon
++  snip
  ~/  %snip
  |*  a=(list)
  ^+  a
  ?~  a  ~
  ?:  =(~ t.a)  ~
  [i.a $(a t.a)]
```

#### Examples

```
> `tape`(snip "foobar")
"fooba"
```

```
> (snip ~)
~
```

***

## `+snoc` <a href="#snoc" id="snoc"></a>

Append.

Accepts a `+list` `.a` and a `$noun` `.b`, producing the `+list` of `.b` appended to `.a`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$noun`.

#### Produces

Produces a `+list` of `.b` appended to `.a`.

#### Source

```hoon
++  snoc
  |*  [a=(list) b=*]
  (weld a ^+(a [b]~))
```

#### Examples

```
> `tape`(zing (snoc `(list tape)`~["a" "bc" "def"] "g"))
"abcdefg"
```

```
> (snoc `(list @ud)`~[1 2 3] 4)
~[1 2 3 4]
```

***

## `+sort` <a href="#sort" id="sort"></a>

Quicksort.

Quicksort: accepts a `+list` `.a` and a `$gate` `.b` which accepts two `$noun`s and produces a `$flag`. `+sort` then produces a `+list` of the elements of `.a`, sorted according to `.b`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$gate` that accepts two `$noun`s and produces a `$flag`.

#### Produces

A `+list`

#### Source

```hoon
++  sort  !.
  ~/  %sort
  |*  [a=(list) b=$-([* *] ?)]
  =>  .(a ^.(homo a))
  |-  ^+  a
  ?~  a  ~
  =+  s=(skid t.a |:(c=i.a (b c i.a)))
  %+  weld
    $(a p.s)
  ^+  t.a
  [i.a $(a q.s)]
```

#### Examples

```
> (sort `(list @)`[0 1 2 3 ~] gth)
~[3 2 1 0]
```

***

## `+spin` <a href="#spin" id="spin"></a>

Gate to `+list`, with state.

Accepts a `+list` `.a`, some state `.b`, and a `$gate` `.c`. `.c` is called with a tuple (the head is an element of `.a` and the tail is the state `.b`), and should produce a tuple of the transformed element and the (potentially modified) state `.b`. Produces a cell where the first element is a `+list` of the transformed elements of `.a`, and the second element is the final value of `.b`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$noun`.

`.c` is a `$gate`.

#### Produces

A pair of a `+list` and a `$noun`.

#### Source

```hoon
++  spin
  ~/  %spin
  |*  [a=(list) b=* c=_|=(^ [** +<+])]
  =>  .(c `$-([_?>(?=(^ a) i.a) _b] [_-:(c) _b])`c)
  =/  acc=(list _-:(c))  ~
  |-  ^-  (pair _acc _b)
  ?~  a
    [(flop acc) b]
  =^  res  b  (c i.a b)
  $(acc [res acc], a t.a)
```

#### Examples

Trivial example; does nothing with the state.

```
> %^  spin  (limo ~[4 5 6])
    0
  |=([n=@ a=@] [n a])
[p=~[4 5 6] q=0]
```

Form a pair with `.p` as the index and `.q` as the `+list` element.

```
> %^  spin  (limo ~[4 5 6])
    0
  |=([n=@ a=@] [`(pair)`[a n] +(a)])
[p=~[[p=0 q=4] [p=1 q=5] [p=2 q=6]] q=3]
```

Create 10 random numbers below 10.

```
> %^  spin  (reap 10 0)
    ~(. og eny)
  |=([n=@ rng=_og] (rads:rng 10))
[p=~[7 8 6 0 1 5 4 7 9 3] q=<4.rvi {a/@uvJ <51.qyl 129.pdd 41.mac 1.ane $141>}>]
```

#### Discussion

The expression `(~(rads og eny) 2)` creates a random number less than 2, seeding the random number generator with entropy (`.eny`). The head of the product is the random number, the tail is the continuation of the random number generator.

***

## `+spun` <a href="#spun" id="spun"></a>

Gate to `+list`, with state.

Accepts a `+list` `.a` and a `$gate` `.b`. Unlike [`+spin`](#spin), `+spun` doesn't have a `.c` parameter. Instead, it derives its intenral state by bunting the tail of the sample of `.b`.

Produces a `+list` with `.b` applied to each element of `.a`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$gate`.

#### Produces

A `+list`.

#### Source

```hoon
++  spun
  ~/  %spun
  |*  [a=(list) b=_|=(^ [** +<+])]
  p:(spin a +<+.b b)
```

#### Examples

`.p` as the index and `.q` as the `+list` element.

```
> %+  spun  (limo ~[4 5 6])
  |=([n=@ a=@] [`(pair)`[a n] +(a)])
~[[p=0 q=4] [p=1 q=5] [p=2 q=6]]
```

Joins two `+list`s into a `+list` of pairs.

```
> =l (limo ~[7 8 9])
> %+  spun  (limo ~[4 5 6])
  |=([n=@ a=@] [`(pair)`[(snag a l) n] +(a)])
~[[p=7 q=4] [p=8 q=5] [p=9 q=6]]
```

***

## `+swag` <a href="#swag" id="swag"></a>

Infix.

Similar to `substr()` in Javascript: extracts a string infix, beginning at inclusive index `.a`, producing `.b` number of characters.

#### Accepts

`.a` is an `$atom`.

`.b` is an `$atom`.

`.c` is a `+list`.

#### Produces

A `+list` of the same type as `.c`.

#### Source

```hoon
++  swag
  |*  [[a=@ b=@] c=(list)]
  (scag +<-> (slag +<-< c))
```

#### Examples

```
> (swag [2 5] "roly poly")
"ly po"
```

```
> (swag [2 2] (limo [1 2 3 4 ~]))
[i=3 t=[i=4 t=~]]
```

***

## `+turn` <a href="#turn" id="turn"></a>

Gate to `+list`.

Accepts a `+list` `.a` and a `$gate` `.b`. Produces a `+list` with the `$gate` applied to each element of the original `+list`.

#### Accepts

`.a` is a `+list`.

`.b` is a `$gate`.

#### Produces

A `+list`.

#### Source

```hoon
++  turn
  ~/  %turn
  |*  [a=(list) b=gate]
  =>  .(a (homo a))
  ^-  (list _?>(?=(^ a) (b i.a)))
  |-
  ?~  a  ~
  [i=(b i.a) t=$(a t.a)]
```

#### Examples

```
> (turn (limo [104 111 111 110 ~]) @t)
<|h o o n|>
```

```
> =a |=(a=@ (add a 4))
> (turn (limo [1 2 3 4 ~]) a)
~[5 6 7 8]
```

#### Discussion

`+turn` is Hoon's version of `map` in Haskell.

***

## `+weld` <a href="#weld" id="weld"></a>

Concatenate.

Concatenate two `+list`s `.a` and `.b`.

#### Accepts

`.a` and `.b` are `+list`s.

#### Source

```hoon
++  weld
  ~/  %weld
  |*  [a=(list) b=(list)]
  =>  .(a ^.(homo a), b ^.(homo b))
  |-  ^+  b
  ?~  a  b
  [i.a $(a t.a)]
```

#### Examples

```
> (weld "urb" "it")
"urbit"
```

```
> (weld (limo [1 2 ~]) (limo [3 4 ~]))
~[1 2 3 4]
```

***

## `+welp` <a href="#welp" id="welp"></a>

Perfect weld.

Concatenate two `+list`s `.a` and `.b` without losing their type information to homogenization.

#### Accepts

`.a` is a `+list`.

`.b` is a `+list`.

#### Produces

A `+list`.

#### Source

```hoon
++  welp
  ~/  %welp
  =|  [* *]
  |@
  ++  $
    ?~  +<-
      +<-(. +<+)
    +<-(+ $(+<- +<->))
  --
```

#### Examples

```
> (welp "foo" "bar")
"foobar"
```

```
> (welp ~[60 61 62] ~[%a %b %c])
[60 61 62 %a %b %c ~]
```

```
> ? (welp ~[60 61 62] ~[%a %b %c])
  [@ud @ud @ud %a %b %c %~]
[60 61 62 %a %b %c ~]
```

```
> (welp [sa+1 so+2 ~] si=3)
[[%sa 1] [%so 2] si=3]
```

***

## `+zing` <a href="#zing" id="zing"></a>

Turns a `+list` of `+list`s into a single `+list` by promoting the elements of each sublist into the higher.

#### Accepts

A `+list` of `+list`s.

#### Produces

A `+list`.

#### Source

```hoon
++  zing
  ~/  %zing
  =|  *
  |@
  ++  $
    ?~  +<
      +<
    (welp +<- $(+< +<+))
  --
```

#### Examples

```
> (zing (limo [(limo ['a' 'b' 'c' ~]) (limo ['e' 'f' 'g' ~]) (limo ['h' 'i' 'j' ~]) ~]))
~['a' 'b' 'c' 'e' 'f' 'g' 'h' 'i' 'j']
```

```
> (zing (limo [(limo [1 'a' 2 'b' ~]) (limo [3 'c' 4 'd' ~]) ~]))
~[1 97 2 98 3 99 4 100]
```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.urbit.org/hoon/stdlib/2b.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.