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
| 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 |
| duplicate(elem, n) | Duplicates the given element |
| first(list1) | Returns the first element in |
| flatten(list) | Flattens the given |
| flatten(list, tail) | Flattens the given |
| foldl(list, acc, function) | Folds (reduces) the given list to the left with a function. Requires an accumulator |
| foldr(list, acc, function) | Folds (reduces) the given list to the right with a function. Requires an accumulator |
| insert_at(list, index, value) | Returns a list with |
| keydelete(list, key, position) | Receives a list of tuples and deletes the first tuple
where the item at |
| keyfind(list, key, position, default \\ nil) | Receives a list of tuples and returns the first tuple
where the item at |
| keymember?(list, key, position) | Receives a list of tuples and returns |
| keyreplace(list, key, position, new_tuple) | Receives a list of tuples and replaces the item
identified by |
| keysort(list, position) | Receives a list of tuples and sorts the items
at |
| keystore(list, key, position, new_tuple) | Receives a list of tuples and replaces the item
identified by |
| last(list1) | Returns the last element in |
| replace_at(list, index, value) | Returns a list with a replaced value at the specified |
| unzip(list) | Unzips the given list of lists or tuples into separate lists and returns a list of lists |
| update_at(list, index, fun) | Returns a list with an updated value at the specified |
| wrap(list) | Wraps the argument in a list.
If the argument is already a list, returns the list.
If the argument is |
| zip(list_of_lists) | Zips corresponding elements from each list in |
Functions
Specs:
- delete([], any) :: []
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]
Specs:
- delete_at([], integer) :: []
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]
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]]
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
Specs:
- flatten(deep_list) :: [] when deep_list: [any | deep_list]
Flattens the given list of nested lists.
Examples
iex> List.flatten([1, [[2], 3]])
[1,2,3]
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]
Specs:
- foldl([elem], acc, (elem, acc -> acc)) :: acc when elem: var, acc: var
Folds (reduces) the given list to 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
Specs:
- foldr([elem], acc, (elem, acc -> acc)) :: acc when elem: var, acc: var
Folds (reduces) the given list to the right with a function. Requires an accumulator.
Examples
iex> List.foldr([1, 2, 3, 4], 0, fn (x, acc) -> x - acc end)
-2
Specs:
- insert_at([], integer, any) :: []
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]
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 item. 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]
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 item.
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
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 item.
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
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]
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]
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]
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
Specs:
- replace_at([], integer, any) :: []
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]
Specs:
- unzip([tuple]) :: [[]]
Unzips the given list of lists or tuples into separate lists and returns a list of lists.
Examples
iex> List.unzip([{1, 2}, {3, 4}])
[[1, 3], [2, 4]]
iex> List.unzip([{1, :a, "apple"}, {2, :b, "banana"}, {3, :c}])
[[1, 2, 3], [:a, :b, :c]]
Specs:
- update_at([elem], integer, (elem -> any)) :: [] 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]
Specs:
- wrap([] | any) :: []
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)
[]