Specs

error_consume(result_input(), (any() -> any())) :: result_input() | :none

If result is tagged with :error, passes the wrapped value into the provided function (if provided) and returns :none.

If result is not tagged with :error, result is returned as-is.

Equivalent to tagged_consume(result, :error, func_or_value). See tagged_consume/3.

Examples

iex> :error |> Result.error_consume()
:none

iex> :error |> Result.error_consume(fn -> "hello" end)
:none

iex> :error |> Result.error_consume(fn {} -> "hello" end)
:none

iex> {:error, 1} |> Result.error_consume(fn 1 -> "hello" end)
:none

iex> {:error, 1, 2} |> Result.error_consume(fn 1, 2 -> "hello" end)
** (ArgumentError) Value-mapping function must have arity between 0 and 1.

iex> {:error, 1, 2} |> Result.error_consume(fn {1, 2} -> "hello" end)
:none

iex> :ok |> Result.error_consume(fn {} -> "hello" end)
:ok

iex> {:ok, 1} |> Result.error_consume(fn 1 -> "hello" end)
{:ok, 1}

iex> "bare value" |> Result.error_consume()
"bare value"

Specs

error_filter(
  result_input(),
  OkThen.Result.Private.func_or_value(as_boolean(any()))
) :: result_input()

If result is tagged :error, passes the wrapped value into the provided function. If func_or_value returns a truthy value, result is returned unchanged. Otherwise, returns :none. If func_or_value is not a function, then it is used directly as the check value.

Equivalent to tagged_filter(result, :error, func_or_value). See tagged_filter/3.

Examples

iex> {:error, "hello"} |> Result.error_filter(&String.length(&1) == 5)
{:error, "hello"}

iex> {:error, "hello"} |> Result.error_filter(&String.length(&1) == 0)
:none

iex> {:error, "hello"} |> Result.error_filter(fn -> true end)
{:error, "hello"}

iex> {:error, "hello"} |> Result.error_filter(fn -> false end)
:none

iex> {:error, "hello"} |> Result.error_filter(true)
{:error, "hello"}

iex> {:error, "hello"} |> Result.error_filter(false)
:none

iex> :some |> Result.error_filter(&String.length(&1) == 0)
:some

iex> :ok |> Result.error_filter(&String.length(&1) == 0)
:ok

iex> nil |> Result.error_filter(&String.length(&1) == 0)
nil

Specs

error_map(t, OkThen.Result.Private.func_or_value(out)) ::
  t | :error | error(out)
when t: result_input(), out: any()

If result is tagged :error, transforms the wrapped value by passing it into the provided mapping function, and replacing it with the returned value. If func_or_value is not a function, then it is used directly as the new value.

If the new value would be nil, then :none is returned as the result instead. Consider piping into |> none_then({:error, nil}) if you really want {:error, nil}. See none_then/2.

If result is not tagged :error, result is returned as-is.

Equivalent to tagged_map(result, :error, func_or_value). See tagged_map/3.

Examples

iex> :error |> Result.error_map("hello")
{:error, "hello"}

iex> {:error, 1} |> Result.error_map("hello")
{:error, "hello"}

iex> {:error, 1} |> Result.error_map(nil)
:none

iex> :none |> Result.error_map("hello")
:none

iex> :error |> Result.error_map(fn {} -> "hello" end)
{:error, "hello"}

iex> {:error, 1} |> Result.error_map(fn 1 -> "hello" end)
{:error, "hello"}

iex> {:error, 1, 2} |> Result.error_map(fn {1, 2} -> "hello" end)
{:error, "hello"}

iex> {:error, 1, 2} |> Result.error_map(fn 1, 2 -> "hello" end)
** (ArgumentError) Value-mapping function must have arity between 0 and 1.

iex> {:error, 1, 2} |> Result.error_map(fn {1, 2} -> {} end)
:error

iex> :ok |> Result.error_map(fn _ -> "hello" end)
:ok

iex> {:ok, 1} |> Result.error_map(fn _ -> "hello" end)
{:ok, 1}

iex> {:ok, 1, 2} |> Result.error_map(fn _ -> "hello" end)
{:ok, 1, 2}

iex> :none |> Result.error_map(fn _ -> "hello" end)
:none

iex> :something_else |> Result.error_map(fn _ -> "hello" end)
:something_else

iex> "bare value" |> Result.error_map(fn _ -> "hello" end)
"bare value"

iex> "bare value" |> Result.error_map("hello")
"bare value"

Specs

error_or_else(result_input(), OkThen.Result.Private.func_or_value(atom(), out)) ::
  out
when out: any()

If result is not tagged with :error, passes the tag and wrapped value into the provided function and returns the result. If the function has arity 1, then only the wrapped value is passed in. If func_or_value is not a function, then it is used directly as the new value.

