View Source Aja.Enum (Aja v0.6.5)
Drop-in replacement for the Enum
module, optimized to work with Aja's data structures such as Aja.Vector
.
It currently only covers a subset of Enum
, but Aja.Enum
aims to completely mirror the API of Enum
,
and should behave exactly the same for any type of Enumerable
.
The only expected difference should be a significant increase in performance for Aja structures.
Rationale
Structures such as Aja.Vector
or Aja.OrdMap
are implementing the Enumerable
protocol, which means they can be
used directly with the Enum
module. The Enumerable
protocol however comes with its overhead and is strongly
limited in terms of performance.
On the other hand, Aja.Enum
provides hand-crafted highly-optimized functions that fully take advantage of
immutable vectors. The speedup can easily reach more than a factor 10 compared to Enum
used on non-list
structures, and sometimes even be noticeably faster than Enum
used over lists.
One of the main reasons to adopt a specific data structure is the performance.
Using vectors with Enum
would defeat the purpose, hence the introduction of Aja.Enum
.
iex> vector = Aja.Vector.new(1..10000)
iex> Enum.sum(vector) # slow
50005000
iex> Aja.Enum.sum(vector) # same result, much faster
50005000
Summary
Functions
Returns true
if all elements in enumerable
are truthy.
Returns true
if fun.(element)
is truthy for all elements in enumerable
.
Returns true
if at least one element in enumerable
is truthy.
Returns true
if fun.(element)
is truthy for at least one element in enumerable
.
Finds the element at the given index
(zero-based).
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 elements 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 amount
of elements from the enumerable
.
Drops elements at the beginning of the enumerable
while fun
returns a truthy value.
Invokes the given fun
for each element in the enumerable
.
Returns true
if enumerable
is empty, otherwise false
.
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.
Returns the first element for which fun
returns a truthy value.
If no such element 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.
Maps the given fun
over enumerable
and flattens the result.
Returns a map with keys as unique elements of enumerable
and values
as the count of every element.
Returns a map with keys as unique elements given by key_fun
and values
as the count of every element.
Splits the enumerable
into groups based on key_fun
.
Intersperses separator
between each element of the given enumerable
.
Inserts the given enumerable
into a collectable
.
Inserts the given enumerable
into a collectable
according to the transform
function.
Joins the given enumerable
into a string using joiner
as a
separator.
Returns a list where each element is the result of invoking
fun
on each corresponding element of enumerable
.
Maps and intersperses the given enumerable
in one pass.
Maps and joins the given enumerable
in one pass.
Invokes the given function to each element in the enumerable
to reduce
it to a single element, while keeping an accumulator.
Returns the maximal element in the enumerable
according
to Erlang's term ordering.
Returns the maximal element in the enumerable
as calculated
by the given fun
.
Checks if element
exists within the enumerable
.
Returns the minimal element in the enumerable
according
to Erlang's term ordering.
Returns the minimal element in the enumerable
as calculated
by the given fun
.
Returns the product of all elements in the enumerable
.
Returns a random element of an enumerable
.
Invokes fun
for each element in the enumerable
with the
accumulator.
Invokes fun
for each element in the enumerable
with the accumulator.
Returns a list of elements in enumerable
excluding those for which the function fun
returns
a truthy value.
Returns a list of elements in enumerable
in reverse order.
Reverses the elements in enumerable
, concatenates the tail
,
and returns it as a 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 first element in the enumerable
as the starting value.
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
by index_range
.
Returns a subset list of the given enumerable
, from start_index
(zero-based)
with amount
number of elements if available.
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 provided sorter
function.
Splits the enumerable
into two enumerables, leaving count
elements in the first one.
Splits enumerable
in two at the position of the element for which fun
returns a falsy value
(false
or nil
) for the first time.
Splits the enumerable
in two lists according to the given function fun
.
Returns the sum of all elements.
Takes an amount
of elements from the beginning or the end of the enumerable
.
Takes count
random elements from enumerable
.
Takes the elements 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 elements.
Opposite of zip/2
. Extracts two-element tuples from the given enumerable
and groups them together.
Returns a list with with each element of enumerable
wrapped in a tuple alongside its index.
Zips corresponding elements from two enumerables into one list of tuples.
Types
@type index() :: integer()
@type t(value) :: Aja.Vector.t(value) | [value] | Enumerable.t()
@type value() :: any()
Functions
@spec all?(t(as_boolean(val))) :: boolean() when val: value()
Returns true
if all elements in enumerable
are truthy.
When an element has a falsy value (false
or nil
) iteration stops immediately
and false
is returned. In all other cases true
is returned.
Examples
iex> Aja.Enum.all?([1, 2, 3])
true
iex> Aja.Enum.all?([1, nil, 3])
false
iex> Aja.Enum.all?([])
true
@spec all?(t(val), (val -> as_boolean(term()))) :: boolean() when val: value()
Returns true
if fun.(element)
is truthy for all elements in enumerable
.
Iterates over enumerable
and invokes fun
on each element. If fun
ever
returns a falsy value (false
or nil
), iteration stops immediately and
false
is returned. Otherwise, true
is returned.
Examples
iex> Aja.Enum.all?([2, 4, 6], fn x -> rem(x, 2) == 0 end)
true
iex> Aja.Enum.all?([2, 3, 4], fn x -> rem(x, 2) == 0 end)
false
iex> Aja.Enum.all?([], fn _ -> nil end)
true
@spec any?(t(as_boolean(val))) :: boolean() when val: value()
Returns true
if at least one element in enumerable
is truthy.
When an element has a truthy value (neither false
nor nil
) iteration stops
immediately and true
is returned. In all other cases false
is returned.
Examples
iex> Aja.Enum.any?([false, false, false])
false
iex> Aja.Enum.any?([false, true, false])
true
iex> Aja.Enum.any?([])
false
@spec any?(t(val), (val -> as_boolean(term()))) :: boolean() when val: value()
Returns true
if fun.(element)
is truthy for at least one element in enumerable
.
Iterates over the enumerable
and invokes fun
on each element. When an invocation
of fun
returns a truthy value (neither false
nor nil
) iteration stops
immediately and true
is returned. In all other cases false
is returned.
Examples
iex> Aja.Enum.any?([2, 4, 6], fn x -> rem(x, 2) == 1 end)
false
iex> Aja.Enum.any?([2, 3, 4], fn x -> rem(x, 2) == 1 end)
true
iex> Aja.Enum.any?([], fn x -> x > 0 end)
false
Finds the element at the given index
(zero-based).
Mirrors Enum.at/3
with higher performance for Aja structures.
Given an enumerable of enumerables, concatenates the enumerables
into
a single list.
Mirrors Enum.concat/1
with higher performance for Aja structures.
Concatenates the enumerable on the right
with the enumerable on the left
.
Mirrors Enum.concat/2
with higher performance for Aja structures.
@spec count(t(any())) :: non_neg_integer()
Returns the size of the enumerable
.
Mirrors Enum.count/1
with higher performance for Aja structures.
@spec count(t(val), (val -> as_boolean(term()))) :: non_neg_integer() when val: value()
Returns the count of elements in the enumerable
for which fun
returns
a truthy value.
Mirrors Enum.count/2
with higher performance for Aja structures.
Enumerates the enumerable
, returning a list where all consecutive
duplicated elements are collapsed to a single element.
Mirrors Enum.dedup/1
with higher performance for Aja structures.
Enumerates the enumerable
, returning a list where all consecutive
duplicated elements are collapsed to a single element.
Mirrors Enum.dedup_by/2
with higher performance for Aja structures.
Drops the amount
of elements from the enumerable
.
Mirrors Enum.drop/2
with higher performance for Aja structures.
@spec drop_while(t(val), (val -> as_boolean(term()))) :: [val] when val: value()
Drops elements at the beginning of the enumerable
while fun
returns a truthy value.
Mirrors Enum.drop_while/2
with higher performance for Aja structures.
Invokes the given fun
for each element in the enumerable
.
Mirrors Enum.each/2
with higher performance for Aja structures.
Returns true
if enumerable
is empty, otherwise false
.
Mirrors Enum.empty?/1
with higher performance for Aja structures.
Finds the element at the given index
(zero-based).
Mirrors Enum.fetch/2
with higher performance for Aja structures.
Finds the element at the given index
(zero-based).
Mirrors Enum.fetch!/2
with higher performance for Aja structures.
@spec filter(t(val), (val -> as_boolean(term()))) :: [val] when val: value()
Filters the enumerable
, i.e. returns only those elements
for which fun
returns a truthy value.
Mirrors Enum.filter/2
with higher performance for Aja structures.
@spec find(t(val), default, (val -> as_boolean(term()))) :: val | default when val: value(), default: value()
Returns the first element for which fun
returns a truthy value.
If no such element is found, returns default
.
Mirrors Enum.find/3
with higher performance for Aja structures.
@spec find_index(t(val), (val -> as_boolean(term()))) :: non_neg_integer() | nil when val: value()
Similar to find/3
, but returns the index (zero-based)
of the element instead of the element itself.
Mirrors Enum.find_index/2
with higher performance for Aja structures.
@spec find_value(t(val), default, (val -> new_val)) :: new_val | default when val: value(), new_val: value(), default: value()
Similar to find/3
, but returns the value of the function
invocation instead of the element itself.
Mirrors Enum.find_value/3
with higher performance for Aja structures.
@spec flat_map(t(val), (val -> t(mapped_val))) :: [mapped_val] when val: value(), mapped_val: value()
Maps the given fun
over enumerable
and flattens the result.
Mirrors Enum.flat_map/2
with higher performance for Aja structures.
@spec frequencies(t(val)) :: %{optional(val) => non_neg_integer()} when val: value()
Returns a map with keys as unique elements of enumerable
and values
as the count of every element.
Mirrors Enum.frequencies/1
with higher performance for Aja structures.
@spec frequencies_by(t(val), (val -> key)) :: %{optional(key) => non_neg_integer()} when val: value(), key: any()
Returns a map with keys as unique elements given by key_fun
and values
as the count of every element.
Mirrors Enum.frequencies_by/2
with higher performance for Aja structures.
@spec group_by(t(val), (val -> key), (val -> mapped_val)) :: %{ optional(key) => [mapped_val] } when val: value(), key: any(), mapped_val: any()
Splits the enumerable
into groups based on key_fun
.
Mirrors Enum.group_by/3
with higher performance for Aja structures.
Intersperses separator
between each element of the given enumerable
.
Mirrors Enum.intersperse/2
with higher performance for Aja structures.
@spec into(t(val), Collectable.t()) :: Collectable.t() when val: value()
Inserts the given enumerable
into a collectable
.
Mirrors Enum.into/2
with higher performance for Aja structures.
Inserts the given enumerable
into a collectable
according to the transform
function.
Mirrors Enum.into/3
with higher performance for Aja structures.
@spec join(t(val), String.t()) :: String.t() when val: String.Chars.t()
Joins the given enumerable
into a string using joiner
as a
separator.
Mirrors Enum.join/2
with higher performance for Aja structures.
Returns a list where each element is the result of invoking
fun
on each corresponding element of enumerable
.
Mirrors Enum.map/2
with higher performance for Aja structures.
@spec map_intersperse(t(val), separator, (val -> mapped_val)) :: [ mapped_val | separator ] when val: value(), separator: value(), mapped_val: value()
Maps and intersperses the given enumerable
in one pass.
Mirrors Enum.map_intersperse/3
with higher performance for Aja structures.
@spec map_join(t(val), String.t(), (val -> String.Chars.t())) :: String.t() when val: value()
Maps and joins the given enumerable
in one pass.
Mirrors Enum.map_join/3
with higher performance for Aja structures.
@spec map_reduce(t(val), acc, (val, acc -> {mapped_val, acc})) :: {t(mapped_val), acc} when val: value(), mapped_val: value(), acc: any()
Invokes the given function to each element in the enumerable
to reduce
it to a single element, while keeping an accumulator.
Mirrors Enum.map_reduce/3
with higher performance for Aja structures.
max(enumerable, sorter \\ &>=/2, empty_fallback \\ fn -> raise Enum.EmptyError end)
View Source@spec max(t(val), (val, val -> boolean()) | module(), (-> empty_result)) :: val | empty_result when val: value(), empty_result: any()
Returns the maximal element in the enumerable
according
to Erlang's term ordering.
Mirrors Enum.max/3
with higher performance for Aja structures.
max_by(enumerable, fun, sorter \\ &>=/2, empty_fallback \\ fn -> raise Enum.EmptyError end)
View Source@spec max_by( t(val), (val -> key), (key, key -> boolean()) | module(), (-> empty_result) ) :: val | empty_result when val: value(), key: term(), empty_result: any()
Returns the maximal element in the enumerable
as calculated
by the given fun
.
Mirrors Enum.max_by/4
with higher performance for Aja structures.
Checks if element
exists within the enumerable
.
Just an alias for Enum.member?/2
, does not improve performance.
min(enumerable, sorter \\ &<=/2, empty_fallback \\ fn -> raise Enum.EmptyError end)
View Source@spec min(t(val), (val, val -> boolean()) | module(), (-> empty_result)) :: val | empty_result when val: value(), empty_result: any()
Returns the minimal element in the enumerable
according
to Erlang's term ordering.
Mirrors Enum.min/3
with higher performance for Aja structures.
min_by(enumerable, fun, sorter \\ &<=/2, empty_fallback \\ fn -> raise Enum.EmptyError end)
View Source@spec min_by( t(val), (val -> key), (key, key -> boolean()) | module(), (-> empty_result) ) :: val | empty_result when val: value(), key: term(), empty_result: any()
Returns the minimal element in the enumerable
as calculated
by the given fun
.
Mirrors Enum.min_by/4
with higher performance for Aja structures.
Returns the product of all elements in the enumerable
.
Mirrors Enum.product/1
.
Raises ArithmeticError
if enumerable
contains a non-numeric value.
Examples
iex> 1..5 |> Aja.Enum.product()
120
iex> [] |> Aja.Enum.product()
1
Returns a random element of an enumerable
.
Mirrors Enum.random/1
with higher performance for Aja structures.
Invokes fun
for each element in the enumerable
with the
accumulator.
Mirrors Enum.reduce/2
with higher performance for Aja structures.
Invokes fun
for each element in the enumerable
with the accumulator.
Mirrors Enum.reduce/3
with higher performance for Aja structures.
@spec reject(t(val), (val -> as_boolean(term()))) :: [val] when val: value()
Returns a list of elements in enumerable
excluding those for which the function fun
returns
a truthy value.
Mirrors Enum.reject/2
with higher performance for Aja structures.
Returns a list of elements in enumerable
in reverse order.
Mirrors Enum.reverse/1
with higher performance for Aja structures.
Reverses the elements in enumerable
, concatenates the tail
,
and returns it as a list.
Mirrors Enum.reverse/2
with higher performance for Aja structures.
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 first element in the enumerable
as the starting value.
Mirrors Enum.scan/2
with higher performance for Aja structures.
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.
Mirrors Enum.scan/3
with higher performance for Aja structures.
Returns a list with the elements of enumerable
shuffled.
Mirrors Enum.shuffle/1
with higher performance for Aja structures.
Returns a subset list of the given enumerable
by index_range
.
Mirrors Enum.slice/2
with higher performance for Aja structures.
@spec slice(t(val), index(), non_neg_integer()) :: [val] when val: value()
Returns a subset list of the given enumerable
, from start_index
(zero-based)
with amount
number of elements if available.
Mirrors Enum.slice/3
.
Sorts the enumerable
according to Erlang's term ordering.
Mirrors Enum.sort/1
with higher performance for Aja structures.
@spec sort( t(val), (val, val -> boolean()) | :asc | :desc | module() | {:asc | :desc, module()} ) :: [val] when val: value()
Sorts the enumerable
by the given function.
Mirrors Enum.sort/2
with higher performance for Aja structures.
@spec sort_by( t(val), (val -> mapped_val), (val, val -> boolean()) | :asc | :desc | module() | {:asc | :desc, module()} ) :: [val] when val: value(), mapped_val: value()
Sorts the mapped results of the enumerable
according to the provided sorter
function.
Mirrors Enum.sort_by/3
with higher performance for Aja structures.
Splits the enumerable
into two enumerables, leaving count
elements in the first one.
Mirrors Enum.split/2
with higher performance for Aja structures.
@spec split_while(t(val), (val -> as_boolean(term()))) :: {[val], [val]} when val: value()
Splits enumerable
in two at the position of the element for which fun
returns a falsy value
(false
or nil
) for the first time.
Mirrors Enum.split_while/2
with higher performance for Aja structures.
@spec split_with(t(val), (val -> as_boolean(term()))) :: {[val], [val]} when val: value()
Splits the enumerable
in two lists according to the given function fun
.
Mirrors Enum.split_with/2
with higher performance for Aja structures.
Returns the sum of all elements.
Mirrors Enum.sum/1
with higher performance for Aja structures.
Takes an amount
of elements from the beginning or the end of the enumerable
.
Mirrors Enum.take/2
with higher performance for Aja structures.
@spec take_random(t(val), non_neg_integer()) :: [val] when val: value()
Takes count
random elements from enumerable
.
Mirrors Enum.take_random/2
with higher performance for Aja structures.
@spec take_while(t(val), (val -> as_boolean(term()))) :: [val] when val: value()
Takes the elements from the beginning of the enumerable
while fun
returns a truthy value.
Mirrors Enum.take_while/2
with higher performance for Aja structures.
Converts enumerable
to a list.
Mirrors Enum.to_list/1
with higher performance for Aja structures.
Enumerates the enumerable
, removing all duplicated elements.
Mirrors Enum.uniq/1
with higher performance for Aja structures.
Enumerates the enumerable
, by removing the elements for which
function fun
returned duplicate elements.
Mirrors Enum.uniq_by/2
with higher performance for Aja structures.
Opposite of zip/2
. Extracts two-element tuples from the given enumerable
and groups them together.
Mirrors Enum.unzip/1
with higher performance for Aja structures.
@spec with_index(t(val), index()) :: [{val, index()}] when val: value()
@spec with_index(t(val), (val, index() -> mapped_val)) :: [mapped_val] when val: value(), mapped_val: value()
Returns a list with with each element of enumerable
wrapped in a tuple alongside its index.
Mirrors Enum.with_index/2
: may receive a function or an integer offset.
If an integer offset
is given, it will index from the given offset
instead of from zero.
If a function
is given, it will index by invoking the function for each
element and index (zero-based) of the enumerable
.
Examples
iex> Aja.Enum.with_index([:a, :b, :c])
[a: 0, b: 1, c: 2]
iex> Aja.Enum.with_index([:a, :b, :c], 3)
[a: 3, b: 4, c: 5]
iex> Aja.Enum.with_index([:a, :b, :c], fn element, index -> {index, element} end)
[{0, :a}, {1, :b}, {2, :c}]
Zips corresponding elements from two enumerables into one list of tuples.
Mirrors Enum.zip/2
with higher performance for Aja structures.