A.Enum (Aja v0.5.1) 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).

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.

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.

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
Link to this function

at(enumerable, index, default \\ nil)

View Source

Specs

at(t(val), integer(), default) :: val | default
when val: value(), default: any()

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

Mirrors Enum.at/3 with higher performance for Aja structures.

Specs

concat(t(val), t(val)) :: t(val) when val: value()

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

Mirrors Enum.concat/2 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

dedup(t(val)) :: [val] when val: value()

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.

Link to this function

dedup_by(enumerable, fun)

View Source

Specs

dedup_by(t(val), (val -> term())) :: [val] when val: value()

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.

Link to this function

drop(enumerable, amount)

View Source

Specs

drop(t(val), integer()) :: [val] when val: value()

Drops the amount of elements from the enumerable.

Mirrors Enum.drop/2 with higher performance for Aja structures.

Link to this function

drop_while(enumerable, fun)

View Source

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

each(t(val), (val -> term())) :: :ok when val: value()

Invokes the given fun for each element in the enumerable.

Mirrors Enum.each/2 with higher performance for Aja structures.

Specs

empty?(t(any())) :: boolean()

Returns true if enumerable is empty, otherwise false.

Mirrors Enum.empty?/1 with higher performance for Aja structures.

Link to this function

fetch(enumerable, index)

View Source

Specs

fetch(t(val), integer()) :: {:ok, val} | :error when val: value()

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

Mirrors Enum.fetch/2 with higher performance for Aja structures.

Link to this function

fetch!(enumerable, index)

View Source

Specs

fetch!(t(val), integer()) :: val when val: value()

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.

Link to this function

find(enumerable, default \\ nil, fun)

View Source

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.

Link to this function

find_index(enumerable, fun)

View Source

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.

Link to this function

find_value(enumerable, default \\ nil, fun)

View Source

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.

Link to this function

flat_map(enumerable, fun)

View Source

Specs

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.

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.

Link to this function

frequencies_by(enumerable, key_fun)

View Source

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.

Link to this function

group_by(enumerable, key_fun, value_fun \\ fn x -> x end)

View Source

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.

Link to this function

intersperse(enumerable, separator)

View Source

Specs

intersperse(t(val), separator) :: [val | separator]
when val: value(), separator: value()

Intersperses separator between each element of the given enumerable.

Mirrors Enum.intersperse/2 with higher performance for Aja structures.

Link to this function

into(enumerable, vector)

View Source

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.

Link to this function

join(enumerable, joiner \\ "")

View Source

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

map(t(v1), (v1 -> v2)) :: [v2] when v1: value(), v2: value()

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.

Link to this function

map_intersperse(enumerable, separator, mapper)

View Source

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.

Link to this function

map_join(enumerable, joiner \\ "", mapper)

View Source

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.

Link to this function

map_reduce(enumerable, acc, fun)

View Source

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.

Link to this function

max(enumerable, sorter \\ &>=/2, empty_fallback \\ fn -> raise(Enum.EmptyError) end)

View Source

Specs

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.

Link to this function

max_by(enumerable, fun, sorter \\ &>=/2, empty_fallback \\ fn -> raise(Enum.EmptyError) end)

View Source

Specs

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.

Link to this function

member?(enumerable, value)

View Source

Specs

member?(t(val), val) :: boolean() when val: value()

Checks if element exists within the enumerable.

Just an alias for Enum.member?/2, does not improve performance.

Link to this function

min(enumerable, sorter \\ &<=/2, empty_fallback \\ fn -> raise(Enum.EmptyError) end)

View Source

Specs

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.

Link to this function

min_by(enumerable, fun, sorter \\ &<=/2, empty_fallback \\ fn -> raise(Enum.EmptyError) end)

View Source

Specs

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

product(t(num)) :: num when num: number()

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

random(t(val)) :: val when val: value()

Returns a random element of an enumerable.

Mirrors Enum.random/1 with higher performance for Aja structures.

Specs

reduce(t(val), (val, val -> val)) :: val when val: value()

Invokes fun for each element in the enumerable with the accumulator.

Mirrors Enum.reduce/2 with higher performance for Aja structures.

Link to this function

reduce(enumerable, acc, fun)

View Source

Specs

reduce(t(val), acc, (val, acc -> acc)) :: acc when val: value(), acc: term()

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

reverse(t(val)) :: [val] when val: value()

Returns a list of elements in enumerable in reverse order.

Mirrors Enum.reverse/1 with higher performance for Aja structures.

Link to this function

reverse(enumerable, tail)

View Source

Specs

reverse(t(val), t(val)) :: [val] when val: value()

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

Mirrors Enum.reverse/2 with higher performance for Aja structures.

Specs

scan(t(val), (val, val -> val)) :: val when val: 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 first element in the enumerable as the starting value.

Mirrors Enum.scan/2 with higher performance for Aja structures.

Link to this function

scan(enumerable, acc, fun)

View Source

Specs

scan(t(val), acc, (val, acc -> acc)) :: acc when val: value(), acc: term()

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

shuffle(t(val)) :: [val] when val: value()

Returns a list with the elements of enumerable shuffled.

Mirrors Enum.shuffle/1 with higher performance for Aja structures.

Link to this function

slice(enumerable, index_range)

View Source

Specs

slice(t(val), Range.t()) :: [val] when val: value()

Returns a subset list of the given enumerable by index_range.

Mirrors Enum.slice/2 with higher performance for Aja structures.

Link to this function

slice(enumerable, start_index, amount)

View Source

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

sort(t(val)) :: [val] when val: value()

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.

Link to this function

sort_by(enumerable, mapper, sorter \\ &<=/2)

View Source

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.

Link to this function

split(enumerable, amount)

View Source

Specs

split(t(val), integer()) :: {[val], [val]} when val: value()

Splits the enumerable into two enumerables, leaving count elements in the first one.

Mirrors Enum.split/2 with higher performance for Aja structures.

Link to this function

split_while(enumerable, fun)

View Source

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.

Link to this function

split_with(enumerable, fun)

View Source

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

sum(t(num)) :: num when num: number()

Returns the sum of all elements.

Mirrors Enum.sum/1 with higher performance for Aja structures.

Link to this function

take(enumerable, amount)

View Source

Specs

take(t(val), integer()) :: [val] when val: value()

Takes an amount of elements from the beginning or the end of the enumerable.

Mirrors Enum.take/2 with higher performance for Aja structures.

Link to this function

take_random(enumerable, count)

View Source

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.

Link to this function

take_while(enumerable, fun)

View Source

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

to_list(t(val)) :: [val] when val: value()

Converts enumerable to a list.

Mirrors Enum.to_list/1 with higher performance for Aja structures.

Specs

uniq(t(val)) :: [val] when val: value()

Enumerates the enumerable, removing all duplicated elements.

Mirrors Enum.uniq/1 with higher performance for Aja structures.

Link to this function

uniq_by(enumerable, fun)

View Source

Specs

uniq_by(t(val), (val -> term())) :: [val] when val: value()

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

unzip(t({val1, val2})) :: {[val1], [val2]} when val1: value(), val2: value()

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.

Link to this function

with_index(enumerable, offset_or_fun \\ 0)

View Source

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}]
Link to this function

zip(enumerable1, enumerable2)

View Source

Specs

zip(t(val1), t(val2)) :: [{val1, val2}] when val1: value(), val2: value()

Zips corresponding elements from two enumerables into one list of tuples.

Mirrors Enum.zip/2 with higher performance for Aja structures.