Enum
Provides a set of algorithms that enumerate over collections according to the
Enumerable protocol:
iex> Enum.map([1, 2, 3], fn(x) -> x * 2 end)
[2,4,6]
Some particular types, like dictionaries, yield a specific format on
enumeration. For dicts, the argument is always a { key, value } tuple:
iex> dict = HashDict.new [a: 1, b: 2]
iex> Enum.map(dict, fn { k, v } -> { k, v * 2 } end) |> Enum.sort
[a: 2, b: 4]
Note that the functions in the Enum module are eager: they always start
the enumeration of the given collection. The Stream module allows
lazy enumeration of collections and provides infinite streams.
Since the majority of the functions in Enum enumerate the whole
collection and return a list as result, infinite streams need to
be carefully used with such functions, as they can potentially run
forever. For example:
Enum.each Stream.cycle([1,2,3]), &IO.puts(&1)
Summary
| all?(collection, fun \\ fn x -> x end) | Invokes the given |
| any?(collection, fun \\ fn x -> x end) | Invokes the given |
| at(collection, n, default \\ nil) | Finds the element at the given index (zero-based).
Returns |
| chunk(coll, n) | Shortcut to |
| chunk(coll, n, step, pad \\ nil) | Returns a collection of lists containing |
| chunk_by(coll, fun) | Splits |
| concat(enumerables) | Given an enumerable of enumerables, concatenate the enumerables into a single list |
| concat(left, right) | Concatenates the enumerable on the right with the enumerable on the left |
| count(collection) | Returns the collection's size |
| count(collection, fun) | Returns the count of items in the collection for which
|
| drop(collection, count) | Drops the first |
| drop_while(collection, fun) | Drops items at the beginning of |
| each(collection, fun) | Invokes the given |
| empty?(collection) | Returns |
| fetch!(collection, n) | Finds the element at the given index (zero-based).
Raises |
| fetch(collection, n) | Finds the element at the given index (zero-based).
Returns |
| filter(collection, fun) | Filters the collection, i.e. returns only those elements
for which |
| filter_map(collection, filter, mapper) | Filters the collection and maps its values in one pass |
| find(collection, ifnone \\ nil, fun) | Returns the first item for which |
| find_index(collection, fun) | Similar to |
| find_value(collection, ifnone \\ nil, fun) | Similar to |
| flat_map(collection, fun) | Returns a new collection appending the result of invoking |
| flat_map_reduce(collection, acc, fun) | Maps and reduces a collection, flattening the given results |
| intersperse(collection, element) | Intersperses |
| join(collection, joiner \\ "") | Joins the given |
| map(collection, fun) | Returns a new collection, where each item is the result
of invoking |
| map_join(collection, joiner \\ "", mapper) | Maps and joins the given |
| map_reduce(collection, acc, fun) | Invokes the given |
| max(collection) | Returns the maximum value.
Raises |
| max_by(collection, fun) | Returns the maximum value as calculated by the given function.
Raises |
| member?(collection, value) | Checks if |
| min(collection) | Returns the minimum value.
Raises |
| min_by(collection, fun) | Returns the minimum value as calculated by the given function.
Raises |
| partition(collection, fun) | Partitions |
| reduce(collection, fun) | Invokes |
| reduce(collection, acc, fun) | Invokes |
| reject(collection, fun) | Returns elements of collection for which |
| reverse(collection) | Reverses the collection |
| reverse(collection, tail) | Reverses the collection and appends the tail.
This is an optimization for
|
| scan(enum, fun) | Applies the given function to each element in the collection, storing the result in a list and passing it as the accumulator for the next computation |
| scan(enum, acc, fun) | Applies the given function to each element in the collection,
storing the result in a list and passing it as the accumulator
for the next computation. Uses the given |
| shuffle(collection) | Returns a list of collection elements shuffled |
| slice(coll, arg2) | Returns a subset list of the given collection. Drops elements
until element position |
| slice(coll, start, count) | Returns a subset list of the given collection. Drops elements
until element position |
| sort(collection) | Returns a sorted list of collection elements. Uses the merge sort algorithm |
| sort(collection, fun) | Returns a list of collection elements sorted by the given function |
| split(collection, count) | Splits the enumerable into two collections, leaving |
| split_while(collection, fun) | Splits |
| take(collection, count) | Takes the first |
| take_every(collection, nth) | Returns a collection of every |
| take_while(collection, fun) | Takes the items at the beginning of |
| to_list(collection) | Convert |
| uniq(collection, fun \\ fn x -> x end) | Enumerates the collection, removing all duplicated items |
| with_index(collection) | Returns the collection with each element wrapped in a tuple alongside its index |
| zip(coll1, coll2) | Zips corresponding elements from two collections into one list of tuples |
Functions
Specs:
Invokes the given fun for each item in the collection and returns false
if at least one invocation returns false. Otherwise returns true.
Examples
iex> Enum.all?([2, 4, 6], fn(x) -> rem(x, 2) == 0 end)
true
iex> Enum.all?([2, 3, 4], fn(x) -> rem(x, 2) == 0 end)
false
If no function is given, it defaults to checking if
all items in the collection evaluate to true.
iex> Enum.all?([1, 2, 3])
true
iex> Enum.all?([1, nil, 3])
false
Specs:
Invokes the given fun for each item in the collection and returns true if
at least one invocation returns true. Returns false otherwise.
Examples
iex> Enum.any?([2, 4, 6], fn(x) -> rem(x, 2) == 1 end)
false
iex> Enum.any?([2, 3, 4], fn(x) -> rem(x, 2) == 1 end)
true
If no function is given, it defaults to checking if
at least one item in the collection evaluates to true.
iex> Enum.any?([false, false, false])
false
iex> Enum.any?([false, true, false])
true
Specs:
Finds the element at the given index (zero-based).
Returns default if index is out of bounds.
Examples
iex> Enum.at([2, 4, 6], 0)
2
iex> Enum.at([2, 4, 6], 2)
6
iex> Enum.at([2, 4, 6], 4)
nil
iex> Enum.at([2, 4, 6], 4, :none)
:none
Specs:
Returns a collection of lists containing n items each, where
each new chunk starts step elements into the collection.
step is optional and, if not passed, defaults to n, i.e.
chunks do not overlap. If the final chunk does not have n
elements to fill the chunk, elements are taken as necessary
from pad if it was passed. If pad is passed and does not
have enough elements to fill the chunk, then the chunk is
returned anyway with less than n elements. If pad is not
passed at all or is nil, then the partial chunk is discarded
from the result.
Examples
iex> Enum.chunk([1, 2, 3, 4, 5, 6], 2)
[[1, 2], [3, 4], [5, 6]]
iex> Enum.chunk([1, 2, 3, 4, 5, 6], 3, 2)
[[1, 2, 3], [3, 4, 5]]
iex> Enum.chunk([1, 2, 3, 4, 5, 6], 3, 2, [7])
[[1, 2, 3], [3, 4, 5], [5, 6, 7]]
iex> Enum.chunk([1, 2, 3, 4, 5, 6], 3, 3, [])
[[1, 2, 3], [4, 5, 6]]
Specs:
Splits coll on every element for which fun returns a new value.
Examples
iex> Enum.chunk_by([1, 2, 2, 3, 4, 4, 6, 7, 7], &(rem(&1, 2) == 1))
[[1], [2, 2], [3], [4, 4, 6], [7, 7]]
Specs:
Given an enumerable of enumerables, concatenate the enumerables into a single list.
Examples
iex> Enum.concat([1..3, 4..6, 7..9])
[1,2,3,4,5,6,7,8,9]
iex> Enum.concat([[1, [2], 3], [4], [5, 6]])
[1,[2],3,4,5,6]
Specs:
Concatenates the enumerable on the right with the enumerable on the left.
This function produces the same result as the Kernel.++/2 operator for lists.
Examples
iex> Enum.concat(1..3, 4..6)
[1,2,3,4,5,6]
iex> Enum.concat([1, 2, 3], [4, 5, 6])
[1,2,3,4,5,6]
Specs:
- count(t) :: non_neg_integer
Returns the collection's size.
Examples
iex> Enum.count([1, 2, 3])
3
Specs:
Returns the count of items in the collection for which
fun returns true.
Examples
iex> Enum.count([1, 2, 3, 4, 5], fn(x) -> rem(x, 2) == 0 end)
2
Specs:
- drop(t, integer) :: []
Drops the first count items from collection.
If a negative value count is given, the last count
values will be dropped. The collection is enumerated
once to retrieve the proper index and the remaining
calculation is performed from the end.
Examples
iex> Enum.drop([1, 2, 3], 2)
[3]
iex> Enum.drop([1, 2, 3], 10)
[]
iex> Enum.drop([1, 2, 3], 0)
[1,2,3]
iex> Enum.drop([1, 2, 3], -1)
[1,2]
Specs:
Drops items at the beginning of collection while fun returns true.
Examples
iex> Enum.drop_while([1, 2, 3, 4, 5], fn(x) -> x < 3 end)
[3,4,5]
Specs:
Invokes the given fun for each item in the collection.
Returns :ok.
Examples
Enum.each(["some", "example"], fn(x) -> IO.puts x end)
"some"
"example"
#=> :ok
Specs:
- empty?(t) :: boolean
Returns true if the collection is empty, otherwise false.
Examples
iex> Enum.empty?([])
true
iex> Enum.empty?([1, 2, 3])
false
Specs:
Finds the element at the given index (zero-based).
Returns { :ok, element } if found, otherwise :error.
A negative index can be passed, which means the collection is
enumerated once and the index is counted from the end (i.e.
-1 fetches the last element).
Examples
iex> Enum.fetch([2, 4, 6], 0)
{ :ok, 2 }
iex> Enum.fetch([2, 4, 6], 2)
{ :ok, 6 }
iex> Enum.fetch([2, 4, 6], 4)
:error
Specs:
Finds the element at the given index (zero-based).
Raises OutOfBoundsError if the given position
is outside the range of the collection.
Examples
iex> Enum.fetch!([2, 4, 6], 0)
2
iex> Enum.fetch!([2, 4, 6], 2)
6
iex> Enum.fetch!([2, 4, 6], 4)
** (Enum.OutOfBoundsError) out of bounds error
Specs:
Filters the collection, i.e. returns only those elements
for which fun returns true.
Examples
iex> Enum.filter([1, 2, 3], fn(x) -> rem(x, 2) == 0 end)
[2]
Specs:
Filters the collection and maps its values in one pass.
Examples
iex> Enum.filter_map([1, 2, 3], fn(x) -> rem(x, 2) == 0 end, &(&1 * 2))
[4]
Specs:
Returns the first item for which fun returns a truthy value. If no such
item is found, returns ifnone.
Examples
iex> Enum.find([2, 4, 6], fn(x) -> rem(x, 2) == 1 end)
nil
iex> Enum.find([2, 4, 6], 0, fn(x) -> rem(x, 2) == 1 end)
0
iex> Enum.find([2, 3, 4], fn(x) -> rem(x, 2) == 1 end)
3
Specs:
Similar to find/3, but returns the index (zero-based)
of the element instead of the element itself.
Examples
iex> Enum.find_index([2, 4, 6], fn(x) -> rem(x, 2) == 1 end)
nil
iex> Enum.find_index([2, 3, 4], fn(x) -> rem(x, 2) == 1 end)
1
Specs:
Similar to find/3, but returns the value of the function
invocation instead of the element itself.
Examples
iex> Enum.find_value([2, 4, 6], fn(x) -> rem(x, 2) == 1 end)
nil
iex> Enum.find_value([2, 3, 4], fn(x) -> rem(x, 2) == 1 end)
true
Specs:
Returns a new collection appending the result of invoking fun
on each corresponding item of collection.
The given function should return an enumerable.
Examples
iex> Enum.flat_map([:a, :b, :c], fn(x) -> [x, x] end)
[:a, :a, :b, :b, :c, :c]
iex> Enum.flat_map([{1,3}, {4,6}], fn({x,y}) -> x..y end)
[1, 2, 3, 4, 5, 6]
Specs:
- flat_map_reduce(t, acc, fun) :: {[any], any} when fun: (element, acc -> {t, acc} | {:halt, acc}), acc: any
Maps and reduces a collection, flattening the given results.
It expects an accumulator and a function that receives each stream item
and an accumulator, and must return a tuple containing a new stream
(often a list) with the new accumulator or a tuple with :halt as first
element and the accumulator as second.
Examples
iex> enum = 1..100
iex> n = 3
iex> Enum.flat_map_reduce(enum, 0, fn i, acc ->
...> if acc < n, do: { [i], acc + 1 }, else: { :halt, acc }
...> end)
{ [1,2,3], 3 }
Specs:
Intersperses element between each element of the enumeration.
Complexity: O(n)
Examples
iex> Enum.intersperse([1, 2, 3], 0)
[1, 0, 2, 0, 3]
iex> Enum.intersperse([1], 0)
[1]
iex> Enum.intersperse([], 0)
[]
Specs:
Joins the given collection according to joiner.
joiner can be either a binary or a list and the
result will be of the same type as joiner. If
joiner is not passed at all, it defaults to an
empty binary.
All items in the collection must be convertible to a binary, otherwise an error is raised.
Examples
iex> Enum.join([1, 2, 3])
"123"
iex> Enum.join([1, 2, 3], " = ")
"1 = 2 = 3"
Specs:
Returns a new collection, where each item is the result
of invoking fun on each corresponding item of collection.
For dicts, the function expects a key-value tuple.
Examples
iex> Enum.map([1, 2, 3], fn(x) -> x * 2 end)
[2, 4, 6]
iex> Enum.map([a: 1, b: 2], fn({k, v}) -> { k, -v } end)
[a: -1, b: -2]
Specs:
Maps and joins the given collection in one pass.
joiner can be either a binary or a list and the
result will be of the same type as joiner. If
joiner is not passed at all, it defaults to an
empty binary.
All items in the collection must be convertible to a binary, otherwise an error is raised.
Examples
iex> Enum.map_join([1, 2, 3], &(&1 * 2))
"246"
iex> Enum.map_join([1, 2, 3], " = ", &(&1 * 2))
"2 = 4 = 6"
Specs:
Invokes the given fun for each item in the collection
while also keeping an accumulator. Returns a tuple where
the first element is the mapped collection and the second
one is the final accumulator.
For dicts, the first tuple element must be a { key, value }
tuple.
Examples
iex> Enum.map_reduce([1, 2, 3], 0, fn(x, acc) -> { x * 2, x + acc } end)
{ [2, 4, 6], 6 }
Specs:
Returns the maximum value.
Raises EmptyError if the collection is empty.
Examples
iex> Enum.max([1, 2, 3])
3
Specs:
Returns the maximum value as calculated by the given function.
Raises EmptyError if the collection is empty.
Examples
iex> Enum.max_by(["a", "aa", "aaa"], fn(x) -> String.length(x) end)
"aaa"
Specs:
Checks if value exists within the collection.
Membership is tested with the match (===) operator, although
enumerables like ranges may include floats inside the given
range.
Examples
iex> Enum.member?(1..10, 5)
true
iex> Enum.member?([:a, :b, :c], :d)
false
Specs:
Returns the minimum value.
Raises EmptyError if the collection is empty.
Examples
iex> Enum.min([1, 2, 3])
1
Specs:
Returns the minimum value as calculated by the given function.
Raises EmptyError if the collection is empty.
Examples
iex> Enum.min_by(["a", "aa", "aaa"], fn(x) -> String.length(x) end)
"a"
Specs:
Partitions collection into two collections, where the first one contains elements
for which fun returns a truthy value, and the second one -- for which fun
returns false or nil.
Examples
iex> Enum.partition([1, 2, 3], fn(x) -> rem(x, 2) == 0 end)
{ [2], [1,3] }
Specs:
Invokes fun for each element in the collection passing that element and the
accumulator acc as arguments. fun's return value is stored in acc.
The first element of the collection is used as the initial value of acc.
Returns the accumulator.
Examples
iex> Enum.reduce([1, 2, 3, 4], fn(x, acc) -> x * acc end)
24
Specs:
Invokes fun for each element in the collection passing that element and the
accumulator acc as arguments. fun's return value is stored in acc.
Returns the accumulator.
Examples
iex> Enum.reduce([1, 2, 3], 0, fn(x, acc) -> x + acc end)
6
Specs:
Returns elements of collection for which fun returns false.
Examples
iex> Enum.reject([1, 2, 3], fn(x) -> rem(x, 2) == 0 end)
[1, 3]
Specs:
- reverse(t) :: []
Reverses the collection.
Examples
iex> Enum.reverse([1, 2, 3])
[3, 2, 1]
Specs:
Reverses the collection and appends the tail.
This is an optimization for
Enum.concat(Enum.reverse(collection), tail).
Examples
iex> Enum.reverse([1, 2, 3], [4, 5, 6])
[3, 2, 1, 4, 5, 6]
Specs:
Applies the given function to each element in the collection, storing the result in a list and passing it as the accumulator for the next computation.
Examples
iex> Enum.scan(1..5, &(&1 + &2))
[1,3,6,10,15]
Specs:
Applies the given function to each element in the collection,
storing the result in a list and passing it as the accumulator
for the next computation. Uses the given acc as the starting value.
Examples
iex> Enum.scan(1..5, 0, &(&1 + &2))
[1,3,6,10,15]
Specs:
- shuffle(t) :: []
Returns a list of collection elements shuffled.
Notice that you need to explicitly call :random.seed/1 and
set a seed value for the random algorithm. Otherwise, the
default seed will be set which will always return the same
result. For example, one could do the following to set a seed
dynamically:
:random.seed(:erlang.now)
Examples
iex(1)> Enum.shuffle([1, 2, 3])
[3, 2, 1]
iex(2)> Enum.shuffle([1, 2, 3])
[3, 1, 2]
Specs:
Returns a subset list of the given collection. Drops elements
until element position range.first, then takes elements until element
position range.last (inclusive).
Positions are calculated by adding the number of items in the collection to negative positions (so position -3 in a collection with count 5 becomes position 2).
The first position (after adding count to negative positions) must be smaller or equal to the last position.
Examples
iex> Enum.slice(1..100, 5..10)
[6, 7, 8, 9, 10, 11]
Specs:
- slice(t, integer, non_neg_integer) :: []
Returns a subset list of the given collection. Drops elements
until element position start, then takes count elements.
Examples
iex> Enum.slice(1..100, 5, 10)
[6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
Specs:
- sort(t) :: []
Returns a sorted list of collection elements. Uses the merge sort algorithm.
Examples
iex> Enum.sort([3, 2, 1])
[1,2,3]
Specs:
Returns a list of collection elements sorted by the given function.
Uses the merge sort algorithm.
Examples
iex> Enum.sort([1, 2, 3], &(&1 > &2))
[3,2,1]
Specs:
- split(t, integer) :: {[], []}
Splits the enumerable into two collections, leaving count
elements in the first one. If count is a negative number,
it starts counting from the back to the beginning of the
collection.
Be aware that a negative count implies the collection
will be enumerated twice: once to calculate the position, and
a second time to do the actual splitting.
Examples
iex> Enum.split([1, 2, 3], 2)
{ [1,2], [3] }
iex> Enum.split([1, 2, 3], 10)
{ [1,2,3], [] }
iex> Enum.split([1, 2, 3], 0)
{ [], [1,2,3] }
iex> Enum.split([1, 2, 3], -1)
{ [1,2], [3] }
iex> Enum.split([1, 2, 3], -5)
{ [], [1,2,3] }
Specs:
Splits collection in two while fun returns true.
Examples
iex> Enum.split_while([1, 2, 3, 4], fn(x) -> x < 3 end)
{ [1, 2], [3, 4] }
Specs:
- take(t, integer) :: []
Takes the first count items from the collection.
If a negative count is given, the last count values will
be taken. For such, the collection is fully enumerated keeping up
to 2 * count elements in memory. Once the end of the collection is
reached, the last count elements are returned.
Examples
iex> Enum.take([1, 2, 3], 2)
[1,2]
iex> Enum.take([1, 2, 3], 10)
[1,2,3]
iex> Enum.take([1, 2, 3], 0)
[]
iex> Enum.take([1, 2, 3], -1)
[3]
Specs:
- take_every(t, integer) :: []
Returns a collection of every nth item in the collection,
starting with the first element.
Examples
iex> Enum.take_every(1..10, 2)
[1, 3, 5, 7, 9]
Specs:
Takes the items at the beginning of collection while fun returns true.
Examples
iex> Enum.take_while([1, 2, 3], fn(x) -> x < 3 end)
[1, 2]
Specs:
- to_list(t) :: [term]
Convert collection to a list.
Examples
iex> Enum.to_list(1 .. 3)
[1, 2, 3]
Specs:
Enumerates the collection, removing all duplicated items.
Examples
iex> Enum.uniq([1, 2, 3, 2, 1])
[1, 2, 3]
iex> Enum.uniq([{1, :x}, {2, :y}, {1, :z}], fn {x, _} -> x end)
[{1,:x}, {2,:y}]
Specs:
Returns the collection with each element wrapped in a tuple alongside its index.
Examples
iex> Enum.with_index [1,2,3]
[{1,0},{2,1},{3,2}]
Specs:
Zips corresponding elements from two collections into one list of tuples.
The zipping finishes as soon as any enumerable completes.
Examples
iex> Enum.zip([1, 2, 3], [:a, :b, :c])
[{1,:a},{2,:b},{3,:c}]
iex> Enum.zip([1,2,3,4,5], [:a, :b, :c])
[{1,:a},{2,:b},{3,:c}]