# lists

### MODULE

lists

### MODULE SUMMARY

List Processing Functions

### DESCRIPTION

This module contains functions for list processing. The functions are organized in two groups: those in the first group perform a particular operation on one ore several lists, whereas those in the second group perform use a user-defined function (given as the first argument) to perform an operation on one list.

### EXPORTS

`append(ListOfLists) -> List1`

Types:

`ListOfLists = [List]`
`List = List1 = [term()]`

Returns a list in which all the sub-lists of `ListOfLists` have been appended. For example:

    > lists:append([[1, 2, 3], [a, b], [4, 5, 6]]).
    [1, 2, 3, a, b, 4, 5, 6]

The result need not be a proper list. The last parameter may be of any datatype and will be the tail in the resulting list. An example:

    > lists:append([[a,b],c]).
    [a,b|c]

The atom `c` will be the tail of the list and the list is therefore not proper (a proper list ends with `[]`).

As a parameter of `[]` is ignored this example is also valid (although probably useless):

    lists:append([[],d]).

`append(List1, List2) -> List3`

Types:

`List1 = List2 = List3 = [term()]`

Returns a new list `List3` which is made from the elements of `List1` followed by the elements of `List2`. For example:

    > lists:append("abc", "def").
    "abcdef".

`lists:append(A,B)` is equivalent to `A ++ B`.

The behaviour regarding inproper lists is identical to the behaviour of `lists:append/1`

`concat(Things) -> string()`

Types:

`Things = [Thing]`
`Thing = atom() | integer() | float() | string()`

Concatenates the ASCII list representation of the elements of `Things`. The elements of `Things` can be atoms, integers, floats or strings.

    > lists:concat([doc, '/', file, '.', 3]).
    "doc/file.3"

`delete(Element, List1) -> List2`

Types:

`List1 = list2 = [Element]`
`Element = term()`

Returns a copy of `List1`, but the first occurrence of `Element`, if present, is deleted.

`duplicate(N, Element) -> List`

Types:

`N = int()`
`List = [Element]`
`Element = term()`

Returns a list which contains N copies of the term `Element`.

| `N` must be an integer >= 0. For example:

    > lists:duplicate(5, xx).
    [xx, xx, xx, xx, xx]

`flatlength(DeepList) -> int()`

Equivalent to `length(flatten(DeepList))`, but more efficient.

`flatten(DeepList) -> List`

Types:

`DeepList = [term() | DeepList]`

Returns a flattened version of `DeepList`.

`flatten(DeepList, Tail) -> List`

Types:

`DeepList = [term() | DeepList]`
`Tail = [term()]`

Returns a flattened version of `DeepList` with the tail `Tail` appended.

`keydelete(Key, N, TupleList1) -> TupleList2`

Types:

`TupleList1 = TupleList2 = [tuple()]`
`N = int()`
`Key = term()`

Returns a copy of `TupleList1` where the first occurrence of a tuple whose `N`th element is `Key` is deleted, if present.

`keymember(Key, N, TupleList) -> bool()`

Types:

`TupleList = [tuple()]`
`N = int()`
`Key = term()`

Searches the list of tuples `TupleList` for a tuple whose `N`th element is `Key`.

`keymerge(N, List1, List2)`

Types:

`N = int()`
`List1 = List2 = [tuple()]`

Returns the sorted list formed by merging `List1` and `List2`. The merge is performed on the `N`th element of each tuple. Both `List1` and `List2` must be key-sorted prior to evaluating this function; otherwise the order of the elements in the result will be undefined. When elements in the input lists compare equal, elements from `List1` are picked before elements from `List2`.

`keyreplace(Key, N, TupleList1, NewTuple) -> TupleList2`

Types:

`Key = term()`
`N = int()`
`TupleList1 = TupleList2 = [tuple()]`
`NewTuple = tuple()`

Returns a list of tuples. In this list, a tuple is replaced by the tuple `NewTuple`. This tuple is the first tuple in the list where the element number `N` is equal to `Key`.

`keysearch(Key, N, TupleList) -> Result`

Types:

`TupleList = [tuple()]`
`N = int()`
`Key = term()`
`Result = {value, tuple()} | false`

Searches the list of the tuples `TupleList` for `Tuple` whose `N`th element is `Key`. Returns `{value, Tuple}` if such a tuple is found, or `false` if no such tuple is found.

