Elixir v1.2.6 Enum

Provides a set of algorithms that enumerate over enumerables 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 = %{a: 1, b: 2}
iex> Enum.map(dict, fn {k, v} -> {k, v * 2} end)
[a: 2, b: 4]

Note that the functions in the Enum module are eager: they always start the enumeration of the given enumerable. The Stream module allows lazy enumeration of enumerables and provides infinite streams.

Since the majority of the functions in Enum enumerate the whole enumerable 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

Functions

Invokes the given fun for each item in the enumerable. It stops the iteration at the first invocation that returns false or nil. It returns false if at least one invocation returns false or nil. Otherwise returns true

Invokes the given fun for each item in the enumerable. It stops the iteration at the first invocation that returns a truthy value. Returns true if at least one invocation returns a truthy value. Otherwise returns false

Finds the element at the given index (zero-based)

Shortcut to chunk(enumerable, count, count)

Returns list of lists containing count items each, where each new chunk starts step elements into the enumerable

Splits enumerable on every element for which fun returns a new value

Given an enumerable of enumerables, concatenates the enumerables into a single list

Concatenates the enumerable on the right with the enumerable on the left

Returns the size of the enumerable

Returns the count of items in the enumerable for which fun returns a truthy value

Enumerates the enumerable, returning a list where all consecutive duplicated elements are collapsed to a single element

Enumerates the enumerable, returning a list where all consecutive duplicated elements are collapsed to a single element

Drops the first n items from then enumerable

Drops items at the beginning of the enumerable while fun returns a truthy value

Invokes the given fun for each item in the enumerable

Determines if the enumerable is empty

Finds the element at the given index (zero-based)

Finds the element at the given index (zero-based)

Filters the enumerable, i.e. returns only those elements for which fun returns a truthy value

Filters the enumerable and maps its elements in one pass

Returns the first item for which fun returns a truthy value. If no such item is found, returns default

Similar to find/3, but returns the index (zero-based) of the element instead of the element itself

Similar to find/3, but returns the value of the function invocation instead of the element itself

Returns a new enumerable appending the result of invoking fun on each corresponding item of enumerable

Maps and reduces an enumerable, flattening the given results

Splits the enumerable into groups based on fun

Intersperses element between each element of the enumeration

Inserts the given enumerable into a collectable

Inserts the given enumerable into a collectable according to the transformation function

Joins the given enumerable into a binary using joiner as a separator

Returns a list where each item is the result of invoking fun on each corresponding item of enumerable

Maps and joins the given enumerable in one pass

Invokes the given function to each item in the enumerable to reduce it to a single element, while keeping an accumulator

Returns the biggest of the elements in the enumerable according to Erlang’s term ordering

Returns the biggest of the elements in the enumerable as calculated by the given function

Checks if element exists within the enumerable

Returns the smallest of the elements in the enumerable according to Erlang’s term ordering

Returns the smallest of the elements in the enumerable as calculated by the given function

Returns a tuple with the smallest and the biggest elements in the enumerable according to Erlang’s term ordering

Returns a tuple with the smallest and the biggest elements in the enumerable as calculated by the given function

Partitions enumerable into two enumerables, where the first one contains elements for which fun returns a truthy value, and the second one – for which fun returns false or nil

Returns a random element of an enumerable

Invokes fun for each element in the enumerable, passing that element and the accumulator as arguments. fun’s return value is stored in the accumulator

Invokes fun for each element in the enumerable, passing that element and the accumulator acc as arguments. fun’s return value is stored in acc

Reduces the enumerable until halt is emitted

Returns elements of enumerable for which the function fun returns false or nil

Returns a list of elements in enumerable in reverse order

Reverses the elements in enumerable, appends the tail, and returns it as a list

Reverses the enumerable in the range from initial position start through count elements

Applies the given function to each element in the enumerable, storing the result in a list and passing it as the accumulator for the next computation

Applies the given function to each element in the enumerable, storing the result in a list and passing it as the accumulator for the next computation. Uses the given acc as the starting value

Returns a list with the elements of enumerable shuffled

