# Module lists

An implementation of the Erlang/OTP lists interface.

## Description

This module implements a strict subset of the Erlang/OTP lists interface.

## Function Index

all/2 | Evaluates to true iff Fun(E) =:= true, for all E in List. |

any/2 | Evaluates to true iff Fun(E) =:= true, for some E in List. |

delete/2 | Remove E from L. |

duplicate/2 | Duplicate an element. |

filter/2 | Filter a list by a predicate, returning the list of elements for which the predicate is true. |

filtermap/2 | Calls `Fun(Elem)` on successive elements `Elem` of `List1` in order to update or
remove elements from `List1` . |

flatten/1 | recursively flattens elements of L into a single list. |

foldl/3 | Fold over a list of terms, from left to right, applying Fun(E, Accum) to each successive element in List. |

foldr/3 | Fold over a list of terms, from right to left, applying Fun(E, Accum) to each successive element in List. |

foreach/2 | Applies given fun to each list element. |

join/2 | Inserts Sep between every element of List. |

keydelete/3 | Delete the entry in L whose Ith element matches K. |

keyfind/3 | Find the entry in L whose Ith element matches K. |

keymember/3 | Returns true if a Ith element matches K. |

keyreplace/4 | Returns the result of replacing NewTuple for the first element in L with who's Ith element matches K. |

keystore/4 | Searches the list of tuples `TupleList` for a tuple whose `N` th
element compares equal to `Key` , replaces it with `NewTuple` if
found. |

keytake/3 | Searches the list of tuples `TupleList1` for a tuple whose `N` th element
compares equal to `Key` . |

last/1 | Get the last item of a list. |

map/2 | Map a list of terms, applying Fun(E). |

mapfoldl/3 | Combine `map/2` and `foldl/3` in one pass. |

member/2 | Determine whether a term is a member of a list. |

nth/2 | Get the value in a list at position N. |

nthtail/2 | Get the sublist of list L starting after the element N. |

reverse/1 | Erlang/OTP implementation of this function actually handles few simple
cases and calls `lists:reverse/2` for the more generic case. |

reverse/2 | Reverse the elements of L, followed by T. |

search/2 | If there is a Value in List such that Pred(Value) returns true, returns {value, Value} for the first such Value, otherwise returns false. |

seq/2 | Returns a sequence of integers in a specified range. |

seq/3 | Returns a sequence of integers in a specified range incremented by a specified value. |

sort/1 | Returns a sorted list, using `<` operator to determine sort order. |

sort/2 | Returns a sorted list, using Fun(A, B) to determine sort order. |

split/2 | Splits List1 into List2 and List3. |

sublist/2 | Return a sublist made of the first `Len` elements of `List` . |

usort/1 | Returns a unique, sorted list, using `<` operator to determine sort order. |

usort/2 | Returns a unique, sorted list. |

## Function Details

### all/2

```
all(Fun::fun((Elem::term()) -> boolean()), List::list()) -> boolean()
```

`Fun`

: the predicate to evaluate`List`

: the list over which to evaluate elements

returns: true if Fun(E) evaluates to true, for all elements in List

Evaluates to true iff Fun(E) =:= true, for all E in List

### any/2

```
any(Fun::fun((Elem::term()) -> boolean()), List::list()) -> boolean()
```

`Fun`

: the predicate to evaluate`List`

: the list over which to evaluate elements

returns: true if Fun(E) evaluates to true, for at least one in List

Evaluates to true iff Fun(E) =:= true, for some E in List

### delete/2

```
delete(E::term(), L::list()) -> Result::list()
```

`E`

: the member to delete`L`

: the list from which to delete the value

returns: the result of removing E from L, if it exists in L; otherwise, L.

Remove E from L

### duplicate/2

```
duplicate(Count::integer(), Elem) -> [Elem]
```

`Count`

: the number of times to duplicate the element`Elem`

: the element to duplicate