`keysort(N, List1) -> List2`

Types:

`N = int()`
`List1 = List2 = [tuple()]`

Returns a list containing the sorted elements of `List1`. `TupleList1` must be a list of tuples, and the sort is performed on the `N`th element of the tuple. The sort is stable.

`last(List) -> Element`

Types:

`List = [Element]`
`Element = term()`

Returns the last element in `List`.

`max(List) -> Max`

Types:

`List = [Element]`
`Element = Max = term()`

Returns the maximum element of `List`.

`member(Element, List) -> bool()`

Types:

`List = [Element]`
`Element = term()`

Returns `true` if `Element` is contained in the list `List`, otherwise `false`.

`merge(ListOfLists) -> List1`

Types:

`ListOfLists = [List]`
`List = List1 = [term()]`

Returns the sorted list formed by merging all the sub-lists of `ListOfLists`. All sub-lists must be sorted prior to evaluating this function.

`merge(List1, List2) -> List3`

Types:

`List1 = List2 = List3 = [term()]`

Returns the sorted list formed by merging `List1` and `List2`. Both `List1` and `List2` must be sorted prior to evaluating this function.

`merge(Fun, List1, List2) -> List`

Types:

`List = List1 = List2 = [Element]`
`Fun = fun(Element, Element) -> bool()`
`Element = term()`

Returns the sorted list formed by merging `List1` and `List2`. Both `List1` and `List2` must be sorted according to the ordering function `Fun` prior to evaluating this function. `Fun(A,B)` should return `true` if `A` comes before `B` in the ordering, `false` otherwise.

`merge3(List1, List2, List3) -> List4`

Types:

`List1 = List2 = List3 = List4 = [term()]`

Returns the sorted list formed by merging `List1`, `List2` and `List3`. All of `List1`, `List2` and `List3` must be sorted prior to evaluating this function.

`min(List) -> Min`

Types:

`List = [Element]`
`Element = Max = term()`

Returns the minimum element of `List`.

`nth(N, List) -> Element`

Types:

`N = int()`
`List = [Element]`
`Element = term()`

Returns the `N`th element of the `List`. For example:

    > lists:nth(3, [a, b, c, d, e]).
    c

`nthtail(N, List1) -> List2`

Types:

`N = int()`
`List1 = List2 = [Alpha]`

Returns the `N`th tail of `List`. For example:

    > lists:nthtail(3, [a, b, c, d, e]).
    [d, e]

`prefix(List1, List2) -> bool()`

Types:

`List1 = List2 = [term()]`

Returns `true` if `List1` is a prefix of `List2`, otherwise `false`.

`reverse(List1) -> List2`

Types:

`List1 = List2 = [term()]`

Returns a list with the top level elements in `List1` in reverse order.

`reverse(List1, List2) -> List3`

Types:

`List1 = List2 = List3 = [term()]`

Returns a list where `List1` has been reversed and appended to the beginning of `List2`. Equivalent to `reverse(List1) ++ List2`. For example:

    > lists:reverse([1, 2, 3, 4], [a, b, c]).
    [4, 3, 2, 1, a, b, c]

`seq(From, To) -> [int()]`
`seq(From, To, Incr) -> [int()]`

Types:

`From = To = Incr = int()`

Returns a sequence of integers which starts with `From` and contains the successive results of adding `Incr` to the previous element, until `To` has been reached or passed (in the latter case, `To` is not an element of the sequence). If `To-From` has a different sign from `Incr`, or if `Incr` = 0 and `From` is different from `To`, an error is signalled (this implies that the result is never an empty list - the first element is always `From`).

`seq(From, To)` is equivalent to `seq(From, To, 1)`.

Examples:

    > lists:seq(1, 10).
    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

    > lists:seq(1, 20, 3).
    [1, 4, 7, 10, 13, 16, 19]

    > lists:seq(1, 1, 0).
    [1]

`sort(List1) -> List2`

Types:

`List1 = List2 = [term()]`

Returns a list which contains the sorted elements of `List1`.

`sort(Fun, List1) -> List2`

Types:

`List1 = List2 = [Element]`
`Fun = fun(Element, Element) -> bool()`
`Element = term()`

Returns a list which contains the sorted elements of `List1`, according to the ordering function `Fun`. `Fun(A,B)` should return `true` if `A` comes before `B` in the ordering, `false` otherwise.

