@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)
true

Improper lists are not printable, even if made only of ASCII characters:

iex> List.ascii_printable?(~c"abc" ++ ?d)
false

@spec delete([], any()) :: []

@spec delete([...], any()) :: list()

Deletes 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)
[]

@spec 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]

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

@spec first([], any()) :: any()

@spec first([elem, ...], any()) :: elem when elem: var

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])
1

@spec flatten(deep_list) :: list() when deep_list: [any() | deep_list]

Flattens 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])
false

@spec 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]

@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)
nil

This 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)
false

This 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)
nil

This function works for any list of tuples:

iex> List.keytake([{22, "SSH"}, {80, "HTTP"}], 80, 0)
{{80, "HTTP"}, [{22, "SSH"}]}

@spec last([], any()) :: any()

@spec last([elem, ...], any()) :: elem when elem: var

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])
3

@spec myers_difference(list(), list()) :: [{:eq | :ins | :del, list()}]

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.

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

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

@spec 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]

@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])
false

@spec to_atom(charlist()) :: atom()

Converts 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"

@spec to_existing_atom(charlist()) :: atom()

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/1 only to convert atoms defined within the module making the function call to to_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"

@spec to_float(charlist()) :: float()

Returns the float whose text representation is charlist.

Inlined by the compiler.

Examples

iex> List.to_float(~c"2.2017764e+0")
2.2017764

@spec to_integer(charlist()) :: integer()

Returns an integer whose text representation is charlist.

Inlined by the compiler.

Examples

iex> List.to_integer(~c"123")
123

@spec to_integer(
  charlist(),
  2..36
) :: integer()

Returns 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([])
""

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

@spec 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]

@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)
[]

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