main-apidocs-erlang-estdlib-lists.md
An implementation of the Erlang/OTP lists interface.
This module implements a strict subset of the Erlang/OTP lists interface.
| 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. |
| append/1 | Returns a list in which all the sublists of ListOfLists have been appended. |
| append/2 | Returns a new list List3, which is made from the elements of List1 followed by the elements of List2. |
| delete/2 | Remove E from L. |
| droplast/1 | Drop the last element of a list. |
| dropwhile/2 | Drops elements Elem from List1 while Pred(Elem) returns true and returns the remaining list. |
| 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. |
| flatmap/2 | Map elements of list L by applying F, and append the results. |
| flatten/1 | 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. |
| keysort/2 | Sort a list of tuples by Nth element. |
| keystore/4 | Searches the list of tuples TupleList for a tuple whose Nth element compares equal to Key, replaces it with NewTuple if found. |
| keytake/3 | Searches the list of tuples TupleList1 for a tuple whose Nth 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. |
| max/1 | Returns the first element of List that compares greater than or equal to all other elements of List. |
| member/2 | Determine whether a term is a member of a list. |
| merge/2 | Returns a list formed by merging List1 and List2, following natural order. |
| merge/3 | Returns a list formed by merging List1 and List2, following Fun order. |
| min/1 | Returns the first element of List that compares less than or equal to all other elements of 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. |
| sublist/3 | Return a sublist starting at Start (1-based) with at most Len elements. |
| ukeysort/2 | Sort a list of tuples by Nth element and remove duplicates. |
| usort/1 | Returns a unique, sorted list, using < operator to determine sort order. |
| usort/2 | Returns a unique, sorted list. |
| zip/2 | Combine elements from two lists into a list of two-tuples. |
| zipwith/3 | Combine elements from two lists using the given function. |
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(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
append(ListOfLists) -> List1
ListOfLists = [List]List = [T]List1 = [T]T = term()ListOfLists: a list of lists to make the general list from
returns: a list made of the sublists of ListOfLists.
Returns a list in which all the sublists of ListOfLists have been appended.
append(List1, List2) -> List3
List1 = [T]List2 = [T]List3 = [T]T = term()List1: a list
List2: a list
returns: a list made of the elements of List1 and List2.
Returns a new list List3, which is made from the elements of List1 followed by the elements of List2.
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
droplast(List::[T, ...]) -> [T]
List: a non-empty list
returns: all elements of List except the last
Drop the last element of a list.
dropwhile(Pred, List1) -> List2
Pred = fun((Elem::T) -> boolean())List1 = [T]List2 = [T]T = term()Pred: the predicate to check against elements in List1
returns: List List1 tail at the point predicate returned false for a element
Drops elements Elem from List1 while Pred(Elem) returns true and returns the remaining list. The Pred function must return a boolean.
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(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(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]
flatmap(F::fun((Elem::term()) -> [term()]), List::[term()]) -> [term()]
F: the function to apply to elements of L
returns: List of mapped elements, appended
Map elements of list L by applying F, and append the results. F should return a list.
flatten(L::list()) -> list()
L: the list to flatten
returns: flattened list
Flattens elements of L into a single list
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(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(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(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(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(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(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(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.
keysort(N::pos_integer(), L::[tuple()]) -> [tuple()]
N: the position in the tuple to compare (1..tuple_size)
L: the list to sort
returns: The list L sorted by Nth element
Sort a list of tuples by Nth element.
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(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(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(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(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.
max(List) -> Max
List = [T, ...]Max = TT = term()List: a non-empty list of terms that can be compared
returns: the maximum element of the list
Returns the first element of List that compares greater than or equal to all other elements of List.
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.
merge(List1, List2) -> any()
Returns a list formed by merging List1 and List2, following natural order. If elements compare equal, element from List1 is picked first
merge(Fun, List1, List2) -> any()
Returns a list formed by merging List1 and List2, following Fun order. If elements compare equal, element from List1 is picked first
min(List) -> Min
List = [T, ...]Min = TT = term()List: a non-empty list of terms that can be compared
returns: the minimum element of the list
Returns the first element of List that compares less than or equal to all other elements of List.
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(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(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(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(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(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(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(List::[T]) -> [T]
List: a list
returns: Sorted list, ordered by <
Returns a sorted list, using < operator to determine sort order.
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(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(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.
sublist(List::[Elem], Start::pos_integer(), Len::non_neg_integer()) -> [Elem]
List: list to take the sublist from
Start: 1-based start position
Len: maximum number of elements to return
returns: a sublist of List starting at Start with at most Len elements
Return a sublist starting at Start (1-based) with at most Len elements. It is not an error for Start+Len to exceed the length of List.
ukeysort(N::pos_integer(), L::[tuple()]) -> [tuple()]
N: the position in the tuple to compare (1..tuple_size)
L: the list to sort
returns: The list L sorted by Nth element with duplicates removed
Sort a list of tuples by Nth element and remove duplicates. Two tuples compare equal if their Nth elements compare equal.
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(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.
zip(List1, List2) -> List3
List1 = [A]List2 = [B]List3 = [{A, B}]A = term()B = term()List1: a list
List2: a list
returns: a list of two-tuples combining corresponding elements of List1 and List2
Combine elements from two lists into a list of two-tuples. Both lists must have equal length.
zipwith(Combine, List1, List2) -> List3
Combine = fun((X, Y) -> T)List1 = [X]List2 = [Y]List3 = [T]X = term()Y = term()T = term()Combine: a function that takes elements from each list
List1: a list
List2: a list
returns: a list of results from applying Combine to corresponding elements
Combine elements from two lists using the given function. Both lists must have equal length.