`sublist(List, N) -> List1`

Types:

`List1 = List2 = [term()]`
`N = int()`

Returns the first `N` elements of `List`. It is not an error for `N` to exceed the length of the list when `List` is a proper list - in that case the whole list is returned.

`sublist(List1, Start, Length) -> List2`

Types:

`List1 = List2 = [term()]`
`Start = End = int()`

Returns the sub-list of `List` starting at `Start` of length `Length`. Terminates with a runtime failure if `Start` is not in `List`, but a sub-list of a length less than `Length` is accepted. `Start` is considered to be in `List` if `Start` >= 1 and `Start` <= `length(List)+1`.

`subtract(List1, List2) -> List3`

Types:

`List1 = List2 = List3 = [term()]`

Returns a new list `List3` which is a copy of `List1`, subjected to the following procedure: for each element in `List2`, its first occurrence in `List1` is removed. For example:

    > lists:subtract("123212", "212").
    "312".

`lists:subtract(A,B)` is equivalent to `A -- B`.

`suffix(List1, List2) -> bool()`

Returns `true` if `List1` is a suffix of `List2`, otherwise `false`.

`sum(List) -> number()`

Types:

`List = [number()]`

Returns the sum of the elements in `List`.

`ukeymerge(N, List1, List2)`

Types:

`N = int()`
`List1 = List2 = [tuple()]`

Returns the sorted list formed by merging `List1` and `List2` while removing consecutive duplicates. The merge is performed on the `N`th element of each tuple. Both `List1` and `List2` must be key-sorted prior to evaluating this function; otherwise the order of the elements in the result will be undefined. When elements in the input lists compare equal, elements from `List1` are picked before elements from `List2`.

`ukeysort(N, List1) -> List2`

Types:

`N = int()`
`List1 = List2 = [tuple()]`

Returns a list containing the sorted elements of `List1` with consecutive duplicates removed. `TupleList1` must be a list of tuples, and the sort is performed on the `N`th element of the tuple. The sort is stable.

`umerge(ListOfLists) -> List1`

Types:

`ListOfLists = [List]`
`List = List1 = [term()]`

Returns the sorted list formed by merging all the sub-lists of `ListOfLists` while removing duplicates. All sub-lists must be sorted and contain no duplicates prior to evaluating this function.

`umerge(List1, List2) -> List3`

Types:

`List1 = List2 = List3 = [term()]`

Returns the sorted list formed by merging `List1` and `List2` while removing duplicates. Both `List1` and `List2` must be sorted and contain no duplicates prior to evaluating this function.

`umerge(Fun, List1, List2) -> List`

Types:

`List = List1 = List2 = [Element]`
`Fun = fun(Element, Element) -> bool()`
`Element = term()`

Returns the sorted list formed by merging `List1` and `List2` while removing consecutive duplicates. Both `List1` and `List2` must be sorted according to the ordering function `Fun` prior to evaluating this function. `Fun(A,B)` should return `true` if `A` comes before `B` in the ordering, `false` otherwise.

`umerge3(List1, List2, List3) -> List4`

Types:

`List1 = List2 = List3 = List4 = [term()]`

Returns the sorted list formed by merging `List1`, `List2` and `List3` while removing duplicates. All of `List1`, `List2` and `List3` must be sorted and contain no duplicates prior to evaluating this function.

`usort(List1) -> List2`

Types:

`List1 = List2 = [term()]`

Returns a list which contains the sorted elements of `List1` without duplicates.

`usort(Fun, List1) -> List2`

Types:

`List1 = List2 = [Element]`
`Fun = fun(Element, Element) -> bool()`
`Element = term()`

Returns a list which contains the sorted elements of `List1` with consecutive duplicates removed, according to the ordering function `Fun`. `Fun(A,B)` should return `true` if `A` comes before `B` in the ordering, `false` otherwise.

`all(Pred, List) -> bool()`

Types:

`Pred = fun(A) -> bool()`
`List = [A]`

Returns `true` if all elements X in `List` satisfy `Pred(X)`.

`any(Pred, List) -> bool()`

Types:

`Pred = fun(Element) -> bool()`
`List = [Element]`
`Element = term()`

Returns `true` if any of the elements in `List` satisfies `Pred`.

`dropwhile(Pred, List1) -> List2`