Returns a subset list of the given enumerable. Drops elements until element position range.first, then takes elements until element position range.last (inclusive)

Returns a subset list of the given enumerable. Drops elements until element position start, then takes count elements

Sorts the enumerable according to Erlang’s term ordering

Sorts the enumerable by the given function

Sorts the mapped results of the enumerable according to the sorter function

Splits the enumerable into two enumerables, leaving count elements in the first one. If count is a negative number, it starts counting from the back to the beginning of the enumerable

Splits enumerable in two at the position of the element for which fun returns false for the first time

Returns the sum of all elements

Takes the first count items from the enumerable

Returns a list of every nth item in the enumerable, starting with the first element

Takes random items from the enumerable

Takes the items from the beginning of the enumerable while fun returns a truthy value

Converts enumerable to a list

Enumerates the enumerable, removing all duplicated elements

Enumerates the enumerable, by removing the elements for which function fun returned duplicate items

Opposite of Enum.zip/2; extracts a two-element tuples from the enumerable and groups them together

Returns the enumerable with each element wrapped in a tuple alongside its index

Zips corresponding elements from two enumerables into one list of tuples

Types

default()
default() :: any
element()
element() :: any
index()
index() :: non_neg_integer
t()
t() :: Enumerable.t

Functions

all?(enumerable, fun \\ fn x -> x end)
all?(t, (element -> as_boolean(term))) :: boolean

Invokes the given fun for each item in the enumerable. It stops the iteration at the first invocation that returns false or nil. It returns false if at least one invocation returns false or nil. 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 enumerable are truthy values.

iex> Enum.all?([1, 2, 3])
true

iex> Enum.all?([1, nil, 3])
false
any?(enumerable, fun \\ fn x -> x end)
any?(t, (element -> as_boolean(term))) :: boolean

Invokes the given fun for each item in the enumerable. It stops the iteration at the first invocation that returns a truthy value. Returns true if at least one invocation returns a truthy value. Otherwise returns false.

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 enumerable is a truthy value.

iex> Enum.any?([false, false, false])
false

iex> Enum.any?([false, true, false])
true
at(enumerable, index, default \\ nil)
at(t, integer, default) :: element | default

Finds the element at the given index (zero-based).

Returns default if index is out of bounds.

Note this operation takes linear time. In order to access the element at index index, it will need to traverse index previous elements.

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
chunk(enumerable, count)
chunk(t, pos_integer) :: [list]

Shortcut to chunk(enumerable, count, count).

chunk(enumerable, count, step, pad \\ nil)
chunk(t, pos_integer, pos_integer, t | nil) :: [list]

Returns list of lists containing count items each, where each new chunk starts step elements into the enumerable.

step is optional and, if not passed, defaults to count, i.e. chunks do not overlap.

If the final chunk does not have count 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 count 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]]
chunk_by(enumerable, fun)
chunk_by(t, (element -> any)) :: [list]

Splits enumerable on every element for which fun returns a new value.

Returns a list of lists.

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]]
concat(enumerables)
concat(t) :: t

Given an enumerable of enumerables, concatenates 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]
concat(left, right)
concat(t, t) :: t

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]
count(enumerable)
count(t) :: non_neg_integer

Returns the size of the enumerable.

Examples

iex> Enum.count([1, 2, 3])
3
count(enumerable, fun)
count(t, (element -> as_boolean(term))) :: non_neg_integer

Returns the count of items in the enumerable for which fun returns a truthy value.

Examples

iex> Enum.count([1, 2, 3, 4, 5], fn(x) -> rem(x, 2) == 0 end)
2
dedup(enumerable)
dedup(t) :: list

Enumerates the enumerable, returning a list where all consecutive duplicated elements are collapsed to a single element.

Elements are compared using ===.

Examples

iex> Enum.dedup([1, 2, 3, 3, 2, 1])
[1, 2, 3, 2, 1]

iex> Enum.dedup([1, 1, 2, 2.0, :three, :"three"])
[1, 2, 2.0, :three]
dedup_by(enumerable, fun)
dedup_by(t, (element -> term)) :: list

