/Elixir 1.7

# List

Functions that work on (linked) lists.

Many of the functions provided for lists, which implement the `Enumerable` protocol, are found in the `Enum` module.

Additionally, the following functions and operators for lists are found in `Kernel`:

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

Additonally, getting a list’s length and accessing it by index are linear time operations. Negative indexes are also supported but they imply the list will be iterated twice, once to calculate the proper index and another time to perform the operation.

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

A list can be checked if it is made of printable ascii codepoints with `ascii_printable?/2`.

# Summary

## Functions

ascii_printable?(list, counter \\ :infinity)

Checks if a list is a charlist made only of printable ASCII characters

delete(list, item)

Deletes the given `item` from the `list`. Returns a new list without the item

delete_at(list, index)

Produces a new list by removing the value at the specified `index`

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, fun)

Folds (reduces) the given list from the left with a function. Requires an accumulator

foldr(list, acc, fun)

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`

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`

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

myers_difference(list1, list2)

Returns a keyword list that represents an edit script

pop_at(list, index, default \\ nil)

Returns and removes the value at the specified `index` in the `list`

replace_at(list, index, value)

Returns a list with a replaced value at the specified `index`

starts_with?(list, prefix)

Returns `true` if `list` starts with the given `prefix` list; otherwise returns `false`

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 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`

wrap(term)

Wraps `term` in a list if this is not list

zip(list_of_lists)

Zips corresponding elements from each list in `list_of_lists`

# Functions

### ascii_printable?(list, counter \\ :infinity)(since 1.6.0)

Checks if a list is a charlist made only of printable ASCII characters.

A printable charlist in Elixir contains only ASCII characters.

Takes an optional `limit` as a second argument. `ascii_printable?/2` only checks the printability of the list up to the `limit`.

#### Examples

```iex> List.ascii_printable?('abc')
true

iex> List.ascii_printable?('abc' ++ [0])
false

iex> List.ascii_printable?('abc' ++ [0], 2)
true```

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

```iex> List.ascii_printable?('abc' ++ ?d)
false```

### delete(list, item)

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

### 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, fun)

`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, fun)

`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()) :: 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```

### 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```

### myers_difference(list1, list2)(since 1.4.0)

`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`.

#### Examples

```iex> List.myers_difference([1, 4, 2, 3], [1, 2, 3, 4])
[eq: [1], del: [4], eq: [2, 3], ins: [4]]```

### pop_at(list, index, default \\ nil)(since 1.4.0)

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

### 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]```

### starts_with?(list, prefix)(since 1.5.0)

`starts_with?([], [...]) :: false`
`starts_with?(list(), []) :: true`
`starts_with?(list(), list()) :: boolean()`

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```

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

iex> List.to_string([0x0064, "ee", ['p']])
"deep"```

### 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(term)

`wrap(term) :: [term, ...] when term: any()`
`wrap(list) :: list when list: maybe_improper_list()`
`wrap(nil) :: []`

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

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