Elixir v1.2.6 List
Specialized functions that only work on lists.
In general, favor using the Enum API instead of List.
Index access for 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.
A decision was taken to delegate most functions to Erlang’s standard library but follow Elixir’s convention of receiving the subject (in this case, a list) as the first argument.
Char lists
If a list is made of non-negative integers, it can also be called as a char list. Elixir uses single quotes to define char lists:
iex> 'héllo'
[104, 233, 108, 108, 111]In particular, char lists 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 char lists
instead of Elixir strings. One example of such functions
is Application.loaded_applications:
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'}]Summary
Functions
Deletes the given item from the list. Returns a list without the item. If the item occurs more than once in the list, just the first occurrence is removed
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
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.
Note that index is capped at the list length. Negative indices
indicate an offset from the end of the list
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. If the item
does not exist, it is added to the end of the list
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 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
Converts a char list to an atom
Converts a char list to an existing atom. Raises an ArgumentError
if the atom does not exist
Returns the float whose text representation is char_list
Returns an integer whose text representation is char_list
Returns an integer whose text representation is char_list 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.
Negative indices indicate an offset from the end of the list.
If index is out of bounds, the original list is returned
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
Zips corresponding elements from each list in list_of_lists
Functions
Deletes the given item from the list. Returns a list without the item. If the item occurs more than once in the list, just the first occurrence is removed.
Examples
iex> List.delete([1, 2, 3], 1)
[2, 3]
iex> List.delete([1, 2, 2, 3], 2)
[1, 2, 3]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]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]]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])
1flatten(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]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)
2Folds (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)
-2Returns 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]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]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)
nilReceives 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)
falsekeyreplace([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]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]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]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)
nilReturns 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])
3Returns 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]Converts a char list to an atom.
Currently Elixir does not support conversions from char lists which contains Unicode codepoints greater than 0xFF.
Inlined by the compiler.
Examples
iex> List.to_atom('elixir')
:elixirConverts a char list to an existing atom. Raises an ArgumentError
if the atom does not exist.
Currently Elixir does not support conversions from char lists 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 errorReturns the float whose text representation is char_list.
Inlined by the compiler.
Examples
iex> List.to_float('2.2017764e+0')
2.2017764Returns an integer whose text representation is char_list.
Inlined by the compiler.
Examples
iex> List.to_integer('123')
123Returns an integer whose text representation is char_list in base base.
Inlined by the compiler.
Examples
iex> List.to_integer('3FF', 16)
1023Converts 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"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]