If result is tagged with :error, result is returned as-is.

Use this function in a pipeline to branch the happy path into another function, or as a kind of case expression to handle multiple types of result without the boilerplate of copying through an error result.

Be aware that no attempt is made to ensure the return value from the function is a tagged tuple. However, all functions are tolerant of untagged results, and on input will interpret them as an {:untagged, value} tuple.

Equivalent to tagged_or_else(result, :error, func_or_value). See tagged_or_else/3.

Examples

iex> :ok
...> |> Result.error_or_else(fn
...>   :ok, {} -> {:ok, "hello"}
...> end)
{:ok, "hello"}

iex> {:ok, 1}
...> |> Result.error_or_else(fn
...>   :ok, 1 -> {:ok, "hello"}
...> end)
{:ok, "hello"}

iex> {:ok, 1, 2}
...> |> Result.error_or_else(fn
...>   :ok, {1, 2} -> {:ok, "matched ok"}
...>   :none, {} -> {:ok, "matched none"}
...> end)
{:ok, "matched ok"}

iex> :none
...> |> Result.error_or_else(fn
...>   :ok, {1, 2} -> {:ok, "matched ok"}
...>   :none, {} -> {:ok, "matched none"}
...> end)
{:ok, "matched none"}

iex> {:error, "just error"}
...> |> Result.error_or_else(fn
...>   :ok, {1, 2} -> {:ok, "matched ok"}
...>   :none, {} -> {:ok, "matched none"}
...> end)
{:error, "just error"}

iex> {:ok, 1, 2}
...> |> Result.error_or_else(fn
...>   {1, 2} -> {:ok, "matched two terms"}
...>   1 -> {:ok, "matched one term"}
...>   {} -> {:ok, "matched no terms"}
...> end)
{:ok, "matched two terms"}

iex> {:ok, 1}
...> |> Result.error_or_else(fn
...>   {1, 2} -> {:ok, "matched two terms"}
...>   1 -> {:ok, "matched one term"}
...>   {} -> {:ok, "matched no terms"}
...> end)
{:ok, "matched one term"}

iex> :ok
...> |> Result.error_or_else(fn
...>   {1, 2} -> {:ok, "matched two terms"}
...>   1 -> {:ok, "matched one term"}
...>   {} -> {:ok, "matched no terms"}
...> end)
{:ok, "matched no terms"}

iex> :none
...> |> Result.error_or_else(fn
...>   {1, 2} -> {:ok, "matched two terms"}
...>   1 -> {:ok, "matched one term"}
...>   {} -> {:ok, "matched no terms"}
...> end)
{:ok, "matched no terms"}

iex> :ok |> Result.error_or_else({:ok, "hello"})
{:ok, "hello"}

iex> {:ok, 1} |> Result.error_or_else({:ok, "hello"})
{:ok, "hello"}

iex> {:ok, 1} |> Result.error_or_else("bare value")
"bare value"

iex> "bare value" |> Result.error_or_else(fn _ -> :none end)
:none

iex> "bare value" |> Result.error_or_else(fn
...>  :untagged, "bare value" -> :none
...> end)
:none

Specs

error_retag(result_input(), new_tag) :: new_tag | {new_tag, any()}
when new_tag: atom()

If result is tagged :error, replaces the tag with new_tag, returning a new tagged tuple.

Equivalent to tagged_retag(result, :error, new_tag). See tagged_retag/3.

Examples

iex> :error |> Result.error_retag(:none)
:none

iex> {:error, "hello"} |> Result.error_retag(:ok)
{:ok, "hello"}

iex> {:error, 1, 2} |> Result.error_retag(:ok)
{:ok, {1, 2}}

iex> {:ok, 1, 2} |> Result.error_retag(:error)
{:ok, 1, 2}

iex> :error |> Result.error_retag("string")
** (ArgumentError) Expected atom as new tag, got: "string".

iex> "bare value" |> Result.error_retag(:ok)
"bare value"

Specs

error_tap(result_input(), OkThen.Result.Private.func_or_value(any())) ::
  result_input()

If result is tagged with :error, passes the wrapped value into the provided function and returns result unchanged. The return value of the function is ignored.

If result is not tagged with :error, the provided function is not called.

Equivalent to tagged_tap(result, :error, function). See tagged_tap/3.

Examples

iex> capture_io(fn ->
...>  assert :error |> Result.error_tap(fn -> IO.write("hello") end) == :error
...> end)
"hello"

iex> capture_io(fn ->
...>  input = {:error, "reason"}
...>  assert input |> Result.error_tap(fn "reason" -> IO.write("hello") end) == input
...> end)
"hello"

iex> capture_io(fn ->
...>  input = {:error, "one", "two"}
...>  function = fn {"one", "two"} -> IO.write("hello") end
...>  assert input |> Result.error_tap(function) == input
...> end)
"hello"