returns: a list made of Elem duplicate Count times

Duplicate an element

### filter/2

```
filter(Pred::fun((Elem::term()) -> boolean()), List::list()) -> list()
```

`Pred`

: the predicate to apply to elements in List`List`

: list

returns: all values in L for which Pred is true.

Filter a list by a predicate, returning the list of elements for which the predicate is true.

### filtermap/2

```
filtermap(Fun, List1) -> List2
```

`Fun = fun((Elem) -> boolean() | {true, Value})`

`List1 = [Elem]`

`List2 = [Elem | Value]`

`Elem = term()`

`Value = term()`

`Fun`

: the filter/map fun`List1`

: the list where given fun will be applied

returns: Returns the result of application of given fun over given list items

Calls `Fun(Elem)`

on successive elements `Elem`

of `List1`

in order to update or
remove elements from `List1`

.

`Fun/1`

must return either a Boolean or a tuple `{true, Value}`

. The function
returns the list of elements for which `Fun`

returns a new value, where a value
of `true`

is synonymous with `{true, Elem}`

.

Example:
`1> lists:filtermap(fun(X) -> case X rem 2 of 0 -> {true, X div 2}; _ -> false end end, [1,2,3,4,5]).`

`[1,2]`

### flatten/1

```
flatten(L::list()) -> list()
```

`L`

: the list to flatten

returns: flattened list

recursively flattens elements of L into a single list

### foldl/3

```
foldl(Fun::fun((Elem::term(), AccIn::term()) -> AccOut::term()), Acc0::term(), List::list()) -> Acc1::term()
```

`Fun`

: the function to apply`Acc0`

: the initial accumulator`List`

: the list over which to fold

returns: the result of folding Fun over L

Fold over a list of terms, from left to right, applying Fun(E, Accum) to each successive element in List

### foldr/3

```
foldr(Fun::fun((Elem::term(), AccIn::term()) -> AccOut::term()), Acc0::term(), List::list()) -> Acc1::term()
```

Equivalent to `foldl(Fun, Acc0, reverse(List))`

.

Fold over a list of terms, from right to left, applying Fun(E, Accum) to each successive element in List

### foreach/2

```
foreach(Fun::fun((Elem::term()) -> term()), List::list()) -> ok
```

`Fun`

: the predicate to evaluate`List`

: the list over which to evaluate elements

returns: ok

Applies given fun to each list element

### join/2

```
join(Sep::any(), List::list()) -> list()
```

`Sep`

: the separator`List`

: list

returns: the result of inserting Sep between every element of List.

Inserts Sep between every element of List.

### keydelete/3

```
keydelete(K::term(), I::pos_integer(), L::list()) -> list()
```

`K`

: the key to match`I`

: the position in the tuple to compare (1..tuple_size)`L`

: the list from which to delete the element

returns: the result of deleting any element in L who’s Ith element matches K

Delete the entry in L whose Ith element matches K.

### keyfind/3

```
keyfind(K::term(), I::pos_integer(), L::[tuple()]) -> tuple() | false
```

`K`

: the key to match`I`

: the position in the tuple to compare (1..tuple_size)`L`

: the list from which to find the element

returns: the tuple in L who’s Ith element matches K; the atom false, otherwise

Find the entry in L whose Ith element matches K.

### keymember/3

```
keymember(K::term(), I::pos_integer(), L::[tuple()]) -> boolean()
```

`K`

: the key to match`I`

: the position in the tuple to compare (1..tuple_size)`L`

: the list from which to find the element

returns: true if there is a tuple in L who’s Ith element matches K; the atom false, otherwise

Returns true if a Ith element matches K.

### keyreplace/4

```
keyreplace(Key::term(), N::pos_integer(), TupleList::[tuple()], NewTuple::tuple()) -> [tuple()]
```

`NewTuple`

: tuple containing the new key to replace param `K`

returns: result of replacing the first element in L who’s Ith element matches K with the contents of NewTuple.

