defmodule Moar.Enum do
# @related [test](/test/enum_test.exs)
@moduledoc "Enum-related functions."
@doc "Like `Enum.at/3` but raises if `index` is out of bounds."
@spec at!(Enum.t(), integer() | [integer()], any()) :: any()
def at!(enum, index, default \\ nil) when is_integer(index) do
if length(enum) < index + 1,
do: raise("Out of range: index #{index} of enum with length #{length(enum)}: #{inspect(enum)}"),
else: Enum.at(enum, index, default)
end
@doc "Removes nil elements from `enum`."
@spec compact(Enum.t()) :: Enum.t()
def compact(enum),
do: enum |> Enum.reject(&is_nil(&1))
@doc """
Returns the indices of `elements` in `enum`, using `fun` for comparisons (defaulting to `Kernel.==/2`)
```elixir
iex> Moar.Enum.find_indices(~w[apple banana cherry], ~w[cherry apple])
[2, 0]
iex> Moar.Enum.find_indices(~w[apple banana cherry], ~w[CHERRY APPLE], fn a, b ->
...> String.downcase(a) == String.downcase(b)
...> end)
[2, 0]
```
"""
@spec find_indices(Enum.t(), [any()], (any(), any() -> boolean())) :: [integer()]
def find_indices(enum, elements, fun \\ &Kernel.==/2),
do: Enum.map(elements, &Enum.find_index(enum, fn element -> fun.(element, &1) end))
@doc """
Returns the indices of `elements` in `enum`, raising if any member of `elements` is not found.
```elixir
iex> Moar.Enum.find_indices!(~w[apple banana cherry], ~w[cherry apple])
[2, 0]
iex> Moar.Enum.find_indices!(~w[apple banana], ~w[cherry apple])
** (RuntimeError) Element "cherry" not present in:
["apple", "banana"]
```
"""
@spec find_indices!(Enum.t(), [any()], (any(), any() -> boolean())) :: [integer()]
def find_indices!(enum, elements, fun \\ &Kernel.==/2) do
Enum.map(elements, fn element ->
Enum.find_index(enum, fn member ->
fun.(member, element)
end) || raise("Element #{inspect(element)} not present in:\n#{inspect(enum)}")
end)
end
@doc "Returns the first item of `enum`, or raises if it is empty."
@spec first!(Enum.t()) :: any()
def first!(enum),
do: Enum.at(enum, 0) || raise("Expected enumerable to have at least one item")
@doc """
Converts an enum into a map of maps indexed by the return value of `index_fun`.
See also the similar map-specific `Moar.Map.index_by/2`.
```elixir
iex> Moar.Enum.index_by([%{name: "Alice", tid: "alice"}, %{name: "Billy", tid: "billy"}], & &1.tid)
%{"alice" => %{name: "Alice", tid: "alice"}, "billy" => %{name: "Billy", tid: "billy"}}
```
"""
@spec index_by(Enum.t(), (any() -> any())) :: map()
def index_by(enum, index_fun) when is_function(index_fun),
do: Enum.reduce(enum, %{}, fn value, acc -> Moar.Map.put_new!(acc, index_fun.(value), value) end)
@doc "Like `Enum.into` but accepts `nil` as the first argument"
@spec into!(nil | Enum.t(), Enum.t()) :: Enum.t()
def into!(nil, enumerable), do: enumerable
def into!(%_{} = struct, enumerable), do: struct |> Map.from_struct() |> into!(enumerable)
def into!(other, enumerable), do: Enum.into(other, enumerable)
@doc """
Deprecated in favor of `map_or_keyword?/1`.
"""
@spec is_map_or_keyword(any()) :: boolean()
@deprecated "Use map_or_keyword?/1"
def is_map_or_keyword(value),
do: map_or_keyword?(value)
@doc """
Returns true if the value is a map or a keyword list. This uses standard Elixir functions for determining
if a term is a map or a keyword, and therefore counts an empty list as a keyword list. See also
`map_or_nonempty_keyword?/1`.
This cannot be used as a guard because it uses `Keyword.keyword?` under the hood. Also, because of that,
it might scan an entire list to see if it's a keyword list, so it might be expensive.
"""
@spec map_or_keyword?(any()) :: boolean()
def map_or_keyword?(value),
do: is_map(value) || (is_list(value) && Keyword.keyword?(value))
@doc """
Deprecated in favor of `map_or_nonempty_keyword?/1`.
"""
@spec is_map_or_nonempty_keyword(any()) :: boolean()
@deprecated "Use map_or_nonempty_keyword?/1"
def is_map_or_nonempty_keyword(value),
do: is_map(value) || (is_list(value) && !Enum.empty?(value) && Keyword.keyword?(value))
@doc """
Like `map_or_keyword?/1` but returns false if the term is an empty list.
"""
@spec map_or_nonempty_keyword?(any()) :: boolean()
def map_or_nonempty_keyword?(value),
do: is_map(value) || (is_list(value) && !Enum.empty?(value) && Keyword.keyword?(value))
@doc "Sorts `enum` case-insensitively. Uses `Enum.sort_by/3` under the hood."
@spec isort(Enum.t()) :: Enum.t()
def isort(enum),
do: enum |> isort_by(&to_string/1)
@doc "Sorts `enum` case-insensitively by `mapper` function. Uses `Enum.sort_by/3` under the hood."
@spec isort_by(Enum.t(), (any() -> any())) :: Enum.t()
def isort_by(enum, mapper),
do: enum |> Enum.sort_by(&(mapper.(&1) |> String.downcase()))
@doc """
Converts a list of lists to a list of maps with the given keys. The keys can be a list, or can be `:first_list`
which uses the first list in `list_of_lists` as the keys and the remaining lists in `list_of_lists` as the values.
```elixir
iex> Moar.Enum.lists_to_maps([[1, 2], [3, 4]], ["a", "b"])
[%{"a" => 1, "b" => 2}, %{"a" => 3, "b" => 4}]
iex> csv = [["a", "b"], [1, 2], [3, 4]]
iex> [headers | rows] = csv
iex> Moar.Enum.lists_to_maps(rows, headers)
[%{"a" => 1, "b" => 2}, %{"a" => 3, "b" => 4}]
iex> csv = [["a", "b"], [1, 2], [3, 4]]
iex> Moar.Enum.lists_to_maps(csv, :first_list)
[%{"a" => 1, "b" => 2}, %{"a" => 3, "b" => 4}]
```
"""
@spec lists_to_maps(list(list(any())), list(any()) | :first_list) :: list(map())
def lists_to_maps([first_list | remaining_lists], :first_list),
do: lists_to_maps(remaining_lists, first_list)
def lists_to_maps(list_of_lists, keys),
do: Enum.map(list_of_lists, &Map.new(Enum.zip([keys, &1])))
@doc """
Returns a list of elements at the given indices, in the given order. If `:all` is given instead of a list of indices,
the entire enum is returned.
```elixir
iex> Moar.Enum.take_at(["A", "B", "C"], [0, 2])
["A", "C"]
iex> Moar.Enum.take_at(["A", "B", "C"], [2, 0])
["C", "A"]
iex> Moar.Enum.take_at(["A", "B", "C"], :all)
["A", "B", "C"]
```
"""
@spec take_at(Enum.t(), integer() | [integer()] | :all) :: any()
def take_at(enum, :all), do: enum
def take_at(enum, list) when is_list(list), do: Enum.map(list, &Enum.at(enum, &1))
@doc """
Returns `:test_id` fields from `enumerable`.
This unusual function exists because the authors of Moar use test_ids extensively in tests.
See also `tids/2`.
"""
@type test_ids_opts() :: {:sorted, boolean()}
@spec test_ids(Enum.t(), [test_ids_opts()]) :: list()
def test_ids(enumerable, opts \\ []) do
test_ids = enumerable |> Enum.map(& &1.test_id)
if Keyword.get(opts, :sorted),
do: test_ids |> Enum.sort(),
else: test_ids
end
@doc """
Returns `:tid` fields from `enumerable`.
This unusual function exists because the authors of Moar use tids (test IDs) extensively in tests.
See also `test_ids/2`.
"""
@type tids_opts() :: {:sorted, boolean()}
@spec tids(Enum.t(), [tids_opts()]) :: list()
def tids(enumerable, opts \\ []) do
tids = enumerable |> Enum.map(& &1.tid)
if Keyword.get(opts, :sorted),
do: tids |> Enum.sort(),
else: tids
end
end