Enumerates the enumerable, returning a list where all consecutive duplicated elements are collapsed to a single element.

The function fun maps every element to a term which is used to determine if two elements are duplicates.

Examples

iex> Enum.dedup_by([{1, :a}, {2, :b}, {2, :c}, {1, :a}], fn {x, _} -> x end)
[{1, :a}, {2, :b}, {1, :a}]

iex> Enum.dedup_by([5, 1, 2, 3, 2, 1], fn x -> x > 2 end)
[5, 1, 3, 2]
drop(enumerable, n)
drop(t, integer) :: list

Drops the first n items from then enumerable.

If a negative value n is given, the last n values will be dropped.

The enumerable 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]
drop_while(enumerable, fun)
drop_while(t, (element -> as_boolean(term))) :: list

Drops items at the beginning of the enumerable while fun returns a truthy value.

Examples

iex> Enum.drop_while([1, 2, 3, 4, 5], fn(x) -> x < 3 end)
[3, 4, 5]
each(enumerable, fun)
each(t, (element -> any)) :: :ok

Invokes the given fun for each item in the enumerable.

Returns :ok.

Examples

Enum.each(["some", "example"], fn(x) -> IO.puts x end)
"some"
"example"
#=> :ok
empty?(enumerable)
empty?(t) :: boolean

Determines if the enumerable is empty.

Returns true if enumerable is empty, otherwise false.

Examples

iex> Enum.empty?([])
true

iex> Enum.empty?([1, 2, 3])
false
fetch(enumerable, index)
fetch(t, integer) :: {:ok, element} | :error

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 enumerable is enumerated once and the index is counted from the end (e.g. -1 fetches the last element).

Note this operation takes linear time. In order to access the element at index index, it will need to traverse index previous elements.

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
fetch!(enumerable, index)
fetch!(t, integer) :: element | no_return

Finds the element at the given index (zero-based).

Raises OutOfBoundsError if the given index is outside the range of the enumerable.

Note this operation takes linear time. In order to access the element at index index, it will need to traverse index previous elements.

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
filter(enumerable, fun)
filter(t, (element -> as_boolean(term))) :: list

Filters the enumerable, i.e. returns only those elements for which fun returns a truthy value.

Examples

iex> Enum.filter([1, 2, 3], fn(x) -> rem(x, 2) == 0 end)
[2]
filter_map(enumerable, filter, mapper)
filter_map(t, (element -> as_boolean(term)), (element -> element)) :: list

Filters the enumerable and maps its elements in one pass.

Examples

iex> Enum.filter_map([1, 2, 3], fn(x) -> rem(x, 2) == 0 end, &(&1 * 2))
[4]
find(enumerable, default \\ nil, fun)
find(t, default, (element -> any)) :: element | default

Returns the first item for which fun returns a truthy value. If no such item is found, returns default.

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
find_index(enumerable, fun)
find_index(t, (element -> any)) :: index | nil

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
find_value(enumerable, default \\ nil, fun)
find_value(t, any, (element -> any)) :: any | nil

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

iex> Enum.find_value([1, 2, 3], "no bools!", &is_boolean/1)
"no bools!"
flat_map(enumerable, fun)
flat_map(t, (element -> t)) :: list

Returns a new enumerable appending the result of invoking fun on each corresponding item of enumerable.

The given function must 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]
flat_map_reduce(enumerable, acc, fun)
flat_map_reduce(t, acc, fun) :: {[any], any} when fun: (element, acc -> {t, acc} | {:halt, acc}), acc: any

Maps and reduces an enumerable, flattening the given results.

It expects an accumulator and a function that receives each stream item, 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}
group_by(enumerable, dict \\ %{}, fun)
group_by(t, dict, (element -> any)) :: dict when dict: Dict.t

Splits the enumerable into groups based on fun.

The result is a dict (by default a map) where each key is a group and each value is a list of elements from enumerable for which fun returned that group. Ordering is not necessarily preserved.

Examples