Returns the result of replacing NewTuple for the first element in L with who’s Ith element matches K.

### keystore/4

```
keystore(Key::term(), N::pos_integer(), TupleList::[tuple()], NewTuple::tuple()) -> [tuple()]
```

`Key`

: the key to match`N`

: the position in the tuple to compare (1..tuple_size)`TupleList`

: the list of tuples from which to find the element`NewTuple`

: the tuple to add to the list

returns: An updated TupleList where the first occurrence of `Key`

has been
replaced with `NewTuple`

.

Searches the list of tuples `TupleList`

for a tuple whose `N`

th
element compares equal to `Key`

, replaces it with `NewTuple`

if
found. If not found, append `NewTuple`

to `TupleList`

.

### keytake/3

```
keytake(Key, N, TupleList1) -> {value, Tuple, TupleList2} | false
```

`Key = term()`

`N = pos_integer()`

`TupleList1 = [tuple()]`

`TupleList2 = [tuple()]`

`Tuple = tuple()`

`Key`

: the key to match`N`

: the position in the tuple to compare (1..tuple_size)`TupleList1`

: the list of tuples from which to find the element

returns: `{value, Tuple, TupleList2}`

if such a tuple is found, otherwise `false`

.
`TupleList2`

is a copy of `TupleList1`

where the first
occurrence of `Tuple`

has been removed.

Searches the list of tuples `TupleList1`

for a tuple whose `N`

th element
compares equal to `Key`

.

### last/1

```
last(L::[E, ...]) -> E
```

`L`

: the proper list from which to get the last item

returns: the last item of the list.

Get the last item of a list.

### map/2

```
map(Fun::fun((Elem::term()) -> Out::term()), List::list()) -> OutList::term()
```

`Fun`

: the function to apply`List`

: the list over which to map

returns: the result of mapping over L

Map a list of terms, applying Fun(E)

### mapfoldl/3

```
mapfoldl(Fun::fun((A, Acc) -> {B, Acc}), Acc, List1::[A]) -> {[B], Acc}
```

`Fun`

: the function to apply

returns: the result of mapping and folding Fun over L

Combine `map/2`

and `foldl/3`

in one pass.

### member/2

```
member(E::term(), L::list()) -> boolean()
```

`E`

: the member to search for`L`

: the list from which to get the value

returns: true if E is a member of L; false, otherwise.

Determine whether a term is a member of a list.

### nth/2

```
nth(N::non_neg_integer(), L::list()) -> term()
```

`N`

: the index in the list to get`L`

: the list from which to get the value

returns: the value in the list at position N.

Get the value in a list at position N.

Returns the value at the specified position in the list. The behavior of this function is undefined if N is outside of the {1..length(L)}.

### nthtail/2

```
nthtail(N::non_neg_integer(), L::list()) -> list()
```

`N`

: the index to start the sublist from`L`

: the list from which to extract a tail

returns: a sublist of list starting from position N.

Get the sublist of list L starting after the element N.

The behavior of this function is undefined if N is outside of the {0..length(L)}.

### reverse/1

```
reverse(L::list()) -> list()
```

`L`

: the list to reverse

returns: the elements of L in reverse order

Equivalent to `lists:reverse(L, [])`

.

Erlang/OTP implementation of this function actually handles few simple
cases and calls `lists:reverse/2`

for the more generic case. Consequently,
calling `lists:reverse/1`

without a list or with an improper list of two
elements will fail with a function clause exception on Erlang/OTP and with a
badarg exception with this implementation.

### reverse/2

```
reverse(L::[E, ...], T::[E]) -> [E, ...]
```

`L`

: the list to reverse`T`

: the tail to append to the reversed list

```
reverse(L::nonempty_list(), T::any()) -> maybe_improper_list()
```

`L`

: the list to reverse`T`

: the tail to append to the reversed list

```
reverse(L::[], T) -> T
```

