Elixir v1.6.0-dev List View Source

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.

Charlists

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'}]

List and Enum modules

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.

Link to this section Summary

Functions

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

Link to this section Functions

Link to this function delete(list, item) View Source
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.

Examples

iex> List.delete([:a, :b, :c], :a)
[:b, :c]

iex> List.delete([:a, :b, :b, :c], :b)
[:a, :b, :c]
Link to this function delete_at(list, index) View Source
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.

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]
Link to this function duplicate(elem, n) View Source
duplicate(elem, non_neg_integer) :: [elem] when elem: var

Duplicates the given element n times in a list.

Examples

iex> List.duplicate("hello", 3)
["hello", "hello", "hello"]

iex> List.duplicate([1, 2], 2)
[[1, 2], [1, 2]]
Link to this function first(list) View Source
first([elem]) :: nil | elem when elem: var

Returns the first element in list or nil if list is empty.

Examples

iex> List.first([])
nil

iex> List.first([1])
1

iex> List.first([1, 2, 3])
1
Link to this function flatten(list) View Source
flatten(deep_list) :: list when deep_list: [any | deep_list]

Flattens the given list of nested lists.

Examples

iex> List.flatten([1, [[2], 3]])
[1, 2, 3]
Link to this function flatten(list, tail) View Source
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.

Examples

iex> List.flatten([1, [[2], 3]], [4, 5])
[1, 2, 3, 4, 5]
Link to this function foldl(list, acc, function) View Source
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.

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
Link to this function foldr(list, acc, function) View Source
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.

Examples

iex> List.foldr([1, 2, 3, 4], 0, fn(x, acc) -> x - acc end)
-2
Link to this function insert_at(list, index, value) View Source
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.

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]
Link to this function keydelete(list, key, position) View Source
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.

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]
Link to this function keyfind(list, key, position, default \\ nil) View Source
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.

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)
nil
Link to this function keymember?(list, key, position) View Source
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.

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)
false
Link to this function keyreplace(list, key, position, new_tuple) View Source
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.

Examples

iex> List.keyreplace([a: 1, b: 2], :a, 0, {:a, 3})
[a: 3, b: 2]
Link to this function keysort(list, position) View Source
keysort([tuple], non_neg_integer) :: [tuple]

Receives a list of tuples and sorts the items at position of the tuples. The sort is stable.

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]
Link to this function keystore(list, key, position, new_tuple) View Source
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.

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]
Link to this function keytake(list, key, position) View Source
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)
nil
Link to this function last(list) View Source
last([elem]) :: nil | elem when elem: var

Returns the last element in list or nil if list is empty.

Examples

iex> List.last([])
nil

iex> List.last([1])
1

iex> List.last([1, 2, 3])
3
Link to this function myers_difference(list1, list2) View Source
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.

Examples

iex> List.myers_difference([1, 4, 2, 3], [1, 2, 3, 4])
[eq: [1], del: [4], eq: [2, 3], ins: [4]]
Link to this function pop_at(list, index, default \\ nil) View Source
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.

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]}
Link to this function replace_at(list, index, value) View Source
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.

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]
Link to this function starts_with?(list, prefix) View Source
starts_with?(list, list) :: boolean
starts_with?(list, []) :: true
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])
false
Link to this function to_atom(charlist) View Source
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.

Examples

iex> List.to_atom('elixir')
:elixir
Link to this function to_existing_atom(charlist) View Source
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.

Examples

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
Link to this function to_float(charlist) View Source
to_float(charlist) :: float

Returns the float whose text representation is charlist.

Inlined by the compiler.

Examples

iex> List.to_float('2.2017764e+0')
2.2017764
Link to this function to_integer(charlist) View Source
to_integer(charlist) :: integer

Returns an integer whose text representation is charlist.

Inlined by the compiler.

Examples

iex> List.to_integer('123')
123
Link to this function to_integer(charlist, base) View Source
to_integer(charlist, 2..36) :: integer

Returns an integer whose text representation is charlist in base base.

Inlined by the compiler.

Examples

iex> List.to_integer('3FF', 16)
1023
Link to this function to_string(list) View Source
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.

Examples

iex> List.to_string([0x00E6, 0x00DF])
"æß"

iex> List.to_string([0x0061, "bc"])
"abc"
Link to this function to_tuple(list) View Source
to_tuple(list) :: tuple

Converts a list to a tuple.

Inlined by the compiler.

Examples

iex> List.to_tuple([:share, [:elixir, 163]])
{:share, [:elixir, 163]}
Link to this function update_at(list, index, fun) View Source
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.

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]
Link to this function wrap(list) View Source
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.

Examples

iex> List.wrap("hello")
["hello"]

iex> List.wrap([1, 2, 3])
[1, 2, 3]

iex> List.wrap(nil)
[]
Link to this function zip(list_of_lists) View Source
zip([list]) :: [tuple]

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}]