iex> Enum.group_by(~w{ant buffalo cat dingo}, &String.length/1)
%{3 => ["cat", "ant"], 7 => ["buffalo"], 5 => ["dingo"]}
intersperse(enumerable, element)
intersperse(t, element) :: list

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)
[]
into(enumerable, collectable)

Inserts the given enumerable into a collectable.

Examples

iex> Enum.into([1, 2], [0])
[0, 1, 2]

iex> Enum.into([a: 1, b: 2], %{})
%{a: 1, b: 2}
into(enumerable, collectable, transform)
into(Enumerable.t, Collectable.t, (term -> term)) :: Collectable.t

Inserts the given enumerable into a collectable according to the transformation function.

Examples

iex> Enum.into([2, 3], [3], fn x -> x * 3 end)
[3, 6, 9]
join(enumerable, joiner \\ "")
join(t, String.t) :: String.t

Joins the given enumerable into a binary using joiner as a separator.

If joiner is not passed at all, it defaults to the empty binary.

All items in the enumerable 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"
map(enumerable, fun)
map(t, (element -> any)) :: list

Returns a list where each item is the result of invoking fun on each corresponding item of enumerable.

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]
map_join(enumerable, joiner \\ "", mapper)
map_join(t, String.t, (element -> any)) :: String.t

Maps and joins the given enumerable 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 enumerable 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"
map_reduce(enumerable, acc, fun)
map_reduce(t, any, (element, any -> {any, any})) :: {any, any}

Invokes the given function to each item in the enumerable to reduce it to a single element, while keeping an accumulator.

Returns a tuple where the first element is the mapped enumerable and the second one is the final accumulator.

The function, fun, receives two arguments: the first one is the element, and the second one is the accumulator. fun must return a a tuple with two elements in the form of {result, 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}
max(enumerable)
max(t) :: element | no_return

Returns the biggest of the elements in the enumerable according to Erlang’s term ordering.

If more than one elements compare equal, the first one that was found is returned.

Raises Enum.EmptyError if enumerable is empty.

Examples

iex> Enum.max([1, 2, 3])
3
max_by(enumerable, fun)
max_by(t, (element -> any)) :: element | no_return

Returns the biggest of the elements in the enumerable as calculated by the given function.

If more than one elements compare equal, the first one that was found is returned.

Raises Enum.EmptyError if enumerable is empty.

Examples

iex> Enum.max_by(["a", "aa", "aaa"], fn(x) -> String.length(x) end)
"aaa"
member?(enumerable, element)
member?(t, element) :: boolean

Checks if element exists within the enumerable.

Membership is tested with the match (===) operator.

Examples

iex> Enum.member?(1..10, 5)
true
iex> Enum.member?(1..10, 5.0)
false

iex> Enum.member?([1.0, 2.0, 3.0], 2)
false
iex> Enum.member?([1.0, 2.0, 3.0], 2.000)
true

iex> Enum.member?([:a, :b, :c], :d)
false
min(enumerable)
min(t) :: element | no_return

Returns the smallest of the elements in the enumerable according to Erlang’s term ordering.

If more than one elements compare equal, the first one that was found is returned.

Raises Enum.EmptyError if enumerable is empty.

Examples

iex> Enum.min([1, 2, 3])
1
min_by(enumerable, fun)
min_by(t, (element -> any)) :: element | no_return

Returns the smallest of the elements in the enumerable as calculated by the given function.

If more than one elements compare equal, the first one that was found is returned.

Raises Enum.EmptyError if enumerable is empty.

Examples

iex> Enum.min_by(["a", "aa", "aaa"], fn(x) -> String.length(x) end)
"a"
min_max(enumerable)
min_max(t) :: {element, element} | no_return

Returns a tuple with the smallest and the biggest elements in the enumerable according to Erlang’s term ordering.

If more than one elements compare equal, the first one that was found is picked.

Raises Enum.EmptyError if enumerable is empty.

Examples

iex> Enum.min_max([2, 3, 1])
{1, 3}
min_max_by(enumerable, fun)
min_max_by(t, (element -> any)) ::
  {element, element} |
  no_return

