plymio_enum

v0.1.0

plymio_enum v0.1.0 Plymio.Enum.Utils

Utility Functions for Eumerables.

Below, a real enumerable means a concrete collection i.e. a List, Map, or Keyword, while a lazy enumerable is (usually) a Stream.

The functions try to be as lazy as possible, often returning a Stream.

Summary

Types

enum()

Functions

enum?(value)

Returns true if value is enumerable, else false

enum_2lists?(value)

Returns true if value is a enumerable of lists of size 2, else false

enum_2tuples?(value)

Returns true if value is a enum of tuples of size 2, else false

enum_length(arg0)

See Enum.count/1

enum_length(arg0, arg1)

See Enum.count/2

flat_just(value)

Flattens an enumerable, removes nils and returns a lazy enumerable

flatten(value)

Flattens an enumerable

just(value)

Removes nils from an enumerable and returns a lazy enumerable

keys!(value)

Returns the keys of an associative enumerable of 2tuples (e.g. Keyword, Map)

lazy?(value)

Returns true if value is a lazy enumerable, else false

maybe_realise(value)

Takes a value and if a lazy enumerable, realises (Enum.to_list/1), else returns the value

real?(value)

Returns true if value is a realised enumerable, else false

to_2tuples(enum)

Converts an enumerable into a stream of 2tuples and returns a lazy enumerable

to_enum(value)

Converts a value to an enumerable if necessary

to_keyword!(enum)

Converts an enumerable into a stream of 2tuples and returns a lazy enumerable of {atom, any} tuples

values!(value)

Returns the values of an enumerable of 2tuples (e.g. Keyword, Map)

wrap(value)

Create an enumerable from the value, unless already an enumerable

wrap_flat(value)
wrap_flat_just(value)

Wraps, flattens and removes nils. Returns a lazy enumerable

Types

enum() 
enum() :: Enumerable.t

Functions

enum?(value) 
enum?(any) :: true | false

Returns true if value is enumerable, else false

Examples 

iex> [1,2,3] |> enum?
true

iex> %{a: 1} |> enum?
true

iex> [1,2,3] |> Stream.map(&(&1)) |> enum?
true

iex> 42 |> enum?
false
enum_2lists?(value) 
enum_2lists?(any) :: true | false

Returns true if value is a enumerable of lists of size 2, else false.

Examples 

iex> [1,[21, 22],3] |> enum_2lists?
false

iex> [[11, 12], [21, 22], [31, 32]] |> enum_2lists?
true

iex> %{a: 1} |> enum_2lists?
false

iex> [[11, 12], [21, 22], [31, 32]] |> Stream.map(&(&1)) |> enum_2lists?
true

iex> 42 |> enum_2lists?
false
enum_2tuples?(value) 
enum_2tuples?(any) :: true | false

Returns true if value is a enum of tuples of size 2, else false.

Examples 

iex> [1,[21, 22],3] |> enum_2tuples?
false

iex> [a: 1, b: 2, c: 3] |> enum_2tuples?
true

iex> [{:a, 1}, {:b, 2}, {:c, 3}] |> enum_2tuples?
true

iex> [{"a", 1}, {"b", 2}, {"c", 3}] |> enum_2tuples?
true

iex> %{a: 1} |> enum_2tuples?
true

iex> [{:a, 1}, {:b, 2}, {:c, 3}] |> Stream.map(&(&1)) |> enum_2tuples?
true

iex> %{a: 1} |> Stream.map(&(&1)) |> enum_2tuples?
true

iex> 42 |> enum_2tuples?
false
enum_length(arg0)

See Enum.count/1.

enum_length(arg0, arg1)

See Enum.count/2.

flat_just(value) 
flat_just(enum) :: enum

Flattens an enumerable, removes nils and returns a lazy enumerable.

Examples 

iex> [{:a, 1}, nil, [{:b1, 12}, nil, {:b2, 22}], nil, {:c, 3}]
...> |> flat_just
...> |> Enum.to_list
[a: 1, b1: 12, b2: 22, c: 3]

iex> [{:a, 1}, nil, {:b, 2}, nil, {:c, 3}] |> Stream.map(&(&1))
...> |> flat_just
...> |> Enum.to_list
[{:a, 1}, {:b, 2}, {:c, 3}]

iex> stream = [{:a, 1}, nil, {:b, 2}, nil, {:c, 3}] |> Stream.map(&(&1))
...> |> flat_just
...> match?(%Stream{}, stream)
true
flatten(value) 
flatten(enum) :: enum

Flattens an enumerable.

If the enumerable is lazy, the result will also be lazy.

Note a Map is not considered an enumerable when flattening and an exception will be raised.

Similar to List.flatten/1

