Functions that work on (linked) lists.
Lists in Elixir are specified between square brackets:
iex> [1, "two", 3, :four]
[1, "two", 3, :four]
Two lists can be concatenated and subtracted using the Kernel.++/2
and Kernel.--/2
operators:
iex> [1, 2, 3] ++ [4, 5, 6]
[1, 2, 3, 4, 5, 6]
iex> [1, true, 2, false, 3, true] -- [true, false]
[1, 2, 3, true]
Lists in Elixir are effectively linked lists, which means they are internally represented in pairs containing the head and the tail of a list:
iex> [head | tail] = [1, 2, 3]
iex> head
1
iex> tail
[2, 3]
Similarly, we could write the list [1, 2, 3]
using only such pairs (called cons cells):
iex> [1 | [2 | [3 | []]]]
[1, 2, 3]
Some lists, called improper lists, do not have an empty list as the second element in the last cons cell:
iex> [1 | [2 | [3 | 4]]]
[1, 2, 3 | 4]
Although improper lists are generally avoided, they are used in some special circumstances like iodata and chardata entities (see the IO
module).
Due to their cons cell based representation, prepending an element to a list is always fast (constant time), while appending becomes slower as the list grows in size (linear time):
iex> list = [1, 2, 3]
iex> [0 | list] # fast
[0, 1, 2, 3]
iex> list ++ [4] # slow
[1, 2, 3, 4]
The Kernel
module contains many functions to manipulate lists and that are allowed in guards. For example, Kernel.hd/1
to retrieve the head, Kernel.tl/1
to fetch the tail and Kernel.length/1
for calculating the length. Keep in mind that, similar to appending to a list, calculating the length needs to traverse the whole list.
If a list is made of non-negative integers, it can also be called a charlist. Elixir uses single quotes to define charlists:
iex> 'héllo'
[104, 233, 108, 108, 111]
In particular, charlists may be printed back in single quotes if they contain only ASCII-printable codepoints:
iex> 'abc'
'abc'
The rationale behind this behaviour is to better support Erlang libraries which may return text as charlists instead of Elixir strings. One example of such functions is Application.loaded_applications/0
:
Application.loaded_applications
#=> [{:stdlib, 'ERTS CXC 138 10', '2.6'},
#=> {:compiler, 'ERTS CXC 138 10', '6.0.1'},
#=> {:elixir, 'elixir', '1.0.0'},
#=> {:kernel, 'ERTS CXC 138 10', '4.1'},
#=> {:logger, 'logger', '1.0.0'}]
A list can be checked if it is made of printable ascii codepoints with ascii_printable?/2
.
This module aims to provide operations that are specific to lists, like conversion between data types, updates, deletions and key lookups (for lists of tuples). For traversing lists in general, developers should use the functions in the Enum
module that work across a variety of data types.
In both Enum
and List
modules, any kind of index access on a list is linear. Negative indexes are also supported but they imply the list will be iterated twice, one to calculate the proper index and another to perform the operation.
Checks if a list is a charlist made only of printable ASCII characters
Deletes the given item
from the list
. Returns a new list without the item
Produces a new list by removing the value at the specified index
Duplicates the given element n
times in a list
Returns the first element in list
or nil
if list
is empty
Flattens the given list
of nested lists
Flattens the given list
of nested lists. The list tail
will be added at the end of the flattened list
Folds (reduces) the given list from the left with a function. Requires an accumulator
Folds (reduces) the given list from the right with a function. Requires an accumulator
Returns a list with value
inserted at the specified index
Receives a list
of tuples and deletes the first tuple where the item at position
matches the given key
. Returns the new list
Receives a list of tuples and returns the first tuple where the item at position
in the tuple matches the given key
Receives a list of tuples and returns true
if there is a tuple where the item at position
in the tuple matches the given key
Receives a list of tuples and replaces the item identified by key
at position
if it exists
Receives a list of tuples and sorts the items at position
of the tuples. The sort is stable
Receives a list
of tuples and replaces the item identified by key
at position
Receives a list
of tuples and returns the first tuple where the element at position
in the tuple matches the given key
, as well as the list
without found tuple
Returns the last element in list
or nil
if list
is empty
Returns a keyword list that represents an edit script
Returns and removes the value at the specified index
in the list
Returns a list with a replaced value at the specified index
Returns true
if list
starts with the given prefix
list; otherwise returns false
Converts a charlist to an atom
Converts a charlist to an existing atom. Raises an ArgumentError
if the atom does not exist
Returns the float whose text representation is charlist
Returns an integer whose text representation is charlist
Returns an integer whose text representation is charlist
in base base
Converts a list of integers representing codepoints, lists or strings into a string
Converts a list to a tuple
Returns a list with an updated value at the specified index
Wraps the argument in a list
Zips corresponding elements from each list in list_of_lists
Checks if a list is a charlist made only of printable ASCII characters.
A printable charlist in Elixir contains only ASCII characters.
Takes an optional limit
as a second argument. ascii_printable?/2
only checks the printability of the list up to the limit
.
iex> List.ascii_printable?('abc')
true
iex> List.ascii_printable?('abc' ++ [0])
false
iex> List.ascii_printable?('abc' ++ [0], 2)
true
Improper lists are not printable, even if made only of ascii characters:
iex> List.ascii_printable?('abc' ++ ?d)
false
delete(list(), any()) :: list()
Deletes the given item
from the list
. Returns a new list without the item.
If the item
occurs more than once in the list
, just the first occurrence is removed.
iex> List.delete([:a, :b, :c], :a)
[:b, :c]
iex> List.delete([:a, :b, :b, :c], :b)
[:a, :b, :c]
delete_at(list(), integer()) :: list()
Produces a new list by removing the value at the specified index
.
Negative indices indicate an offset from the end of the list
. If index
is out of bounds, the original list
is returned.
iex> List.delete_at([1, 2, 3], 0)
[2, 3]
iex> List.delete_at([1, 2, 3], 10)
[1, 2, 3]
iex> List.delete_at([1, 2, 3], -1)
[1, 2]
duplicate(elem, non_neg_integer()) :: [elem] when elem: var
Duplicates the given element n
times in a list.
iex> List.duplicate("hello", 3)
["hello", "hello", "hello"]
iex> List.duplicate([1, 2], 2)
[[1, 2], [1, 2]]
first([elem]) :: nil | elem when elem: var
Returns the first element in list
or nil
if list
is empty.
iex> List.first([])
nil
iex> List.first([1])
1
iex> List.first([1, 2, 3])
1
flatten(deep_list) :: list() when deep_list: [any() | deep_list]
Flattens the given list
of nested lists.
iex> List.flatten([1, [[2], 3]])
[1, 2, 3]
flatten(deep_list, [elem]) :: [elem] when deep_list: [elem | deep_list], elem: var
Flattens the given list
of nested lists. The list tail
will be added at the end of the flattened list.
iex> List.flatten([1, [[2], 3]], [4, 5])
[1, 2, 3, 4, 5]
foldl([elem], acc, (elem, acc -> acc)) :: acc when elem: var, acc: var
Folds (reduces) the given list from the left with a function. Requires an accumulator.
iex> List.foldl([5, 5], 10, fn(x, acc) -> x + acc end)
20
iex> List.foldl([1, 2, 3, 4], 0, fn(x, acc) -> x - acc end)
2
foldr([elem], acc, (elem, acc -> acc)) :: acc when elem: var, acc: var
Folds (reduces) the given list from the right with a function. Requires an accumulator.
iex> List.foldr([1, 2, 3, 4], 0, fn(x, acc) -> x - acc end)
-2
insert_at(list(), integer(), any()) :: list()
Returns a list with value
inserted at the specified index
.
Note that index
is capped at the list length. Negative indices indicate an offset from the end of the list
.
iex> List.insert_at([1, 2, 3, 4], 2, 0)
[1, 2, 0, 3, 4]
iex> List.insert_at([1, 2, 3], 10, 0)
[1, 2, 3, 0]
iex> List.insert_at([1, 2, 3], -1, 0)
[1, 2, 3, 0]
iex> List.insert_at([1, 2, 3], -10, 0)
[0, 1, 2, 3]
keydelete([tuple()], any(), non_neg_integer()) :: [tuple()]
Receives a list
of tuples and deletes the first tuple where the item at position
matches the given key
. Returns the new list.
iex> List.keydelete([a: 1, b: 2], :a, 0)
[b: 2]
iex> List.keydelete([a: 1, b: 2], 2, 1)
[a: 1]
iex> List.keydelete([a: 1, b: 2], :c, 0)
[a: 1, b: 2]
keyfind([tuple()], any(), non_neg_integer(), any()) :: any()
Receives a list of tuples and returns the first tuple where the item at position
in the tuple matches the given key
.
iex> List.keyfind([a: 1, b: 2], :a, 0)
{:a, 1}
iex> List.keyfind([a: 1, b: 2], 2, 1)
{:b, 2}
iex> List.keyfind([a: 1, b: 2], :c, 0)
nil
keymember?([tuple()], any(), non_neg_integer()) :: boolean()
Receives a list of tuples and returns true
if there is a tuple where the item at position
in the tuple matches the given key
.
iex> List.keymember?([a: 1, b: 2], :a, 0)
true
iex> List.keymember?([a: 1, b: 2], 2, 1)
true
iex> List.keymember?([a: 1, b: 2], :c, 0)
false
keyreplace([tuple()], any(), non_neg_integer(), tuple()) :: [tuple()]
Receives a list of tuples and replaces the item identified by key
at position
if it exists.
iex> List.keyreplace([a: 1, b: 2], :a, 0, {:a, 3})
[a: 3, b: 2]
keysort([tuple()], non_neg_integer()) :: [tuple()]
Receives a list of tuples and sorts the items at position
of the tuples. The sort is stable.
iex> List.keysort([a: 5, b: 1, c: 3], 1)
[b: 1, c: 3, a: 5]
iex> List.keysort([a: 5, c: 1, b: 3], 0)
[a: 5, b: 3, c: 1]
keystore([tuple()], any(), non_neg_integer(), tuple()) :: [tuple(), ...]
Receives a list
of tuples and replaces the item identified by key
at position
.
If the item does not exist, it is added to the end of the list
.
iex> List.keystore([a: 1, b: 2], :a, 0, {:a, 3})
[a: 3, b: 2]
iex> List.keystore([a: 1, b: 2], :c, 0, {:c, 3})
[a: 1, b: 2, c: 3]
keytake([tuple()], any(), non_neg_integer()) :: {tuple(), [tuple()]} | nil
Receives a list
of tuples and returns the first tuple where the element at position
in the tuple matches the given key
, as well as the list
without found tuple.
If such a tuple is not found, nil
will be returned.
iex> List.keytake([a: 1, b: 2], :a, 0)
{{:a, 1}, [b: 2]}
iex> List.keytake([a: 1, b: 2], 2, 1)
{{:b, 2}, [a: 1]}
iex> List.keytake([a: 1, b: 2], :c, 0)
nil
last([elem]) :: nil | elem when elem: var
Returns the last element in list
or nil
if list
is empty.
iex> List.last([])
nil
iex> List.last([1])
1
iex> List.last([1, 2, 3])
3
myers_difference(list(), list()) :: [{:eq | :ins | :del, list()}] | nil
Returns a keyword list that represents an edit script.
The algorithm is outlined in the “An O(ND) Difference Algorithm and Its Variations” paper by E. Myers.
An edit script is a keyword list. Each key describes the “editing action” to take in order to bring list1
closer to being equal to list2
; a key can be :eq
, :ins
, or :del
. Each value is a sublist of either list1
or list2
that should be inserted (if the corresponding key :ins
), deleted (if the corresponding key is :del
), or left alone (if the corresponding key is :eq
) in list1
in order to be closer to list2
.
iex> List.myers_difference([1, 4, 2, 3], [1, 2, 3, 4])
[eq: [1], del: [4], eq: [2, 3], ins: [4]]
pop_at(list(), integer(), any()) :: {any(), list()}
Returns and removes the value at the specified index
in the list
.
Negative indices indicate an offset from the end of the list
. If index
is out of bounds, the original list
is returned.
iex> List.pop_at([1, 2, 3], 0)
{1, [2, 3]}
iex> List.pop_at([1, 2, 3], 5)
{nil, [1, 2, 3]}
iex> List.pop_at([1, 2, 3], 5, 10)
{10, [1, 2, 3]}
iex> List.pop_at([1, 2, 3], -1)
{3, [1, 2]}
replace_at(list(), integer(), any()) :: list()
Returns a list with a replaced value at the specified index
.
Negative indices indicate an offset from the end of the list
. If index
is out of bounds, the original list
is returned.
iex> List.replace_at([1, 2, 3], 0, 0)
[0, 2, 3]
iex> List.replace_at([1, 2, 3], 10, 0)
[1, 2, 3]
iex> List.replace_at([1, 2, 3], -1, 0)
[1, 2, 0]
iex> List.replace_at([1, 2, 3], -10, 0)
[1, 2, 3]
starts_with?([], [...]) :: false
starts_with?(list(), []) :: true
starts_with?(list(), list()) :: boolean()
Returns true
if list
starts with the given prefix
list; otherwise returns false
.
If prefix
is an empty list, it returns true
.
iex> List.starts_with?([1, 2, 3], [1, 2])
true
iex> List.starts_with?([1, 2], [1, 2, 3])
false
iex> List.starts_with?([:alpha], [])
true
iex> List.starts_with?([], [:alpha])
false
to_atom(charlist()) :: atom()
Converts a charlist to an atom.
Currently Elixir does not support conversions from charlists which contains Unicode codepoints greater than 0xFF.
Inlined by the compiler.
iex> List.to_atom('elixir')
:elixir
to_existing_atom(charlist()) :: atom()
Converts a charlist to an existing atom. Raises an ArgumentError
if the atom does not exist.
Currently Elixir does not support conversions from charlists which contains Unicode codepoints greater than 0xFF.
Inlined by the compiler.
iex> _ = :my_atom
iex> List.to_existing_atom('my_atom')
:my_atom
iex> List.to_existing_atom('this_atom_will_never_exist')
** (ArgumentError) argument error
to_float(charlist()) :: float()
Returns the float whose text representation is charlist
.
Inlined by the compiler.
iex> List.to_float('2.2017764e+0')
2.2017764
to_integer(charlist()) :: integer()
Returns an integer whose text representation is charlist
.
Inlined by the compiler.
iex> List.to_integer('123')
123
to_integer(charlist(), 2..36) :: integer()
Returns an integer whose text representation is charlist
in base base
.
Inlined by the compiler.
iex> List.to_integer('3FF', 16)
1023
to_string(:unicode.charlist()) :: String.t()
Converts a list of integers representing codepoints, lists or strings into a string.
Notice that this function expects a list of integers representing UTF-8 codepoints. If you have a list of bytes, you must instead use the :binary
module.
iex> List.to_string([0x00E6, 0x00DF])
"æß"
iex> List.to_string([0x0061, "bc"])
"abc"
iex> List.to_string([0x0064, "ee", ['p']])
"deep"
to_tuple(list()) :: tuple()
Converts a list to a tuple.
Inlined by the compiler.
iex> List.to_tuple([:share, [:elixir, 163]])
{:share, [:elixir, 163]}
update_at([elem], integer(), (elem -> any())) :: list() when elem: var
Returns a list with an updated value at the specified index
.
Negative indices indicate an offset from the end of the list
. If index
is out of bounds, the original list
is returned.
iex> List.update_at([1, 2, 3], 0, &(&1 + 10))
[11, 2, 3]
iex> List.update_at([1, 2, 3], 10, &(&1 + 10))
[1, 2, 3]
iex> List.update_at([1, 2, 3], -1, &(&1 + 10))
[1, 2, 13]
iex> List.update_at([1, 2, 3], -10, &(&1 + 10))
[1, 2, 3]
wrap(list() | any()) :: list()
Wraps the argument in a list.
If the argument is already a list, returns the list. If the argument is nil
, returns an empty list.
iex> List.wrap("hello")
["hello"]
iex> List.wrap([1, 2, 3])
[1, 2, 3]
iex> List.wrap(nil)
[]
zip([list()]) :: [tuple()]
Zips corresponding elements from each list in list_of_lists
.
The zipping finishes as soon as any list terminates.
iex> List.zip([[1, 2], [3, 4], [5, 6]])
[{1, 3, 5}, {2, 4, 6}]
iex> List.zip([[1, 2], [3], [5, 6]])
[{1, 3, 5}]
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.6.0/List.html