Returns a tuple with the smallest and the biggest elements in the enumerable as calculated by the given function.

If more than one elements compare equal, the first one that was found is picked.

Raises Enum.EmptyError if enumerable is empty.

Examples

iex> Enum.min_max_by(["aaa", "bb", "c"], fn(x) -> String.length(x) end)
{"c", "aaa"}
partition(enumerable, fun)
partition(t, (element -> any)) :: {list, list}

Partitions enumerable into two enumerables, 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]}
random(enumerable)
random(t) :: element | no_return

Returns a random element of an enumerable.

Raises Enum.EmptyError if enumerable is empty.

This function uses Erlang’s :rand module to calculate the random value. Check its documentation for setting a different random algorithm or a different seed.

The implementation is based on the reservoir sampling algorithm. It assumes that the sample being returned can fit into memory; the input enumerable doesn’t have to, as it is traversed just once.

Examples

# Although not necessary, let's seed the random algorithm
iex> :rand.seed(:exsplus, {1, 2, 3})
iex> Enum.random([1, 2, 3])
2
iex> Enum.random([1, 2, 3])
1
reduce(enumerable, fun)
reduce(t, (element, any -> any)) :: any

Invokes fun for each element in the enumerable, passing that element and the accumulator as arguments. fun’s return value is stored in the accumulator.

The first element of the enumerable is used as the initial value of the accumulator. If you wish to use another value for the accumulator, use Enumerable.reduce/3. This function won’t call the specified function for enumerables that are 1-element long.

Returns the accumulator.

Note that since the first element of the enumerable is used as the initial value of the accumulator, fun will only be executed n - 1 times where n is the length of the enumerable.

Examples

iex> Enum.reduce([1, 2, 3, 4], fn(x, acc) -> x * acc end)
24
reduce(enumerable, acc, fun)
reduce(t, any, (element, any -> any)) :: any

Invokes fun for each element in the enumerable, 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
reduce_while(enumerable, acc, fun)

Reduces the enumerable until halt is emitted.

The return value for fun is expected to be {:cont, acc}, return {:halt, acc} to end the reduction early.

Returns the accumulator.

Examples

iex> Enum.reduce_while(1..100, 0, fn i, acc ->
...>   if i < 3, do: {:cont, acc + i}, else: {:halt, acc}
...> end)
3
reject(enumerable, fun)
reject(t, (element -> as_boolean(term))) :: list

Returns elements of enumerable for which the function fun returns false or nil.

Examples

iex> Enum.reject([1, 2, 3], fn(x) -> rem(x, 2) == 0 end)
[1, 3]
reverse(enumerable)
reverse(t) :: list

Returns a list of elements in enumerable in reverse order.

Examples

iex> Enum.reverse([1, 2, 3])
[3, 2, 1]
reverse(enumerable, tail)
reverse(t, t) :: list

Reverses the elements in enumerable, appends the tail, and returns it as a list.

This is an optimization for Enum.concat(Enum.reverse(enumerable), tail).

Examples

iex> Enum.reverse([1, 2, 3], [4, 5, 6])
[3, 2, 1, 4, 5, 6]
reverse_slice(enumerable, start, count)
reverse_slice(t, non_neg_integer, non_neg_integer) :: list

Reverses the enumerable in the range from initial position start through count elements.

If count is greater than the size of the rest of the enumerable, then this function will reverse the rest of the enumerable.

Examples

iex> Enum.reverse_slice([1, 2, 3, 4, 5, 6], 2, 4)
[1, 2, 6, 5, 4, 3]
scan(enumerable, fun)
scan(t, (element, any -> any)) :: list

Applies the given function to each element in the enumerable, 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]
scan(enumerable, acc, fun)
scan(t, any, (element, any -> any)) :: list

Applies the given function to each element in the enumerable, 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]
shuffle(enumerable)
shuffle(t) :: list

Returns a list with the elements of enumerable shuffled.

This function uses Erlang’s :rand module to calculate the random value. Check its documentation for setting a different random algorithm or a different seed.

Examples

