View Source List (Elixir v1.15.3)
Linked lists hold zero, one, or more elements in the chosen order.
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
++/2 and --/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]An element can be prepended to a list using |:
iex> new = 0
iex> list = [1, 2, 3]
iex> [new | list]
[0, 1, 2, 3]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]Most of the functions in this module work in linear time. This means that,
that the time it takes to perform an operation grows at the same rate as the
length of the list. For example length/1 and last/1 will run in linear
time because they need to iterate through every element of the list, but
first/1 will run in constant time because it only needs the first element.
Lists also implement the Enumerable protocol, so many functions to work with
lists are found in the Enum module. Additionally, the following functions and
operators for lists are found in Kernel:
Charlists
If a list is made of non-negative integers, where each integer represents a Unicode code point, the list can also be called a charlist. These integers must:
- be within the range
0..0x10FFFF(0..1_114_111); - and be out of the range
0xD800..0xDFFF(55_296..57_343), which is reserved in Unicode for UTF-16 surrogate pairs.
Elixir uses the ~c sigil to define charlists:
iex> ~c"héllo"
[104, 233, 108, 108, 111]In particular, charlists will be printed back by default with the ~c
sigil if they contain only printable ASCII characters:
iex> ~c"abc"
~c"abc"Even though the representation changed, the raw data does remain a list of integers, which can be handled as such:
iex> inspect(~c"abc", charlists: :as_list)
"[97, 98, 99]"
iex> Enum.map(~c"abc", fn num -> 1000 + num end)
[1097, 1098, 1099]You can use the IEx.Helpers.i/1 helper to get a condensed rundown on
charlists in IEx when you encounter them, which shows you the type, description
and also the raw representation in one single summary.
The rationale behind this behaviour is to better support
Erlang libraries which may return text as charlists
instead of Elixir strings. In Erlang, charlists are the default
way of handling strings, while in Elixir it's binaries. One
example of such functions is Application.loaded_applications/0:
Application.loaded_applications()
#=> [
#=> {:stdlib, ~c"ERTS CXC 138 10", ~c"2.6"},
#=> {:compiler, ~c"ERTS CXC 138 10", ~c"6.0.1"},
#=> {:elixir, ~c"elixir", ~c"1.0.0"},
#=> {:kernel, ~c"ERTS CXC 138 10", ~c"4.1"},
#=> {:logger, ~c"logger", ~c"1.0.0"}
#=> ]A list can be checked if it is made of only printable ASCII
characters with ascii_printable?/2.
Improper lists are never deemed as charlists.
Summary
Functions
Checks if list is a charlist made only of printable ASCII characters.
Deletes the given element from the list. Returns a new list without
the element.
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 default 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, which can be any value.
Folds (reduces) the given list from the right with a function. Requires an accumulator, which can be any value.
Returns true if list is an improper list. Otherwise returns false.
Returns a list with value inserted at the specified index.
Receives a list of tuples and deletes the first tuple
where the element at position matches the
given key. Returns the new list.
Receives a list of tuples and returns the first tuple
where the element at position in the tuple matches the
given key.
Receives a list of tuples and returns the first tuple
where the element at position in the tuple matches the
given key.
Receives a list of tuples and returns true if there is
a tuple where the element at position in the tuple matches
the given key.
Receives a list of tuples and if the identified element by key at position
exists, it is replaced with new_tuple.
Receives a list of tuples and sorts the elements
at position of the tuples.
Receives a list of tuples and replaces the element
identified by key at position with new_tuple.
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 default if list is empty.
Returns a keyword list that represents an edit script.
Returns a keyword list that represents an edit script with nested diffs.
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 list of integers representing Unicode code points, lists or strings into a charlist.
Converts a charlist to an existing atom.
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 code points, lists or strings into a string.
Converts a list to a tuple.
Returns a list with an updated value at the specified index.
Wraps term in a list if this is not list.
Zips corresponding elements from each list in list_of_lists.
Functions
@spec ascii_printable?(list(), 0) :: true
@spec ascii_printable?([], limit) :: true when limit: :infinity | pos_integer()
@spec ascii_printable?([...], limit) :: boolean() when limit: :infinity | pos_integer()
Checks if list is a charlist made only of printable ASCII characters.
Takes an optional limit as a second argument. ascii_printable?/2 only
checks the printability of the list up to the limit.
A printable charlist in Elixir contains only the printable characters in the standard seven-bit ASCII character encoding, which are characters ranging from 32 to 126 in decimal notation, plus the following control characters:
?\a- Bell?\b- Backspace?\t- Horizontal tab?\n- Line feed?\v- Vertical tab?\f- Form feed?\r- Carriage return?\e- Escape
For more information read the Character groups section in the Wikipedia article of the ASCII standard.
Examples
iex> List.ascii_printable?(~c"abc")
true
iex> List.ascii_printable?(~c"abc" ++ [0])
false
iex> List.ascii_printable?(~c"abc" ++ [0], 2)
trueImproper lists are not printable, even if made only of ASCII characters:
iex> List.ascii_printable?(~c"abc" ++ ?d)
falseDeletes the given element from the list. Returns a new list without
the element.
If the element occurs more than once in the list, just
the first occurrence is removed.
Examples
iex> List.delete([:a, :b, :c], :a)
[:b, :c]
iex> List.delete([:a, :b, :c], :d)
[:a, :b, :c]
iex> List.delete([:a, :b, :b, :c], :b)
[:a, :b, :c]
iex> List.delete([], :b)
[]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.
Examples
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]@spec duplicate(any(), 0) :: []
@spec duplicate(elem, pos_integer()) :: [elem, ...] when elem: var
Duplicates the given element n times in a list.
n is an integer greater than or equal to 0.
If n is 0, an empty list is returned.
Examples
iex> List.duplicate("hello", 0)
[]
iex> List.duplicate("hi", 1)
["hi"]
iex> List.duplicate("bye", 2)
["bye", "bye"]
iex> List.duplicate([1, 2], 3)
[[1, 2], [1, 2], [1, 2]]Returns the first element in list or default if list is empty.
first/2 has been introduced in Elixir v1.12.0, while first/1 has been available since v1.0.0.
Examples
iex> List.first([])
nil
iex> List.first([], 1)
1
iex> List.first([1])
1
iex> List.first([1, 2, 3])
1Flattens the given list of nested lists.
Empty list elements are discarded.
Examples
iex> List.flatten([1, [[2], 3]])
[1, 2, 3]
iex> List.flatten([[], [[], []]])
[]@spec 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.
Empty list elements from list are discarded,
but not the ones from tail.
Examples
iex> List.flatten([1, [[2], 3]], [4, 5])
[1, 2, 3, 4, 5]
iex> List.flatten([1, [], 2], [3, [], 4])
[1, 2, 3, [], 4]@spec 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, which can be any value.
Examples
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
iex> List.foldl([1, 2, 3], {0, 0}, fn x, {a1, a2} -> {a1 + x, a2 - x} end)
{6, -6}@spec 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, which can be any value.
Examples
iex> List.foldr([1, 2, 3, 4], 0, fn x, acc -> x - acc end)
-2
iex> List.foldr([1, 2, 3, 4], %{sum: 0, product: 1}, fn x, %{sum: a1, product: a2} -> %{sum: a1 + x, product: a2 * x} end)
%{product: 24, sum: 10}@spec improper?(maybe_improper_list()) :: boolean()
Returns true if list is an improper list. Otherwise returns false.
Examples
iex> List.improper?([1, 2 | 3])
true
iex> List.improper?([1, 2, 3])
falseReturns 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.
Examples
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]@spec keydelete([tuple()], any(), non_neg_integer()) :: [tuple()]
Receives a list of tuples and deletes the first tuple
where the element at position matches the
given key. Returns the new list.
Examples
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]This function works for any list of tuples:
iex> List.keydelete([{22, "SSH"}, {80, "HTTP"}], 80, 0)
[{22, "SSH"}]@spec keyfind([tuple()], any(), non_neg_integer(), any()) :: any()
Receives a list of tuples and returns the first tuple
where the element at position in the tuple matches the
given key.
If no matching tuple is found, default is returned.
Examples
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)
nilThis function works for any list of tuples:
iex> List.keyfind([{22, "SSH"}, {80, "HTTP"}], 22, 0)
{22, "SSH"}@spec keyfind!([tuple()], any(), non_neg_integer()) :: any()
Receives a list of tuples and returns the first tuple
where the element at position in the tuple matches the
given key.
If no matching tuple is found, an error is raised.
Examples
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)
** (KeyError) key :c at position 0 not found in: [a: 1, b: 2]This function works for any list of tuples:
iex> List.keyfind!([{22, "SSH"}, {80, "HTTP"}], 22, 0)
{22, "SSH"}@spec keymember?([tuple()], any(), non_neg_integer()) :: boolean()
Receives a list of tuples and returns true if there is
a tuple where the element at position in the tuple matches
the given key.
Examples
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)
falseThis function works for any list of tuples:
iex> List.keymember?([{22, "SSH"}, {80, "HTTP"}], 22, 0)
true@spec keyreplace([tuple()], any(), non_neg_integer(), tuple()) :: [tuple()]
Receives a list of tuples and if the identified element by key at position
exists, it is replaced with new_tuple.
Examples
iex> List.keyreplace([a: 1, b: 2], :a, 0, {:a, 3})
[a: 3, b: 2]
iex> List.keyreplace([a: 1, b: 2], :a, 1, {:a, 3})
[a: 1, b: 2]This function works for any list of tuples:
iex> List.keyreplace([{22, "SSH"}, {80, "HTTP"}], 22, 0, {22, "Secure Shell"})
[{22, "Secure Shell"}, {80, "HTTP"}]@spec keysort( [tuple()], non_neg_integer(), (any(), any() -> boolean()) | :asc | :desc | module() | {:asc | :desc, module()} ) :: [tuple()]
Receives a list of tuples and sorts the elements
at position of the tuples.
The sort is stable.
A sorter argument is available since Elixir v1.14.0. Similar to
Enum.sort/2, the sorter can be an anonymous function, the atoms
:asc or :desc, or module that implements a compare function.
Examples
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]To sort in descending order:
iex> List.keysort([a: 5, c: 1, b: 3], 0, :desc)
[c: 1, b: 3, a: 5]As in Enum.sort/2, avoid using the default sorting function to sort
structs, as by default it performs structural comparison instead of a
semantic one. In such cases, you shall pass a sorting function as third
element or any module that implements a compare/2 function. For example,
if you have tuples with user names and their birthday, and you want to
sort on their birthday, in both ascending and descending order, you should
do:
iex> users = [
...> {"Ellis", ~D[1943-05-11]},
...> {"Lovelace", ~D[1815-12-10]},
...> {"Turing", ~D[1912-06-23]}
...> ]
iex> List.keysort(users, 1, Date)
[
{"Lovelace", ~D[1815-12-10]},
{"Turing", ~D[1912-06-23]},
{"Ellis", ~D[1943-05-11]}
]
iex> List.keysort(users, 1, {:desc, Date})
[
{"Ellis", ~D[1943-05-11]},
{"Turing", ~D[1912-06-23]},
{"Lovelace", ~D[1815-12-10]}
]@spec keystore([tuple()], any(), non_neg_integer(), tuple()) :: [tuple(), ...]
Receives a list of tuples and replaces the element
identified by key at position with new_tuple.
If the element does not exist, it is added to the end of the list.
Examples
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]This function works for any list of tuples:
iex> List.keystore([{22, "SSH"}], 80, 0, {80, "HTTP"})
[{22, "SSH"}, {80, "HTTP"}]@spec 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.
Examples
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)
nilThis function works for any list of tuples:
iex> List.keytake([{22, "SSH"}, {80, "HTTP"}], 80, 0)
{{80, "HTTP"}, [{22, "SSH"}]}Returns the last element in list or default if list is empty.
last/2 has been introduced in Elixir v1.12.0, while last/1 has been available since v1.0.0.
Examples
iex> List.last([])
nil
iex> List.last([], 1)
1
iex> List.last([1])
1
iex> List.last([1, 2, 3])
3Returns 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.
See myers_difference/3 if you want to handle nesting in the diff scripts.
Examples
iex> List.myers_difference([1, 4, 2, 3], [1, 2, 3, 4])
[eq: [1], del: [4], eq: [2, 3], ins: [4]]@spec myers_difference(list(), list(), (term(), term() -> script | nil)) :: script when script: [{:eq | :ins | :del | :diff, list()}]
Returns a keyword list that represents an edit script with nested diffs.
This is an extension of myers_difference/2 where a diff_script function
can be given in case it is desired to compute nested differences. The function
may return a list with the inner edit script or nil in case there is no
such script. The returned inner edit script will be under the :diff key.
Examples
iex> List.myers_difference(["a", "db", "c"], ["a", "bc"], &String.myers_difference/2)
[eq: ["a"], diff: [del: "d", eq: "b", ins: "c"], del: ["c"]]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.
Examples
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]}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.
Examples
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]@spec starts_with?([...], [...]) :: boolean()
@spec starts_with?(list(), []) :: true
@spec starts_with?([], [...]) :: false
Returns true if list starts with the given prefix list; otherwise returns false.
If prefix is an empty list, it returns true.
Examples
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])
falseConverts a charlist to an atom.
Elixir supports conversions from charlists which contains any Unicode code point.
Inlined by the compiler.
Examples
iex> List.to_atom(~c"Elixir")
:Elixir
iex> List.to_atom(~c"🌢 Elixir")
:"🌢 Elixir"@spec to_charlist(:unicode.charlist()) :: charlist()
Converts a list of integers representing Unicode code points, lists or strings into a charlist.
Note that this function expects a list of integers representing
Unicode code points. If you have a list of bytes, you must instead use
the :binary module.
Examples
iex> ~c"æß" = List.to_charlist([0x00E6, 0x00DF])
[230, 223]
iex> List.to_charlist([0x0061, "bc"])
~c"abc"
iex> List.to_charlist([0x0064, "ee", [~c"p"]])
~c"deep"Converts a charlist to an existing atom.
Elixir supports conversions from charlists which contains any Unicode
code point. Raises an ArgumentError if the atom does not exist.
Inlined by the compiler.
Atoms and modules
Since Elixir is a compiled language, the atoms defined in a module will only exist after said module is loaded, which typically happens whenever a function in the module is executed. Therefore, it is generally recommended to call
List.to_existing_atom/1only to convert atoms defined within the module making the function call toto_existing_atom/1.
Examples
iex> _ = :my_atom
iex> List.to_existing_atom(~c"my_atom")
:my_atom
iex> _ = :"🌢 Elixir"
iex> List.to_existing_atom(~c"🌢 Elixir")
:"🌢 Elixir"Returns the float whose text representation is charlist.
Inlined by the compiler.
Examples
iex> List.to_float(~c"2.2017764e+0")
2.2017764Returns an integer whose text representation is charlist.
Inlined by the compiler.
Examples
iex> List.to_integer(~c"123")
123Returns an integer whose text representation is charlist in base base.
Inlined by the compiler.
The base needs to be between 2 and 36.
Examples
iex> List.to_integer(~c"3FF", 16)
1023@spec to_string(:unicode.charlist()) :: String.t()
Converts a list of integers representing code points, lists or strings into a string.
To be converted to a string, a list must either be empty or only contain the following elements:
- strings
- integers representing Unicode code points
- a list containing one of these three elements
Note that this function expects a list of integers representing
Unicode code points. If you have a list of bytes, you must instead use
the :binary module.
Examples
iex> List.to_string([0x00E6, 0x00DF])
"æß"
iex> List.to_string([0x0061, "bc"])
"abc"
iex> List.to_string([0x0064, "ee", [~c"p"]])
"deep"
iex> List.to_string([])
""Converts a list to a tuple.
Inlined by the compiler.
Examples
iex> List.to_tuple([:share, [:elixir, 163]])
{:share, [:elixir, 163]}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.
Examples
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]@spec wrap(term()) :: maybe_improper_list()
Wraps term in a list if this is not list.
If term is already a list, it returns the list.
If term is nil, it returns an empty list.
Examples
iex> List.wrap("hello")
["hello"]
iex> List.wrap([1, 2, 3])
[1, 2, 3]
iex> List.wrap(nil)
[]Zips corresponding elements from each list in list_of_lists.
The zipping finishes as soon as any list terminates.
Examples
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}]