List
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.
Charlists
If a list is made of non-negative integers, it can also be called as 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
:
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
- delete(list, item)
-
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
- delete_at(list, index)
-
Produces a new list by removing the value at the specified
index
. Negative indices indicate an offset from the end of the list. Ifindex
is out of bounds, the originallist
is returned - duplicate(elem, n)
-
Duplicates the given element
n
times in a list - first(list)
-
Returns the first element in
list
ornil
iflist
is empty - flatten(list)
-
Flattens the given
list
of nested lists - flatten(list, tail)
-
Flattens the given
list
of nested lists. The listtail
will be added at the end of the flattened list - foldl(list, acc, function)
-
Folds (reduces) the given list from the left with a function. Requires an accumulator
- foldr(list, acc, function)
-
Folds (reduces) the given list from the right with a function. Requires an accumulator
- insert_at(list, index, value)
-
Returns a list with
value
inserted at the specifiedindex
. Note thatindex
is capped at the list length. Negative indices indicate an offset from the end of the list - keydelete(list, key, position)
-
Receives a list of tuples and deletes the first tuple where the item at
position
matches the givenkey
. Returns the new list - keyfind(list, key, position, default \\ nil)
-
Receives a list of tuples and returns the first tuple where the item at
position
in the tuple matches the givenkey
- keymember?(list, key, position)
-
Receives a list of tuples and returns
true
if there is a tuple where the item atposition
in the tuple matches the givenkey
- keyreplace(list, key, position, new_tuple)
-
Receives a list of tuples and replaces the item identified by
key
atposition
if it exists - keysort(list, position)
-
Receives a list of tuples and sorts the items at
position
of the tuples. The sort is stable - keystore(list, key, position, new_tuple)
-
Receives a list of tuples and replaces the item identified by
key
atposition
. If the item does not exist, it is added to the end of the list - keytake(list, key, position)
-
Receives a
list
of tuples and returns the first tuple where the element atposition
in the tuple matches the givenkey
, as well as thelist
without found tuple - last(list)
-
Returns the last element in
list
ornil
iflist
is empty - replace_at(list, index, value)
-
Returns a list with a replaced value at the specified
index
. Negative indices indicate an offset from the end of the list. Ifindex
is out of bounds, the originallist
is returned - to_atom(charlist)
-
Converts a charlist to an atom
- to_existing_atom(charlist)
-
Converts a charlist to an existing atom. Raises an
ArgumentError
if the atom does not exist - to_float(charlist)
-
Returns the float whose text representation is
charlist
- to_integer(charlist)
-
Returns an integer whose text representation is
charlist
- to_integer(charlist, base)
-
Returns an integer whose text representation is
charlist
in basebase
- to_string(list)
-
Converts a list of integers representing codepoints, lists or strings into a string
- to_tuple(list)
-
Converts a list to a tuple
- update_at(list, index, fun)
-
Returns a list with an updated value at the specified
index
. Negative indices indicate an offset from the end of the list. Ifindex
is out of bounds, the originallist
is returned - wrap(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 - zip(list_of_lists)
-
Zips corresponding elements from each list in
list_of_lists
Functions
delete(list, item)
delete(list, any) :: list
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]
delete_at(list, index)
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]
duplicate(elem, n)
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]]
first(list)
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
flatten(list)
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]
flatten(list, tail)
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]
foldl(list, acc, function)
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
foldr(list, acc, function)
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
insert_at(list, index, value)
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]
keydelete(list, key, position)
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]
keyfind(list, key, position, default \\ nil)
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
keymember?(list, key, position)
keymember?([tuple], any, non_neg_integer) :: any
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
keyreplace(list, key, position, new_tuple)
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]
keysort(list, position)
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]
keystore(list, key, position, new_tuple)
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]
keytake(list, key, position)
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
last(list)
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
replace_at(list, index, value)
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]
to_atom(charlist)
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
to_existing_atom(charlist)
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
to_float(charlist)
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
to_integer(charlist)
to_integer(charlist) :: integer
Returns an integer whose text representation is charlist
.
Inlined by the compiler.
Examples
iex> List.to_integer('123')
123
to_integer(charlist, base)
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
to_string(list)
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"
to_tuple(list)
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]}
update_at(list, index, fun)
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]
wrap(list)
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)
[]
zip(list_of_lists)
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}]
© 2012–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.3.4/List.html