Elixir v1.1.0 List

Implements functions that only make sense for lists and cannot be part of the Enum protocol. In general, favor using the Enum API instead of List.

Some functions in this module expect an index. 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 the operation.

A decision was taken to delegate most functions to Erlang’s standard library but follow Elixir’s convention of receiving the target (in this case, a list) as the first argument.

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. If index is out of bounds, the original list is returned

duplicate(elem, n)

Duplicates the given element n times in a list

first(list)

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

flatten(list)

Flattens the given list of nested lists

flatten(list, tail)

Flattens the given list of nested lists. The list tail 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 specified index. Note that index 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 given key. 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 given key

keymember?(list, key, position)

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

keyreplace(list, key, position, new_tuple)

Receives a list of tuples and replaces the item identified by key at position 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 at position. 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 at position in the tuple matches the given key, as well as the list without found tuple

last(list)

Returns the last element in list or nil if list 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. If index is out of bounds, the original list is returned

to_atom(char_list)

Converts a char list to an atom

to_existing_atom(char_list)

Converts a char list to an existing atom. Raises an ArguementError if the atom does not exist

to_float(char_list)

Returns the float whose text representation is char_list

to_integer(char_list)

Returns an integer whose text representation is char_list

to_integer(char_list, base)

Returns an integer whose text representation is char_list in base base

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. If index is out of bounds, the original list 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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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(char_list)

Specs

to_atom(char_list) :: atom

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')
:elixir

to_existing_atom(char_list)

Specs

to_existing_atom(char_list) :: atom

Converts a char list to an existing atom. Raises an ArguementError 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 error

to_float(char_list)

Specs

to_float(char_list) :: float

Returns the float whose text representation is char_list.

Inlined by the compiler.

Examples

iex> List.to_float('2.2017764e+0')
2.2017764

to_integer(char_list)

Specs

to_integer(char_list) :: integer

Returns an integer whose text representation is char_list.

Inlined by the compiler.

Examples

iex> List.to_integer('123')
123

to_integer(char_list, base)

Specs

to_integer(char_list, 2 .. 36) :: integer

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

Inlined by the compiler.

Examples

iex> List.to_integer('3FF', 16)
1023

to_string(list)

Specs

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)

Specs

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)

Specs

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)

Specs

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)

Specs

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