noether v0.2.1 Noether.Either

This module hosts several utility functions to work with {:ok, _} | {:error, _} values. These type of values will be then called Either.

Link to this section Summary

Functions

Given an {:ok, value} and a function that returns an Either value, it applies the function on the value. It effectively "squashes" an {:ok, {:ok, v}} or {:ok, {:error, _}} to its most appropriate representation. If an {:error, _} is given, it is returned as-is.

Given a list of Either, the function is mapped only on the elements of type {:ok, _}. Other values will be discarded. A list of the results is returned outside of the tuple.

Given a value and two functions that return an Either, it applies the first one and returns the result if it matches {:ok, _}. Otherwise the second function is applied.

Given an Either and two functions, it applies the first or second one on the second value of the tuple, depending if the value is {:ok, _} or {:error, _} respectively.

It returns true only if the value given matches a {:error, value} type.

Given an {:ok, {:ok, value}} it flattens the ok unwrapping the value and returning {:ok, value}. If an {:error, _} is given, it is returned as-is.

Given an {:ok, {:ok, value}} it flattens the ok unwrapping the value and returning {:ok, value}. If an {:error, _} is given, it is returned as-is.

Given an {:ok, value} and a function, it applies the function on the value returning {:ok, f.(value)}. If an {:error, _} is given, it is returned as-is.

Given a list of values and a function returning {:ok, any} or {:error, any}, it applies the function on every value returning {:ok, values} if every f.(v) results in {:ok, v}; returning {:error, _} if f.(v) results in an.

Given an Either and one function, it applies the function to the {:error, _} tuple.

It returns true only if the value given matches a {:ok, value} type.

It returns the value of an {:ok, value} only if such a tuple is given. If not, the default value (nil if not provided) is returned.

Given any value, it makes sure the result is an Either type.

Given any value, it makes sure the result is an Either type.

Link to this section Types

Link to this type

either()
either() :: {:ok, any()} | {:error, any()}

Link to this type

fun1()
fun1() :: (any() -> any())

Link to this section Functions

Link to this function

bind(a, f)
bind(either(), fun1()) :: either()

Given an {:ok, value} and a function that returns an Either value, it applies the function on the value. It effectively "squashes" an {:ok, {:ok, v}} or {:ok, {:error, _}} to its most appropriate representation. If an {:error, _} is given, it is returned as-is.

Examples

iex> bind({:ok, 1}, fn a -> {:ok, a + 1} end)
{:ok, 2}

iex> bind({:ok, 1}, fn _ -> {:error, 5} end)
{:error, 5}

iex> bind({:error, 1}, fn _ -> {:ok, 45} end)
{:error, 1}
Link to this function

cat_either(a, f)
cat_either([either()], fun1()) :: [any()]

Given a list of Either, the function is mapped only on the elements of type {:ok, _}. Other values will be discarded. A list of the results is returned outside of the tuple.

Examples

iex> cat_either([{:ok, 1}], &(&1 + 1))
[2]

iex> cat_either([{:ok, 1}, {:error, 2}, {:ok, 3}], &(&1 + 1))
[2, 4]
Link to this function

choose(a, f, g)
choose(either(), fun1(), fun1()) :: either()

Given a value and two functions that return an Either, it applies the first one and returns the result if it matches {:ok, _}. Otherwise the second function is applied.

Examples

iex> choose(0, fn a -> {:ok, a + 1} end, fn b -> {:ok, b + 2} end)
{:ok, 1}

iex> choose(0, fn _ -> {:error, 1} end, fn b -> {:ok, b + 2} end)
{:ok, 2}

iex> choose(0, fn _ -> {:error, 1} end, fn _ -> {:error, 2} end)
{:error, 2}
Link to this function

either(a, f, g)
either(either(), fun1(), fun1()) :: either()

Given an Either and two functions, it applies the first or second one on the second value of the tuple, depending if the value is {:ok, _} or {:error, _} respectively.

Examples

iex> either({:ok, 1}, &(&1 + 1), &(&1 + 2))
{:ok, 2}