Examples 

iex> [{:a, 1}, [{:b1, 12}, {:b2, 22}], {:c, 3}] |> flatten
[a: 1, b1: 12, b2: 22, c: 3]

iex> [[{:a, 1}, {:b21, 21}], [[{:b22, 22}]], {:c, 3}] |> Stream.map(&(&1))
...> |> flatten
...> |> Enum.to_list
[{:a, 1}, {:b21, 21}, {:b22, 22}, {:c, 3}]

iex> stream = [[{:a, 1}, {:b21, 21}], [[{:b22, 22}]], {:c, 3}] |> Stream.map(&(&1))
...> |> flatten
...> is_function(stream)
true

iex> error = assert_raise FunctionClauseError, fn -> %{a: 1} |> flatten end
...> match?(%FunctionClauseError{}, error)
true

iex> [{:a, 1}, {:b, 2}, {:c, 3}] |> Stream.map(&(&1))
...> |> flatten
...> |> Enum.to_list
[{:a, 1}, {:b, 2}, {:c, 3}]
just(value) 
just(enum) :: enum

Removes nils from an enumerable and returns a lazy enumerable.

Examples 

iex> stream = [1, nil, 2, nil, 3] |> just
iex> Enum.to_list(stream)
[1, 2, 3]

iex> stream = %{a: 1, b: nil, c: 3} |> just
iex> Enum.to_list(stream)
[a: 1, b: nil, c: 3]

iex> stream = [{:a, 1}, nil, {:b, 2}, nil, {:c, 3}] |> Stream.map(&(&1)) |> just
iex> Enum.to_list(stream)
[{:a, 1}, {:b, 2}, {:c, 3}]
keys!(value) 
keys!(enum) :: enum | no_return

Returns the keys of an associative enumerable of 2tuples (e.g. Keyword, Map).

The same key may appear more than once in the return.

If the enumumerable is lazy, the return is also lazy.

When the enum is realised (e.g. Enum.to_list/1), it will fail with a FunctionClauseError if the enum elements do not match {k,v}.

Examples 

iex> [a: 1, b: 2, c: 3, a: 4, c: 5] |> keys!
[:a, :b, :c, :a, :c]

iex> %{a: 1} |> keys!
[:a]

iex> [{:a, 1}, {:b, 2}, {:c, 3}] |> Stream.map(&(&1))
...> |> keys!
...> |> Enum.to_list
[:a, :b, :c]

iex> [1, 2, 3] |> Stream.map(&(&1))
...> |> keys!
...> |> Enum.to_list
** (FunctionClauseError) no function clause matching in Plymio.Enum.Utils.enum_keys/1

iex> 42
...> |> keys!
...> |> Enum.to_list
** (FunctionClauseError) no function clause matching in Plymio.Enum.Utils.enum_keys/1

iex> stream = [{:a, 1}, {:b, 2}, {:c, 3}] |> Stream.map(&(&1))
...> |> keys!
...> match?(%Stream{}, stream)
true

iex> stream = %{a: 1} |> Stream.map(&(&1)) |> keys!
iex> Enum.to_list(stream)
[:a]
lazy?(value) 
lazy?(any) :: true | false

Returns true if value is a lazy enumerable, else false

Examples 

iex> [1,2,3] |> lazy?
false

iex> %{a: 1} |> lazy?
false

iex> [1,2,3] |> Stream.map(&(&1)) |> lazy?
true

iex> 42 |> lazy?
false
maybe_realise(value) 
maybe_realise(any) :: any

Takes a value and if a lazy enumerable, realises (Enum.to_list/1), else returns the value.

Examples 

iex> 1 |> maybe_realise
1

iex> [:a, :b, :c] |> maybe_realise
[:a, :b, :c]

iex> %{a: 1, b: 2, c: 3} |> maybe_realise
%{a: 1, b: 2, c: 3}

iex> [:a, :b, :c] |> Stream.map(&(&1)) |> maybe_realise
[:a, :b, :c]

iex> %{a: 1, b: 2, c: 3} |> Stream.map(&(&1)) |> maybe_realise
[a: 1, b: 2, c: 3]
real?(value) 
real?(any) :: true | false

Returns true if value is a realised enumerable, else false

Examples 

iex> [1,2,3] |> real?
true

iex> %{a: 1} |> real?
true

iex> [1,2,3] |> Stream.map(&(&1)) |> real?
false

iex> 42 |> real?
false
to_2tuples(enum) 
to_2tuples(enum) :: enum

Converts an enumerable into a stream of 2tuples and returns a lazy enumerable.

Uses Enum.chunk/4 to split the enumerable up into pairs.

Examples 

