Module lists

Description
Function Index
Function Details

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 Nth 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 Nth 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.