# Although not necessary, let's seed the random algorithm
iex> :rand.seed(:exsplus, {1, 2, 3})
iex> Enum.shuffle([1, 2, 3])
[2, 1, 3]
iex> Enum.shuffle([1, 2, 3])
[2, 3, 1]
slice(enumerable, range)
slice(t, Range.t) :: list

Returns a subset list of the given enumerable. 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 enumerable to negative positions (e.g. position -3 in an enumerable with count 5 becomes position 2).

The first position (after adding count to negative positions) must be smaller or equal to the last position.

If the start of the range is not a valid offset for the given enumerable or if the range is in reverse order, returns [].

Examples

iex> Enum.slice(1..100, 5..10)
[6, 7, 8, 9, 10, 11]

iex> Enum.slice(1..10, 5..20)
[6, 7, 8, 9, 10]

iex> Enum.slice(1..10, 11..20)
[]

iex> Enum.slice(1..10, 6..5)
[]
slice(enumerable, start, count)
slice(t, integer, non_neg_integer) :: list

Returns a subset list of the given enumerable. Drops elements until element position start, then takes count elements.

If the count is greater than enumerable length, it returns as many as possible. If zero, then it returns [].

Examples

iex> Enum.slice(1..100, 5, 10)
[6, 7, 8, 9, 10, 11, 12, 13, 14, 15]

iex> Enum.slice(1..10, 5, 100)
[6, 7, 8, 9, 10]

iex> Enum.slice(1..10, 5, 0)
[]
sort(enumerable)
sort(t) :: list

Sorts the enumerable according to Erlang’s term ordering.

Uses the merge sort algorithm.

Examples

iex> Enum.sort([3, 2, 1])
[1, 2, 3]
sort(enumerable, fun)
sort(t, (element, element -> boolean)) :: list

Sorts the enumerable by the given function.

This function uses the merge sort algorithm. The given function must return false if the first argument is smaller than second one.

Examples

iex> Enum.sort([1, 2, 3], &(&1 > &2))
[3, 2, 1]

The sorting algorithm will be stable as long as the given function returns true for values considered equal:

iex> Enum.sort ["some", "kind", "of", "monster"], &(byte_size(&1) <= byte_size(&2))
["of", "some", "kind", "monster"]

If the function does not return true for equal values, the sorting is not stable and the order of equal terms may be shuffled. For example:

iex> Enum.sort ["some", "kind", "of", "monster"], &(byte_size(&1) < byte_size(&2))
["of", "kind", "some", "monster"]
sort_by(enumerable, mapper, sorter \\ &<=/2)
sort_by(t, (element -> mapped_element), (mapped_element, mapped_element -> boolean)) :: list when mapped_element: element

Sorts the mapped results of the enumerable according to the sorter function.

This function maps each element of the enumerable using the mapper function. The enumerable is then sorted by the mapped elements using the sorter function, which defaults to Kernel.<=/2

sort_by/3 differs from sort/2 in that it only calculates the comparison value for each element in the enumerable once instead of once for each element in each comparison. If the same function is being called on both element, it’s also more compact to use sort_by/3.

This technique is also known as a Schwartzian Transform, or the Lisp decorate-sort-undecorate idiom as the mapper is decorating the original enumerable; then sorter is sorting the decorations; and finally the enumerable is being undecorated so only the original elements remain, but now in sorted order.

Examples

Using the default sorter of <=/2:

iex> Enum.sort_by ["some", "kind", "of", "monster"], &byte_size/1
["of", "some", "kind", "monster"]

Using a custom sorter to override the order:

iex> Enum.sort_by ["some", "kind", "of", "monster"], &byte_size/1, &>=/2
["monster", "some", "kind", "of"]
split(enumerable, count)
split(t, integer) :: {list, list}

Splits the enumerable into two enumerables, leaving count elements in the first one. If count is a negative number, it starts counting from the back to the beginning of the enumerable.

Be aware that a negative count implies the enumerable 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]}
split_while(enumerable, fun)
split_while(t, (element -> as_boolean(term))) :: {list, list}

Splits enumerable in two at the position of the element for which fun returns false for the first time.

Examples