iex> either({:error, 1}, &(&1 + 1), &(&1 + 2))
{:error, 3}
Link to this function

error?(a)
error?(any()) :: boolean()

It returns true only if the value given matches a {:error, value} type.

Examples

iex> error?({:ok, 1})
false

iex> error?({:error, 2})
true

iex> error?(3)
false
Link to this function

flat_map(a, f)
flat_map(either(), fun1()) :: either()

Given an {:ok, {:ok, value}} it flattens the ok unwrapping the value and returning {:ok, value}. If an {:error, _} is given, it is returned as-is.

Examples

iex> flat_map({:ok, {:ok, 1}}, &(&1 + 1))
{:ok, 2}

iex> flat_map({:ok, {:error, "Value not found"}}, &(&1 + 1))
{:error, "Value not found"}

iex> flat_map({:ok, 1}, &(&1 + 1))
** (FunctionClauseError) no function clause matching in Noether.Either.flat_map/2

iex> flat_map({:error, "Value not found"}, &(&1 + 1))
{:error, "Value not found"}

Given an {:ok, {:ok, value}} it flattens the ok unwrapping the value and returning {:ok, value}. If an {:error, _} is given, it is returned as-is.

Examples

iex> join({:ok, {:ok, 1}})
{:ok, 1}

iex> join({:ok, 1})
** (FunctionClauseError) no function clause matching in Noether.Either.join/1

iex> join({:error, "Value not found"})
{:error, "Value not found"}
Link to this function

map(a, f)
map(either(), fun1()) :: either()

Given an {:ok, value} and a function, it applies the function on the value returning {:ok, f.(value)}. If an {:error, _} is given, it is returned as-is.

Examples

iex> map({:ok, -1}, &Kernel.abs/1)
{:ok, 1}

iex> map({:error, "Value not found"}, &Kernel.abs/1)
{:error, "Value not found"}
Link to this function

map_all(values, f)
map_all([any()], (any() -> either())) :: {:ok, [any()]} | {:error, any()}

Given a list of values and a function returning {:ok, any} or {:error, any}, it applies the function on every value returning {:ok, values} if every f.(v) results in {:ok, v}; returning {:error, _} if f.(v) results in an.

Examples

iex> map_all(["23:50:07.0123456", "23:50:07.123Z"], &Time.from_iso8601/1)
{:ok, [~T[23:50:07.012345], ~T[23:50:07.123]]}

iex> map_all(["23:50:61", "23:50:07.123Z"], &Time.from_iso8601/1)
{:error, :invalid_time}
Link to this function

map_error(a, f)
map_error(either(), fun1()) :: either()

Given an Either and one function, it applies the function to the {:error, _} tuple.

Examples

iex> map_error({:ok, 1}, &(&1 + 1))
{:ok, 1}

iex> map_error({:error, 1}, &(&1 + 1))
{:error, 2}

It returns true only if the value given matches a {:ok, value} type.

Examples

iex> ok?({:ok, 1})
true

iex> ok?({:error, 2})
false

iex> ok?(3)
false
Link to this function

unwrap(a, b \\ nil)

It returns the value of an {:ok, value} only if such a tuple is given. If not, the default value (nil if not provided) is returned.

Examples

iex> unwrap({:ok, 1})
1

iex> unwrap(2)
nil

iex> unwrap({:ok, 1}, :default_value)
1

iex> unwrap(2, :default_value)
:default_value
Link to this function

wrap(a)
wrap(any()) :: either()

Given any value, it makes sure the result is an Either type.

Examples

iex> wrap({:ok, 1})
{:ok, 1}

iex> wrap({:error, 2})
{:error, 2}

iex> wrap(3)
{:ok, 3}
Link to this function

wrap_err(a)
wrap_err(any()) :: either()

Given any value, it makes sure the result is an Either type.

Examples

iex> wrap_err({:ok, 1})
{:ok, 1}

iex> wrap_err({:error, 2})
{:error, 2}

iex> wrap_err(3)
{:error, 3}