A.Enum (Aja v0.5.0) View Source
Drop-in replacement for the Enum
module, optimized to work with Aja's data structures such as A.Vector
.
It currently only covers a subset of Enum
, but A.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 A.Vector
or A.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, A.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 A.Enum
.
iex> vector = A.Vector.new(1..10000)
iex> Enum.sum(vector) # slow
50005000
iex> A.Enum.sum(vector) # same result, much faster
50005000
Link to this section 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).
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
.
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.
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.
Sorts the enumerable
and removes duplicates.
Sorts the enumerable
by the given function and removes duplicates.
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.
Returns a list with with each element of enumerable
wrapped in a tuple alongside its index.
Link to this section Types
Specs
index() :: integer()
Specs
t(value) :: A.Vector.t(value) | [value] | Enumerable.t()
Specs
value() :: any()
Link to this section Functions
Specs
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> A.Enum.all?([1, 2, 3])
true
iex> A.Enum.all?([1, nil, 3])
false
iex> A.Enum.all?([])
true
Specs
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> A.Enum.all?([2, 4, 6], fn x -> rem(x, 2) == 0 end)
true
iex> A.Enum.all?([2, 3, 4], fn x -> rem(x, 2) == 0 end)
false
iex> A.Enum.all?([], fn _ -> nil end)
true
Specs
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> A.Enum.any?([false, false, false])
false
iex> A.Enum.any?([false, true, false])
true
iex> A.Enum.any?([])
false
Specs
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> A.Enum.any?([2, 4, 6], fn x -> rem(x, 2) == 1 end)
false
iex> A.Enum.any?([2, 3, 4], fn x -> rem(x, 2) == 1 end)
true
iex> A.Enum.any?([], fn x -> x > 0 end)
false
Specs
Finds the element at the given index
(zero-based).
Mirrors Enum.at/3
with higher performance for Aja structures.
Specs
count(t(any())) :: non_neg_integer()
Returns the size of the enumerable
.
Mirrors Enum.count/1
with higher performance for Aja structures.
Specs
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.
Specs
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.
Specs
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.
Specs
Drops the amount
of elements from the enumerable
.
Mirrors Enum.drop/2
with higher performance for Aja structures.
Specs
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.
Specs
Invokes the given fun
for each element in the enumerable
.
Mirrors Enum.each/2
with higher performance for Aja structures.
Specs
Returns true
if enumerable
is empty, otherwise false
.
Mirrors Enum.empty?/1
with higher performance for Aja structures.
Specs
Finds the element at the given index
(zero-based).
Mirrors Enum.fetch/2
with higher performance for Aja structures.
Specs
Finds the element at the given index
(zero-based).
Mirrors Enum.fetch!/2
with higher performance for Aja structures.
Specs
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.
Specs
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.
Specs
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.
Specs
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.
Specs
Maps the given fun
over enumerable
and flattens the result.
Mirrors Enum.flat_map/2
with higher performance for Aja structures.
Specs
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.
Specs
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.
Specs
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.
Specs
Intersperses separator
between each element of the given enumerable
.
Mirrors Enum.intersperse/2
with higher performance for Aja structures.
Specs
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.
Specs
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.
Specs
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.
Specs
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.
Specs
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.
Specs
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 SourceSpecs
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 SourceSpecs
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.
Specs
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 SourceSpecs
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 SourceSpecs
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.
Specs
Returns the product of all elements in the enumerable
.
Mirrors Enum.product/1 from Elixir 1.12.
Raises ArithmeticError
if enumerable
contains a non-numeric value.
Examples
iex> 1..5 |> A.Enum.product()
120
iex> [] |> A.Enum.product()
1
Specs
Returns a random element of an enumerable
.
Mirrors Enum.random/1
with higher performance for Aja structures.
Specs
Invokes fun
for each element in the enumerable
with the
accumulator.
Mirrors Enum.reduce/2
with higher performance for Aja structures.
Specs
Invokes fun
for each element in the enumerable
with the accumulator.
Mirrors Enum.reduce/3
with higher performance for Aja structures.
Specs
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.
Specs
Returns a list of elements in enumerable
in reverse order.
Mirrors Enum.reverse/1
with higher performance for Aja structures.
Specs
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.
Specs
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.
Specs
Returns a list with the elements of enumerable
shuffled.
Mirrors Enum.shuffle/1
with higher performance for Aja structures.
Specs
Returns a subset list of the given enumerable
by index_range
.
Mirrors Enum.slice/2
with higher performance for Aja structures.
Specs
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
.
Specs
Sorts the enumerable
according to Erlang's term ordering.
Mirrors Enum.sort/1
with higher performance for Aja structures.
Specs
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.
Specs
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.
Sorts the enumerable
and removes duplicates.
It is more efficient than calling Enum.sort/1
followed by Enum.uniq/1
,
and slightly faster than Enum.sort/1
followed by Enum.dedup/1
.
Examples
iex> A.Enum.sort_uniq([1, 4, 2, 2, 3, 1, 4, 3])
[1, 2, 3, 4]
Sorts the enumerable
by the given function and removes duplicates.
See Enum.sort/2
for more details about how the second parameter works.
Examples
iex> A.Enum.sort_uniq([1, 4, 2, 2, 3, 1, 4, 3], &(&1 >= &2))
[4, 3, 2, 1]
iex> A.Enum.sort_uniq([1, 4, 2, 2, 3, 1, 4, 3], :asc)
[1, 2, 3, 4]
iex> A.Enum.sort_uniq([1, 4, 2, 2, 3, 1, 4, 3], :desc)
[4, 3, 2, 1]
iex> dates = [~D[2019-01-01], ~D[2020-03-02], ~D[2019-01-01], ~D[2020-03-02]]
iex> A.Enum.sort_uniq(dates, {:desc, Date})
[~D[2020-03-02], ~D[2019-01-01]]
Specs
Splits the enumerable
into two enumerables, leaving count
elements in the first one.
Mirrors Enum.split/2
with higher performance for Aja structures.
Specs
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.
Specs
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.
Specs
Returns the sum of all elements.
Mirrors Enum.sum/1
with higher performance for Aja structures.
Specs
Takes an amount
of elements from the beginning or the end of the enumerable
.
Mirrors Enum.take/2
with higher performance for Aja structures.
Specs
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.
Specs
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.
Specs
Converts enumerable
to a list.
Mirrors Enum.to_list/1
with higher performance for Aja structures.
Specs
Enumerates the enumerable
, removing all duplicated elements.
Mirrors Enum.uniq/1
with higher performance for Aja structures.
Specs
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.
Specs
with_index(t(val), index()) :: [{val, index()}] when val: value()
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
(Elixir 1.12 version): 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> A.Enum.with_index([:a, :b, :c])
[a: 0, b: 1, c: 2]
iex> A.Enum.with_index([:a, :b, :c], 3)
[a: 3, b: 4, c: 5]
iex> A.Enum.with_index([:a, :b, :c], fn element, index -> {index, element} end)
[{0, :a}, {1, :b}, {2, :c}]