Types:

`Pred = fun(A) -> bool()`
`List1 = List2 = [A]`

Drops elements `X` from `List1` while `Pred(X)` is `true` and returns the remaining list.

`filter(Pred, List1) -> List2`

Types:

`Pred = fun(A) -> bool()`
`List1 = List2 = [A]`

`List2` is a list of all elements `X` in `List1` for which `Pred(X)` is `true`.

`flatmap(Function, List1) -> Element`

Types:

`Function = fun(A) -> B`
`List1 = [A]`
`Element = [B]`

`flatmap` behaves as if it had been defined as follows:

    flatmap(Func, List) ->
        append(map(Func, List))

`foldl(Function, Acc0, List) -> Acc1`

Types:

`Function = fun(A, AccIn) -> AccOut`
`List = [A]`
`Acc0 = Acc1 = AccIn = AccOut = term()`

`Acc0` is returned if the list is empty. For example:

    > lists:foldl(fun(X, Sum) -> X + Sum end, 0, [1,2,3,4,5]).
    15
    > lists:foldl(fun(X, Prod) -> X * Prod end, 1, [1,2,3,4,5]).
    120

`foldr(Function, Acc0, List) -> Acc1`

Types:

`Function = fun(A, AccIn) -> AccOut`
`List = [A]`
`Acc0 = Acc1 = AccIn = AccOut = term()`

Calls `Function` on successive elements of `List` together with an extra argument `Acc` (short for accumulator). `Function` must return a new accumulator which is passed to the next call. `Acc0` is returned if the list is empty. `foldr` differs from `foldl` in that the list is traversed "bottom up" instead of "top down". `foldl` is tail recursive and would usually be preferred to `foldr`.

`foreach(Function, List) -> void()`

Types:

`Function = fun(A) -> void()`
`List = [A]`

Applies the function `Function` to each of the elements in `List`. This function is used for its side effects and the evaluation order is defined to be the same as the order of the elements in the list.

`map(Func, List1) -> List2`

Types:

`Func = fun(A) -> B`
`List1 = [A]`
`List2 = [B]`

`map` takes a function from `A`s to `B`s, and a list of `A`s and produces a list of `B`s by applying the function to every element in the list. This function is used to obtain the return values. The evaluation order is implementation dependent.

`mapfoldl(Function, Acc0, List1) -> {List2, Acc}`

Types:

`Function = fun(A, AccIn) -> {B, AccOut}`
`Acc0 = Acc1 = AccIn = AccOut = term()`
`List1 = [A]`
`List2 = [B]`

`mapfold` combines the operations of `map` and `foldl` into one pass. For example, we could sum the elements in a list and double them at the same time:

    > lists:mapfoldl(fun(X, Sum) -> {2*X, X+Sum} end,
                     0, [1,2,3,4,5]).
    {[2,4,6,8,10],15}

`mapfoldr(Function, Acc0, List1) -> {List2, Acc}`

Types:

`Function = fun(A, AccIn) -> {B, AccOut}`
`Acc0 = Acc1 = AccIn = AccOut = term()`
`List1 = [A]`
`List2 = [B]`

`mapfold` combines the operations of `map` and `foldr` into one pass.

`splitwith(Pred, List) -> {List1, List2}`

Types:

`Pred = fun(A) -> bool()`
`List = List1 = List2 = [A]`

Partitions `Lists` into `List1` and `List2` according to `Pred`.

`splitwith` behaves as if it had been defined as follows:

    splitwidth(Pred, List) ->
              {takewhile(Pred, List), dropwhile(Pred, List)}.

Note also that `List == List1 ++ List2`.

`takewhile(Pred, List1) -> List2`

Types:

`Pred = fun(A) -> bool()`
`List1 = List2 = [A]`

Returns the longest prefix of `List1` for which all elements `X` in `List1` satisfy `Pred(X)`.

### Relics

Some of the exported functions in `lists.erl` are not documented. In particular, this applies to a number of `maps` and `folds` which have an extra argument for environment passing. These functions are no longer needed because Erlang 4.4 and later releases have Funs.

| Any undocumented functions in lists should not be used.

### AUTHORS

Joe Armstrong - support@erlang.ericsson.se
Robert Virding - support@erlang.ericsson.se

stdlib 1.10.1
Copyright © 1991-2002 Ericsson Utvecklings AB