iex> ["a", 1, :b, 2, 31, 32]
...> |> to_2tuples
...> |> Enum.to_list
[{"a", 1}, {:b, 2}, {31, 32}]

iex> stream = ["a", 1, :b, 2, 31, 32]
...> |> to_2tuples
...> match?(%Stream{}, stream)
true

iex> [{:a, 1}, {:b, 2}, {:c, 3}, {:d, 4}]
...> |> to_2tuples
...> |> Enum.to_list
[{{:a, 1}, {:b, 2}}, {{:c, 3}, {:d, 4}}]

iex> [:a, 1, :b, 2, :c, 3] |> Stream.map(&(&1))
...> |> to_2tuples
...> |> Enum.to_list
[{:a, 1}, {:b, 2}, {:c, 3}]
to_enum(value) 
to_enum(any) :: enum

Converts a value to an enumerable if necessary.

Non-enumerables are wrapped in a List.

Examples 

iex> [1,[21, 22],3] |> to_enum
[1,[21, 22],3]

iex> [a: 1, b: 2, c: 3] |> to_enum
[a: 1, b: 2, c: 3]

iex> [{:a, 1}, {:b, 2}, {:c, 3}] |> to_enum
[{:a, 1}, {:b, 2}, {:c, 3}]

iex> %{a: 1} |> to_enum
%{a: 1}

iex> stream = [{:a, 1}, {:b, 2}, {:c, 3}] |> Stream.map(&(&1)) |> to_enum
iex> Enum.to_list(stream)
[{:a, 1}, {:b, 2}, {:c, 3}]

iex> stream = %{a: 1} |> Stream.map(&(&1)) |> to_enum
iex> Enum.to_list(stream)
[a: 1]

iex> 42 |> to_enum
[42]

iex> :abc |> to_enum
[:abc]
to_keyword!(enum) 
to_keyword!(enum) :: enum | no_return

Converts an enumerable into a stream of 2tuples and returns a lazy enumerable of {atom, any} tuples.

Examples 

iex> stream = [:a, 1, :b, 2, :c, 3] |> to_keyword!
iex> Enum.to_list(stream)
[{:a, 1}, {:b, 2}, {:c, 3}]

iex> stream = [:a, 1, :b, 2, :c, 3] |> Stream.map(&(&1)) |> to_keyword!
iex> Enum.to_list(stream)
[{:a, 1}, {:b, 2}, {:c, 3}]
values!(value) 
values!(enum) :: enum | no_return

Returns the values of an enumerable of 2tuples (e.g. Keyword, Map)

If the enumumerable is lazy, the return is also lazy.

Examples 

iex> [a: 1, b: 2, c: 3, a: 4, c: 5] |> values!
[1, 2, 3, 4, 5]

iex> %{a: 1} |> values!
[1]

iex> stream = [{:a, 1}, {:b, 2}, {:c, 3}] |> Stream.map(&(&1)) |> values!
iex> Enum.to_list(stream)
[1, 2, 3]

iex> stream = %{a: 1} |> Stream.map(&(&1)) |> values!
iex> Enum.to_list(stream)
[1]
wrap(value) 
wrap(enum) :: enum

Create an enumerable from the value, unless already an enumerable.

Similar to List.wrap/1.

Note a Map is not considered an enumerable when wrapping (i.e same behaviour as List.wrap/1).

Examples 

iex> [a: 1, b: 2, c: 3] |> wrap
[a: 1, b: 2, c: 3]

iex> %{a: 1} |> wrap
[%{a: 1}]

iex> stream = [{:a, 1}, {:b, 2}, {:c, 3}] |> Stream.map(&(&1)) |> wrap
iex> Enum.to_list(stream)
[{:a, 1}, {:b, 2}, {:c, 3}]
wrap_flat(value)
wrap_flat_just(value) 
wrap_flat_just(any) :: enum

Wraps, flattens and removes nils. Returns a lazy enumerable.

Examples 

iex> [{:a, 1}, nil, [{:b1, 12}, nil, {:b2, 22}], nil, {:c, 3}]
...> |> wrap_flat_just
...> |> Enum.to_list
[a: 1, b1: 12, b2: 22, c: 3]

iex> stream = [{:a, 1}, nil, [{:b1, 12}, nil, {:b2, 22}], nil, {:c, 3}]
...> |> wrap_flat_just
...> match?(%Stream{}, stream)
true

iex> [{:a, 1}, nil, {:b, 2}, nil, {:c, 3}] |> Stream.map(&(&1))
...> |> wrap_flat_just
...> |> Enum.to_list
[{:a, 1}, {:b, 2}, {:c, 3}]

iex> 42 |> wrap_flat_just
...> |>  Enum.to_list
[42]