`T = any()`

`L`

: the list to reverse`T`

: the tail to append to the reversed list

returns: the elements of L in reverse order followed by T

Reverse the elements of L, followed by T. If T is not a list or not a proper list, it is appended anyway and the result will be an improper list.

If L is not a proper list, the function fails with badarg.

Following Erlang/OTP tradition, `lists:reverse/1,2`

is a nif. It computes
the length and then allocates memory for the list at once (2 * n terms).

While this is much faster with AtomVM as allocations are expensive with default heap growth strategy, it can consume more memory until the list passed is garbage collected, as opposed to a recursive implementation where the process garbage collect part of the input list during the reversal.

Consequently, tail-recursive implementations calling `lists:reverse/2`

can be as expensive or more expensive in memory than list comprehensions or
non-tail recursive versions depending on the number of terms saved on the
stack between calls.

For example, a non-tail recursive join/2 implementation requires two terms
on stack for each iteration, so when it returns it will use
`n * 3`

(stack) + `n * 4`

(result list)
a tail recursive version will use, on last iteration:
`n * 4`

(reversed list) + n * 4’ (result list)

### search/2

```
search(Pred::fun((Elem::term()) -> boolean()), List::list()) -> {value, Value::term()} | false
```

`Pred`

: the predicate to apply to elements in List`List`

: search

returns: the first {value, Val}, if Pred(Val); false, otherwise.

If there is a Value in List such that Pred(Value) returns true, returns {value, Value} for the first such Value, otherwise returns false.

### seq/2

```
seq(From::integer(), To::integer()) -> list()
```

`From`

: from integer`To`

: to Integer

returns: list of integers from [From..To]

Returns a sequence of integers in a specified range.

This function is equivalent to `lists:seq(From, To, 1)`

.

### seq/3

```
seq(From::integer(), To::integer(), Incr::integer()) -> list()
```

`From`

: from integer`To`

: to Integer`Incr`

: increment value

returns: list of integers `[From, From+Incr, ..., N]`

, where `N`

is the largest integer `<=`

`To`

incremented by `Incr`

Returns a sequence of integers in a specified range incremented by a specified value.

### sort/1

```
sort(List::[T]) -> [T]
```

`List`

: a list

returns: Sorted list, ordered by `<`

Returns a sorted list, using `<`

operator to determine sort order.

### sort/2

```
sort(Fun::fun((T, T) -> boolean()), List::[T]) -> [T]
```

`Fun`

: sort function`List`

: a list

returns: Sorted list, ordered by Fun(A, B) : boolean() such that A “less than” B.

Returns a sorted list, using Fun(A, B) to determine sort order.

### split/2

```
split(N, List1) -> {List2, List3}
```

`N = non_neg_integer()`

`List1 = [T]`

`List2 = [T]`

`List3 = [T]`

`T = term()`

`N`

: elements non negative Integer`List1`

: list to split

returns: Tuple with the two lists

Splits List1 into List2 and List3. List2 contains the first N elements and List3 the remaining elements (the Nth tail).

### sublist/2

```
sublist(List::[Elem], Len::integer()) -> [Elem]
```

`List`

: list to take the sublist from`Len`

: the number of elements to get from List

returns: a list made of the first `Len`

elements of `List`

Return a sublist made of the first `Len`

elements of `List`

.
It is not an error for `Len`

to be larger than the length of `List`

.

### usort/1

```
usort(List::[T]) -> [T]
```

`List`

: a list

returns: Sorted list with duplicates removed, ordered by `<`

Returns a unique, sorted list, using `<`

operator to determine sort order.

**See also:** sort/1.

### usort/2

```
usort(Fun::fun((T, T) -> boolean()), List::[T]) -> [T]
```

`Fun`

: sort function`List`

: a list

returns: Sorted list with duplicates removed, ordered by Fun.

Returns a unique, sorted list.

**See also:** sort/2.