List
Standard library for list operations.
Functions in this module operate on type [A]
(equivalent to List<A>
),
which represents a linked list with O(1)
put()
and O(n)
at()
and delete()
. Literal lists can be created with
the syntax [a, b, ...]
, where a
, b
, etc. are elements.
To import all names from this module, use:
import List (*)
With no import, you can still access anything with the prefix List.
, like List.at
.
Index
Name | Type | Description |
---|---|---|
[A] -> A | Returns the first element in the list | |
[A] -> [A] | Returns a list containing all elements in | |
[A] -> Int | Returns the length of | |
[A] -> Bool | Returns whether | |
([A], [A]) -> [A] | Concatenates | |
[[A]] -> [A] | Concatenates all elements in the list | |
([A], A -> B) -> [B] | Calls | |
([A], Int) -> A | Returns the element at index | |
([A], Int, Int) -> [A] | Returns a sublist of | |
([A], Int, Int) -> [A] | Returns a sublist of | |
([A], Int) -> ([A], [A]) | Returns two lists: the first contains all elements from index | |
([A], Int) -> [A] | Takes | |
([A], Int) -> [A] | Drops | |
([A], A -> Bool) -> [A] | Takes elements from | |
([A], A -> Bool) -> [A] | Drops elements from | |
([A], A -> Bool) -> ([A], [A]) | Takes elements from | |
([A], A -> Bool) -> ([A], [A]) | Returns two new lists: one containing elements for which | |
[A] -> [A] | Reverses the list | |
([A], A -> [B]) -> [B] | Calls | |
([A], F, (F, A) -> F) -> F | Same as | |
([A], F, (F, A) -> (F, B)) -> (F, [B]) | Same as | |
[A ~ Num] -> A ~ Num | Returns the sum of all numbers in | |
[A ~ Ord] -> [A ~ Ord] | Sorts | |
([A], A -> B ~ Ord) -> [A] | Sorts | |
([A], (A, A) -> Bool) -> [A] | Sorts | |
([String], String) -> String | Joins the list of strings | |
[A ~ Ord] -> Option<A ~ Ord> | Returns the maximum element in | |
[A ~ Ord] -> Option<A ~ Ord> | Returns the minimum element in | |
([A], A -> B ~ Ord) -> Option<A> | Returns the element in | |
([A], A -> B ~ Ord) -> Option<A> | Returns the element in | |
(Int, Int) -> [Int] | Returns a list containing the sequence of integers from | |
(A, Int) -> [A] | Creates a new list that has the element | |
([A], [B]) -> [(A, B)] | Returns a list where the | |
[(A, B)] -> ([A], [B]) | Unpacks a list of tuples | |
([A], A -> B) -> Map<B, [A]> | Calls | |
[A] -> [A] | Removes duplicates in | |
([A], A -> B) -> [A] | Removes duplicates in | |
[A] -> [(A, Int)] | Pairs each element in | |
([A], A -> B) -> () | Calls | |
([A], F, (F, A) -> F) -> F | Computes a single value by applying the combining function | |
([A], A -> Bool) -> [A] | Calls | |
([A], A -> Bool) -> Option<A> | Returns the first element in | |
([A], A -> Option<B>) -> [B] | Calls | |
([A], F, (F, A) -> (F, B)) -> (F, [B]) | Computes a new collection and a single value by applying the combining
function | |
([A], A) -> [A] | Puts | |
([A], A) -> [A] | Removes | |
([A], A) -> Bool | Returns true if | |
([A], A -> Bool) -> Bool | Calls | |
([A], A -> Bool) -> Bool | Calls | |
[A] -> Set<A> | Converts | |
[(K, V)] -> Map<K, V> | Converts |
Functions
head : [A] -> A head(l)
Returns the first element in the list l
. Raises EmptyList
if l
is empty.
This function is part of the Base
module, meaning it's a builtin that's in the global namespace, so it doesn't need to be imported.
assert head([1]) == 1 assert head(["hi", "hey", "hello"]) == "hi"
tail : [A] -> [A] tail(l)
Returns a list containing all elements in l
except the first. Raises
EmptyList
if l
is empty.
This function is part of the Base
module, meaning it's a builtin that's in the global namespace, so it doesn't need to be imported.
assert tail([1]) == [] assert tail(["hi", "hey", "hello"]) == ["hey", "hello"]
at : ([A], Int) -> A at(l, i)
Returns the element at index i
in l
. i
can be negative, where -1
is
the last index, -2
is the second-to-last index, etc. If at
tries to
access an element at an invalid index, it raises
BadListIndex
.
assert at(["cow", "dog", "cat"], 0) == "cow" assert at(["cow", "dog", "cat"], -1) == "cat" assert at([42.3, .428, 13.3], 2) == 13.3 assert at([42.3, .428, 13.3], -3) == 42.3
slice : ([A], Int, Int) -> [A] slice(l, i, len)
Returns a sublist of l
starting at index i
with length len
. i
can
be negative, where -1
is the last index, -2
is the second-to-last index,
etc. If len <= 0
, returns []
. If slice
tries to access an element at an
invalid index, it raises BadListIndex
.
assert slice(["cow", "dog", "cat"], 0, 2) == ["cow", "dog"] assert slice(["cow", "dog", "cat"], -1, 1) == ["cat"] assert slice(["cow", "dog", "cat"], 3, 0) == [] assert slice([42.3, .428, 13.3], -3, 2) == [42.3, .428]
range : ([A], Int, Int) -> [A] range(l, start, end)
Returns a sublist of l
starting at index start
and ending at index
end
, inclusive. start
and end
can be negative, where -1
is the last
index, -2
is the second-to-last index, etc. If start > end
(after
resolving negative indexes), returns []
. If range
tries to access an
element at an invalid index, it raises BadListIndex
.
assert range(["cow", "dog", "cat"], 0, 1) == ["cow", "dog"] assert range(["cow", "dog", "cat"], -1, 2) == ["cat"] assert range(["cow", "dog", "cat"], 3, 1) == [] assert range([42.3, .428, 13.3], -3, 1) == [42.3, .428]
split_at : ([A], Int) -> ([A], [A]) split_at(l, i)
Returns two lists: the first contains all elements from index 0
to i - 1
,
and the second contains all elements from index i
to the end of the list.
i
can be negative, where -1
is the last index, -2
is the second-to-last
index, etc. If split_at
tries to access an element at an invalid index, it
raises BadListIndex
.
assert split_at(["cow", "dog", "cat"], 0) == ([], ["cow", "dog", "cat"]) assert split_at(["cow", "dog", "cat"], -1) == (["cow", "dog"], ["cat"]) assert split_at([42.3, .428, 13.3], 2) == ([42.3, .428], [13.3]) assert split_at([42.3, .428, 13.3], -3) == ([], [42.3, .428, 13.3])
take : ([A], Int) -> [A] take(l, n)
Takes n
elements from the beginning of l
, returning a new list. If l
has fewer than n
elements, returns l
. If n
is negative, returns []
.
assert take(["cow", "dog", "cat"], 2) == ["cow", "dog"] assert take(["cow", "dog", "cat"], 10) == ["cow", "dog", "cat"] assert take(["cow", "dog", "cat"], 0) == [] assert take(["cow", "dog", "cat"], -3) == []
drop : ([A], Int) -> [A] drop(l, n)
Drops n
elements from the beginning of l
, returning a new list. If l
has fewer than n
elements, returns []
. If n
is negative, returns l
.
assert drop(["cow", "dog", "cat"], 2) == ["cat"] assert drop(["cow", "dog", "cat"], 10) == [] assert drop(["cow", "dog", "cat"], 0) == ["cow", "dog", "cat"] assert drop(["cow", "dog", "cat"], -3) == ["cow", "dog", "cat"]
take_while : ([A], A -> Bool) -> [A] take_while(l, f)
Takes elements from l
while f
returns true, returning a new list. f
accepts an element and returns true to take it or false to stop.
assert take_while(["cow", "dog", "cat"], |a| a < "d") == ["cow"] assert take_while(["cow", "dog", "cat"], |a| a > "e") == [] assert take_while([42.3, .428, 13.3], |a| a < 50) == [42.3, .428, 13.3] assert take_while([], |_| true) == []
drop_while : ([A], A -> Bool) -> [A] drop_while(l, f)
Drops elements from l
while f
returns true, returning a new list. f
accepts an element and returns true to take it or false to stop.
assert drop_while(["cow", "dog", "cat"], |a| a < "d") == ["dog", "cat"] assert drop_while(["cow", "dog", "cat"], |a| a > "e") == ["cow", "dog", "cat"] assert drop_while([42.3, .428, 13.3], |a| a < 50) == [] assert drop_while([], |_| true) == []
split_while : ([A], A -> Bool) -> ([A], [A]) split_while(l, f)
Takes elements from l
while f
returns true, and returns two new lists:
the elements that were taken, and all remaining elements.
assert split_while(["cow", "dog", "cat"], |a| a < "d") == (["cow"], ["dog", "cat"]) assert split_while(["cow", "dog", "cat"], |a| a > "e") == ([], ["cow", "dog", "cat"]) assert split_while([42.3, .428, 13.3], |a| a < 50) == ([42.3, .428, 13.3], []) assert split_while([], |_| true) == ([], [])
partition : ([A], A -> Bool) -> ([A], [A]) partition(l, f)
Returns two new lists: one containing elements for which f
returns true,
and the other containing elements for which f
returns false.
assert partition(["cow", "dog", "cat"], |a| a < "d") == (["cow", "cat"], ["dog"]) assert partition(["cow", "dog", "cat"], |a| a > "e") == ([], ["cow", "dog", "cat"]) assert partition([42.3, .428, 13.3], |a| a < 1) == ([.428], [42.3, 13.3]) assert partition([], |a| true) == ([], [])
reverse : [A] -> [A] reverse(l)
Reverses the list l
.
assert reverse(["cow", "dog", "cat"]) == ["cat", "dog", "cow"] assert reverse([42.3, .428, 13.3]) == [13.3, .428, 42.3] assert reverse([]) == []
flat_map : ([A], A -> [B]) -> [B] flat_map(l, f)
Calls f
for each element in l
, concatenating the resultant lists together
into one list. f
accepts an element in l
and returns a list.
assert flat_map([42.3, .428, 13.3], |a| [a, a + 0.1]) == [42.3, 42.4, .428, .528, 13.3, 13.4] assert flat_map([42.3, .428, 13.3], |a| [a]) == [42.3, .428, 13.3] assert flat_map(["cow", "dog", "cat"], String.to_chars) == String.to_chars("cowdogcat") assert flat_map([], |a| [a]) == []
foldr : ([A], F, (F, A) -> F) -> F foldr(l, init, f)
Same as fold
, expect that it goes through l
in the reverse
order, calling f
with the last element, then the second-to-last element,
etc.
assert foldr(["cow", "dog", "cat"], "turtle", |accum, a| accum ++ a) == "turtlecatdogcow" assert foldr([42.3, .428, 13.3], 5, |accum, a| -accum + a) == 50.172 assert foldr([], true, |accum, a| accum && a) == true
foldr_map : ([A], F, (F, A) -> (F, B)) -> (F, [B]) foldr_map(l, init, f)
Same as fold_map
, expect that it goes through l
in the
reverse order, calling f
with the last element, then the second-to-last
element, etc. The resulting mapped list is still in the same order as the
original list.
let l = ["cow", "dog", "cat"] assert foldr_map(l, "turtle", |accum, a| (accum ++ "!" ++ a, a ++ "!")) == ("turtle!cat!dog!cow", ["cow!", "dog!", "cat!"]) let l = [42, .4, 13.3] assert foldr_map(l, 5, |accum, a| (-accum + a, accum)) == (49.9, [-7.9, 8.3, 5]) assert foldr_map([], true, |accum, a| (accum && a, accum)) == (true, [])
sum : [A ~ Num] -> A ~ Num sum(l)
Returns the sum of all numbers in l
.
assert sum([5, 9, -37]) == -23 assert sum([42.3, .4, 13.3]) == 56.0 assert sum([]) == 0
sort : [A ~ Ord] -> [A ~ Ord] sort(l)
Sorts l
in ascending order. l
is expected to contain elements that
satisfy the Ord
interface, meaning they have
a defined ordering.
assert sort(["cow", "dog", "cat"]) == ["cat", "cow", "dog"] assert sort([42.3, .428, 13.3]) == [.428, 13.3, 42.3] assert sort([]) == []
sort_by : ([A], A -> B ~ Ord) -> [A] sort_by(l)
Sorts l
in ascending order based on the return value of f
for each
element. The element for which f
returns the minimum value is first, and
the element for which f
returns the maximum value is last. f
accepts an
element as an argument and returns a value that satisfies the
Ord
interface, which has a defined ordering.
assert sort_by([42.3, .428, 13.3], |a| -a) == [42.3, 13.3, .428] let f(a) = String.to_chars(a) |> at(2) |> to_int assert sort_by(["cow", "dog", "cat"], f) == ["dog", "cat", "cow"] assert sort_by([], |a| a) == []
sort_cmp : ([A], (A, A) -> Bool) -> [A] sort_cmp(l, f)
Sorts l
in ascending order based on the comparator function f
. f
is
called with two elements a
and b
, and the comparator should return true
if a
must be placed before b
in the sorted list.
assert sort_cmp([42.3, .428, 13.3], |a, b| a < b) == [.428, 13.3, 42.3] let key(s) = String.to_chars(s) |> at(2) |> to_int let f(a, b) = key(a) > key(b) assert sort_cmp(["cow", "dog", "cat"], f) == ["cow", "cat", "dog"] assert sort_cmp([], |a, b| a < b) == []
join : ([String], String) -> String join(l, sep)
Joins the list of strings l
with the separator sep
, returning a string.
sep
is placed in-between every two subsequent elements of l
.
assert join(["cow", "dog", "cat"], "") == "cowdogcat" assert join(["cow", "dog", "cat"], ", ") == "cow, dog, cat" assert join([], ", ") == ""
max_in : [A ~ Ord] -> Option<A ~ Ord> max_in(l)
Returns the maximum element in l
as Some(max)
, or
None
if l
is empty. l
is expected to contain elements
that satisfy the Ord
interface, meaning they
have a defined ordering.
assert max_in(["cow", "dog", "cat"]) == Some("dog") assert max_in([42.3, .428, 13.3]) == Some(42.3) assert max_in([]) == None
min_in : [A ~ Ord] -> Option<A ~ Ord> min_in(l)
Returns the minimum element in l
as Some(min)
, or
None
if l
is empty. l
is expected to contain elements
that satisfy the Ord
interface, meaning they
have a defined ordering.
assert min_in(["cow", "dog", "cat"]) == Some("cat") assert min_in([42.3, .428, 13.3]) == Some(.428) assert min_in([]) == None
max_by : ([A], A -> B ~ Ord) -> Option<A> max_by(l, f)
Returns the element in l
for which f
returns the maximum value. f
accepts an element as an argument and returns a value that satisfies the
Ord
interface, which has a defined ordering.
assert max_by(["cow", "dog", "turtle"], |l| length(l)) == Some("turtle") assert max_by([42.3, .428, 13.3], |l| -l) == Some(.428) assert max_by([], |l| l) == None
min_by : ([A], A -> B ~ Ord) -> Option<A> min_by(l, f)
Returns the element in l
for which f
returns the minimum value. f
accepts an element as an argument and returns a value that satisfies the
Ord
interface, which has a defined ordering.
assert min_by(["cow", "dog", "turtle"], |l| length(l)) == Some("cow") assert min_by([42.3, .428, 13.3], |l| -l) == Some(42.3) assert min_by([], |l| l) == None
seq : (Int, Int) -> [Int] seq(start, end)
Returns a list containing the sequence of integers from start
to end
,
both inclusive. If start > end
, returns []
.
assert seq(0, 3) == [0, 1, 2, 3] assert seq(-3, 1) == [-3, -2, -1, 0, 1] assert seq(5, 5) == [5] assert seq(2, 1) == []
repeat : (A, Int) -> [A] repeat(a, n)
Creates a new list that has the element a
repeated n
times.
assert repeat("hi", 3) == ["hi", "hi", "hi"] assert repeat('h', 1) == ['h'] assert repeat(true, 0) == []
zip : ([A], [B]) -> [(A, B)] zip(l1, l2)
Returns a list where the i
-th element is a tuple containing the i
-th
element of l1
and the i
-th element of l2
. If l1
and l2
don't have
the same length, raises MismatchedLengths
. See
unzip()
for the opposite operation.
assert zip(["cow", "dog", "cat"], [42.3, .428, 13.3]) == [("cow", 42.3), ("dog", .428), ("cat", 13.3)] assert zip([@hi], ['h']) == [(@hi, 'h')] assert zip([], []) == []
unzip : [(A, B)] -> ([A], [B]) unzip(l)
Unpacks a list of tuples l
into two separate lists. If the i
-th element
of l
is a tuple (a, b)
, the i
-th element of the first result list is
a
, and the i
-th element of the second result list is b
. See
zip()
for the opposite operation.
assert unzip([("cow", 42.3), ("dog", .428), ("cat", 13.3)]) == (["cow", "dog", "cat"], [42.3, .428, 13.3]) assert unzip([(@hi, 'h')]) == ([@hi], ['h']) assert unzip([]) == ([], [])
group_by : ([A], A -> B) -> Map<B, [A]> group_by(l, f)
Calls f
on each element of l
, returning a map from each return value of
f
to the list of elements that gave that return value.
assert group_by(["turtle", "dog", "cat"], |a| length(a)) == { 6 => ["turtle"], 3 => ["dog", "cat"] } assert group_by([42.3, .428, 13.3], |a| a > 10) == { true => [42.3, 13.3], false => [.428] } assert group_by([42.3, .428, 13.3], |a| a) == { 42.3 => [42.3], .428 => [.428], 13.3 => [13.3] } assert group_by( ["cow", "dog", "cat"], |a| String.to_chars(a) |> head ) == { 'c' => ["cow", "cat"], 'd' => ["dog"] }
unique : [A] -> [A] unique(l)
Removes duplicates in l
, returning a new list. l
is not modified.
assert unique(["cow", "dog", "cat"]) == ["cow", "dog", "cat"] assert unique(["cow", "dog", "cow"]) == ["cow", "dog"] assert unique([42.3, .428, 13.3, .428]) == [42.3, .428, 13.3] assert unique([]) == []
unique_by : ([A], A -> B) -> [A] unique_by(l, f)
Removes duplicates in l
, returning a new list, where two elements are
duplicates if f
returns the same value for them. l
is not modified.
assert unique_by([42.3, .428, 13.3], |a| a > 10) == [42.3, .428] assert unique_by([42.3, .428, 13.3], |a| true) == [42.3] assert unique_by( ["cow", "dog", "cat"], |a| String.to_chars(a) |> head ) == ["cow", "dog"] assert unique_by([], |a| a) == []
with_index : [A] -> [(A, Int)] with_index(l)
Pairs each element in l
with its index, returning a new list of tuples.
assert with_index(["cow", "dog", "cat"]) == [("cow", 0), ("dog", 1), ("cat", 2)] assert with_index([42.3]) == [(42.3, 0)] assert with_index([]) == []
each : ([A], A -> B) -> () each(l, f)
Calls f
on each element of l
. This function rarely needs to be used, and
is only necessary when performing a side-effect (e.g. printing, writing to
a file, etc.) for each element in a list. In most cases, what you really want
is a specific operation like map()
, filter()
, or
fold()
.
// prints each element each([1, 2, 3], |e| print("element: " ++ e))
Implementations
impl Sized for [A]
The following functions are from the Sized
interface.
length : [A] -> Int length(sized)
Returns the length of sized
. See the full description in the Sized
interface.
empty? : [A] -> Bool empty?(sized)
Returns whether sized
is empty. See the full description in the Sized
interface.
impl Concat for [A]
The following functions are from the Concat
interface.
concat : ([A], [A]) -> [A] concat(a, b)
Concatenates a
and b
together, equivalent to a ++ b
. See the full description in the Concat
interface.
concat_all : [[A]] -> [A] concat_all(l)
Concatenates all elements in the list l
together. See the full description in the Concat
interface.
impl Mappable for List
The following functions are from the Mappable
interface.
map : ([A], A -> B) -> [B] map(container, f)
Calls f
for each element in container
, collecting the results into
a new container. See the full description in the Mappable
interface.
impl Collection for List
The following functions are from the Collection
interface.
fold : ([A], F, (F, A) -> F) -> F fold(collection, init, f)
Computes a single value by applying the combining function f
to each
element of the given collection
, starting with the initial value init
. See the full description in the Collection
interface.
filter : ([A], A -> Bool) -> [A] filter(collection, f)
Calls f
for each element in collection
, returning a new collection
that only contains the elements for which f
returns true. See the full description in the Collection
interface.
find : ([A], A -> Bool) -> Option<A> find(collection, f)
Returns the first element in collection
for which f
returns true. See the full description in the Collection
interface.
filter_map : ([A], A -> Option<B>) -> [B] filter_map(collection, f)
Calls f
for each element in collection
, returning a new collection
that contains every e
such that f
returned Some(e)
. See the full description in the Collection
interface.
fold_map : ([A], F, (F, A) -> (F, B)) -> (F, [B]) fold_map(collection, init, f)
Computes a new collection and a single value by applying the combining
function f
to each element of the given collection
, starting with the
initial value init
. See the full description in the Collection
interface.
put : ([A], A) -> [A] put(collection, elem)
Puts elem
into collection
, returning a new collection. See the full description in the Collection
interface.
delete : ([A], A) -> [A] delete(collection, elem)
Removes elem
from collection
, returning a new collection. See the full description in the Collection
interface.
contains? : ([A], A) -> Bool contains?(collection, elem)
Returns true if collection
contains elem
. See the full description in the Collection
interface.
all? : ([A], A -> Bool) -> Bool all?(collection, f)
Calls f
for each element in collection
, and returns true if f
returns true for every element. See the full description in the Collection
interface.
any? : ([A], A -> Bool) -> Bool any?(collection, f)
Calls f
for each element in collection
, and returns true if f
returns true for at least one element. See the full description in the Collection
interface.
impl ToSet for List
The following functions are from the ToSet
interface.
to_set : [A] -> Set<A> to_set(a)
Converts a
to a set. See the full description in the ToSet
interface.
impl ToMap for List
The following functions are from the ToMap
interface.
to_map : [(K, V)] -> Map<K, V> to_map(a)
Converts a
to a map. See the full description in the ToMap
interface.
Exceptions
exception BadListIndex(Int)
Raised by at()
, split_at()
, slice()
, and
range()
when accessing an index out of bounds.
exception MismatchedLengths(Int, Int)
Raised by zip()
when the two lists don't have the same lengths.