iex> Enum.split_while([1, 2, 3, 4], fn(x) -> x < 3 end)
{[1, 2], [3, 4]}
sum(enumerable)
sum(t) :: number

Returns the sum of all elements.

Raises ArithmeticError if enumerable contains a non-numeric value.

Examples

iex> Enum.sum([1, 2, 3])
6
take(enumerable, count)
take(t, integer) :: list

Takes the first count items from the enumerable.

count must be an integer. If a negative count is given, the last count values will be taken. For such, the enumerable is fully enumerated keeping up to 2 * count elements in memory. Once the end of the enumerable 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]
take_every(enumerable, nth)
take_every(t, non_neg_integer) :: list | no_return

Returns a list of every nth item in the enumerable, starting with the first element.

The first item is always included, unless nth is 0.

The second argument specifying every nth item must be a non-negative integer, otherwise FunctionClauseError will be raised.

Examples

iex> Enum.take_every(1..10, 2)
[1, 3, 5, 7, 9]

iex> Enum.take_every(1..10, 0)
[]

iex> Enum.take_every([1, 2, 3], 1)
[1, 2, 3]
take_random(enumerable, count)
take_random(t, integer) :: list

Takes random items from the enumerable.

Notice this function will traverse the whole enumerable to get the random sublist of enumerable. If you want the random number between two integers, the best option is to use the :random module.

See random/1 for notes on implementation and random seed.

Examples

# Although not necessary, let's seed the random algorithm
iex> :rand.seed(:exsplus, {1, 2, 3})
iex> Enum.take_random(1..10, 2)
[5, 8]
iex> Enum.take_random(?a..?z, 5)
'fhjni'
take_while(enumerable, fun)
take_while(t, (element -> as_boolean(term))) :: list

Takes the items from the beginning of the enumerable while fun returns a truthy value.

Examples

iex> Enum.take_while([1, 2, 3], fn(x) -> x < 3 end)
[1, 2]
to_list(enumerable)
to_list(t) :: [element]

Converts enumerable to a list.

Examples

iex> Enum.to_list(1..3)
[1, 2, 3]
uniq(enumerable)
uniq(t) :: list

Enumerates the enumerable, removing all duplicated elements.

Examples

iex> Enum.uniq([1, 2, 3, 3, 2, 1])
[1, 2, 3]
uniq_by(enumerable, fun)
uniq_by(t, (element -> term)) :: list

Enumerates the enumerable, by removing the elements for which function fun returned duplicate items.

The function fun maps every element to a term which is used to determine if two elements are duplicates.

Example

iex> Enum.uniq_by([{1, :x}, {2, :y}, {1, :z}], fn {x, _} -> x end)
[{1, :x}, {2, :y}]

Enum.uniq_by([{a: {tea: 2}}, {b: {tea: 2}}, {c, {coffe: 1}}], fn {x, _} -> x end)
[a: [tea: 2], b: [tea: 2]]
unzip(enumerable)
unzip(t) :: {[element], [element]}

Opposite of Enum.zip/2; extracts a two-element tuples from the enumerable and groups them together.

It takes an enumerable with items being two-element tuples and returns a tuple with two lists, each of which is formed by the first and second element of each tuple, respectively.

This function fails unless enumerable is or can be converted into a list of tuples with exactly two elements in each tuple.

Examples

iex> Enum.unzip([{:a, 1}, {:b, 2}, {:c, 3}])
{[:a, :b, :c], [1, 2, 3]}

iex> Enum.unzip(%{a: 1, b: 2})
{[:a, :b], [1, 2]}
with_index(enumerable, offset \\ 0)
with_index(t, integer) :: [{element, integer}]

Returns the enumerable with each element wrapped in a tuple alongside its index.

Examples

iex> Enum.with_index([:a, :b, :c])
[a: 0, b: 1, c: 2]

iex> Enum.with_index([:a, :b, :c], 3)
[a: 3, b: 4, c: 5]
zip(enumerable1, enumerable2)
zip(t, t) :: [{any, any}]

Zips corresponding elements from two enumerables 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}]