iex> capture_io(fn ->
...>  input = {:ok, "in"}
...>  assert input |> Result.error_tap(fn -> IO.write("hello") end) == input
...> end)
""

Specs

error_then(result_input(), OkThen.Result.Private.func_or_value(out)) :: out
when out: any()

If result is tagged :error, passes the wrapped value into func_or_value and returns the result. If a function is not provided, the argument at the same position is returned as-is.

If result is not tagged with the specified tag atom, result is returned as-is.

Use this function to pipe results into functions that return tagged tuples.

Be aware that no attempt is made to ensure the return value from the function is a tagged tuple. However, all functions are tolerant of untagged results, and on input will interpret them as an {:untagged, value} tuple.

Equivalent to tagged_then(result, :error, func_or_value). See tagged_then/3.

Examples

iex> :error |> Result.error_then({:ok, "hello"})
{:ok, "hello"}

iex> {:error, 1} |> Result.error_then({:ok, "hello"})
{:ok, "hello"}

iex> :none |> Result.error_then({:ok, "hello"})
:none

iex> :error |> Result.error_then(fn -> {:ok, "hello"} end)
{:ok, "hello"}

iex> :error |> Result.error_then(fn {} -> {:ok, "hello"} end)
{:ok, "hello"}

iex> {:error, 1} |> Result.error_then(fn 1 -> {:ok, "hello"} end)
{:ok, "hello"}

iex> {:error, 1, 2} |> Result.error_then(fn {1, 2} -> {:ok, "hello"} end)
{:ok, "hello"}

iex> {:error, 1, 2} |> Result.error_then(fn 1, 2 -> {:ok, "hello"} end)
** (ArgumentError) Value-mapping function must have arity between 0 and 1.

iex> {:error, 1, 2} |> Result.error_then(fn {1, 2} -> :ok end)
:ok

iex> :ok |> Result.error_then(fn _ -> {:ok, "hello"} end)
:ok

iex> {:ok, 1} |> Result.error_then(fn _ -> {:ok, "hello"} end)
{:ok, 1}

iex> {:ok, 1, 2} |> Result.error_then(fn _ -> {:ok, "hello"} end)
{:ok, 1, 2}

iex> :none |> Result.error_then(fn _ -> {:ok, "hello"} end)
:none

iex> :something_else |> Result.error_then(fn _ -> {:ok, "hello"} end)
:something_else

iex> "bare value" |> Result.error_then({:ok, "hello"})
"bare value"

iex> "bare value" |> Result.error_then(fn _ -> {:ok, "hello"} end)
"bare value"

Specs

error_unwrap!(result_input()) :: any()

Same as error_unwrap_or_else/2, except raises ArgumentError if result is not tagged :error.

Examples

iex> {:error, "hello"} |> Result.error_unwrap!()
"hello"

iex> :error |> Result.error_unwrap!()
{}

iex> :ok |> Result.error_unwrap!()
** (ArgumentError) Result is not tagged error: :ok.

iex> {:ok, "hello"} |> Result.error_unwrap!()
** (ArgumentError) Result is not tagged error: {:ok, "hello"}.

iex> :none |> Result.error_unwrap!()
** (ArgumentError) Result is not tagged error: :none.

iex> "hello" |> Result.error_unwrap!()
** (ArgumentError) Result is not tagged error: "hello".

Specs

error_unwrap_or_else(result_input(), OkThen.Result.Private.func_or_value(any())) ::
  any()

Returns the wrapped value if result is tagged :error. Otherwise, passes the tag and wrapped value into the provided function and returns the result. If the function has arity 1, then only the wrapped value is passed in. An arity-0 function is also accepted. If func_or_value is not a function, then it is used directly as the new value.

See also tagged_or_else/3.

Equivalent to tagged_unwrap_or_else(result, :error, default). See tagged_unwrap_or_else/3.

Examples

iex> {:error, "hello"} |> Result.error_unwrap_or_else("default")
"hello"

iex> :error |> Result.error_unwrap_or_else("default")
{}

iex> :ok |> Result.error_unwrap_or_else("default")
"default"

iex> {:ok, "hello"} |> Result.error_unwrap_or_else("default")
"default"

iex> {:ok, "hello"}
...> |> Result.error_unwrap_or_else(fn
...>   :ok, "hello" -> "default"
...> end)
"default"

iex> {:ok, "hello"}
...> |> Result.error_unwrap_or_else(fn
...>   "hello" -> "default"
...> end)
"default"

iex> {:error, "hello"} |> Result.tagged_unwrap_or_else(:ok, fn -> "default" end)
"default"

iex> :none |> Result.error_unwrap_or_else("default")
"default"

iex> "hello" |> Result.error_unwrap_or_else("default")
"default"