View Source OnePiece.Result (OnePiece.Result v0.3.0)
Handles t/0
responses. Inspired by Rust std::result::Result
package.
Link to this section Summary
Functions
Do an and
with a err/0
.
Do an and
with a ok/0
.
Returns true if the err/0
result contains the given value.
Returns true if the ok/0
result contains the given value.
Wraps a value into an err/0
result.
Returns the contained ok/0
value, or raise an exception with the given error message.
Returns the contained ok/0
value, or raise an exception with the given error message.
Returns true if the result is err/0
and the value inside of it matches a predicate.
Is valid if and only if an err/0
is supplied.
Returns true if the argument is an err/0
.
Returns true if the result is ok/0
and the value inside of it matches a predicate.
Is valid if and only if an ok/0
is supplied.
Returns true if the argument is a ok/0
.
Tap into err/0
results.
Tap into ok/0
results.
Unwrap an err/0
result, or raise an exception.
Unwrap an ok/0
result, or raise an exception.
Returns the contained ok/0
value or a provided default.
Applies a function or returns the value when a ok/0
is given, or propagates the error.
Link to this section Types
Link to this section Functions
Do an and
with a err/0
.
When passing any ok/0
result, it returns the first ok/0
value. Otherwise, when passing two err/0
results,
then returns the second err/0
.
iex> 21
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.and_err(OnePiece.Result.ok(42))
{:ok, 21}
iex> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.and_err(OnePiece.Result.err("something went wrong"))
{:ok, 42}
iex> "something went wrong"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.and_err(OnePiece.Result.ok(42))
{:ok, 42}
iex> "something went wrong"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.and_err(OnePiece.Result.err("late error"))
{:error, "late error"}
Do an and
with a ok/0
.
When passing two ok/0
result, it returns the second ok/0
value. When a ok/0
and a err/0
result, then
returns the err/0
. Otherwise, when passing two err/0
result, it returns the earliest err/0
.
iex> 21
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.and_ok(OnePiece.Result.ok(42))
{:ok, 42}
iex> 21
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.and_ok(OnePiece.Result.err("something went wrong"))
{:error, "something went wrong"}
iex> "something went wrong"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.and_ok(OnePiece.Result.ok(42))
{:error, "something went wrong"}
iex> "something went wrong"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.and_ok(OnePiece.Result.err("late error"))
{:error, "something went wrong"}
Iterate over t/0
list unwrapping the ok/0
values. It fails at the first err/0
.
iex> OnePiece.Result.collect([
...> OnePiece.Result.ok(21),
...> OnePiece.Result.ok(42),
...> OnePiece.Result.ok(84),
...> ])
{:ok, [21,42,84]}
iex> OnePiece.Result.collect([
...> OnePiece.Result.ok(21),
...> OnePiece.Result.err("oops"),
...> OnePiece.Result.ok(84),
...> ])
{:error, "oops"}
Returns true if the err/0
result contains the given value.
iex> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.contains_err?("oops")
true
iex> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.contains_err?("nop")
false
iex> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.contains_err?("ops")
false
Returns true if the ok/0
result contains the given value.
iex> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.contains_ok?(42)
true
iex> 21
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.contains_ok?(42)
false
iex> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.contains_ok?(42)
false
Wraps a value into an err/0
result.
iex> OnePiece.Result.err("oops")
{:error, "oops"}
Returns the contained ok/0
value, or raise an exception with the given error message.
iex> try do
...> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.expect_err!("expected a oops")
...> rescue
...> e -> e.message
...> end
"expected a oops"
iex> try do
...> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.expect_err!("expected a oops")
...> rescue
...> _ -> "was a unwrap failure"
...> end
"oops"
Returns the contained ok/0
value, or raise an exception with the given error message.
iex> try do
...> 21
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.expect_ok!("expected 42")
...> rescue
...> e -> e.message
...> end
"expected 42"
iex> try do
...> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.expect_ok!("expected 42")
...> rescue
...> _ -> "was a unwrap failure"
...> end
42
Converts from a nested t/0
to flatten t/0
.
iex> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.flatten()
{:ok, 42}
iex> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.flatten()
{:error, {:ok, 42}}
iex> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.flatten()
{:error, "oops"}
iex> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.flatten()
{:error, {:error, "oops"}}
Returns true if the result is err/0
and the value inside of it matches a predicate.
iex> is_not_found = fn err -> err == :not_found end
...> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.is_err_and?(is_not_found)
false
iex> is_not_found = fn err -> err == :not_found end
...> :not_found
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.is_err_and?(is_not_found)
true
Is valid if and only if an err/0
is supplied.
iex> check = fn
...> val when OnePiece.Result.is_err_result(val) -> true
...> _ -> false
...> end
...> 42
...> |> OnePiece.Result.ok()
...> |> check.()
false
iex> check = fn
...> val when OnePiece.Result.is_err_result(val) -> true
...> _ -> false
...> end
...> "oops"
...> |> OnePiece.Result.err()
...> |> check.()
true
Returns true if the argument is an err/0
.
iex> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.is_err?()
false
iex> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.is_err?()
true
Returns true if the result is ok/0
and the value inside of it matches a predicate.
iex> is_meaning_of_life = fn x -> x == 42 end
...> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.is_ok_and?(is_meaning_of_life)
true
iex> is_meaning_of_life = fn x -> x == 42 end
...> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.is_ok_and?(is_meaning_of_life)
false
Is valid if and only if an ok/0
is supplied.
iex> check = fn
...> val when OnePiece.Result.is_ok_result(val) -> true
...> _ -> false
...> end
...> 42
...> |> OnePiece.Result.ok()
...> |> check.()
true
iex> check = fn
...> val when OnePiece.Result.is_ok_result(val) -> true
...> _ -> false
...> end
...> "oops"
...> |> OnePiece.Result.err()
...> |> check.()
false
Returns true if the argument is a ok/0
.
iex> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.is_ok?()
true
iex> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.is_ok?()
false
When the value contained in an err/0
result then applies a function or returns the mapped value, wrapping the
returning value in a err/0
, propagating the ok/0
result as it is.
Avoid Wrapping
If you want to avoid the wrap then use
OnePiece.Result.when_err/2
instead.
iex> 21
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.map_err("must be 42")
{:error, "must be 42"}
iex> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.map_err("must be 42")
{:ok, 42}
You can also pass a function to achieve lazy evaluation:
iex> meaning_of_life = fn x -> "must be 42 instead of #{x}" end
...> 21
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.map_err(meaning_of_life)
{:error, "must be 42 instead of 21"}
When the value contained in an ok/0
result then applies a function or returns the mapped value, wrapping the
returning value in a ok/0
, propagating the err/0
result as it is.
Avoid Wrapping
If you want to avoid the wrap then use
OnePiece.Result.when_ok/2
instead.
iex> 21
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.map_ok(42)
{:ok, 42}
iex> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.map_ok(42)
{:error, "oops"}
You can also pass a function to achieve lazy evaluation:
iex> meaning_of_life = fn x -> x * 2 end
...> 21
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.map_ok(meaning_of_life)
{:ok, 42}
@spec map_ok_or( result :: t(), on_ok :: (any() -> any()), on_error :: any() | (any() -> any()) ) :: any()
Applies a on_ok
function to the contained value if ok/0
otherwise applies a on_err
function or return the
on_err
value if err/0
.
iex> meaning_of_life = fn x -> x * 2 end
...> 21
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.map_ok_or(meaning_of_life, 84)
42
iex> meaning_of_life = fn x -> x * 2 end
...> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.map_ok_or(meaning_of_life, 84)
84
Lazy Evaluation
It is recommended to pass a function as the default value, which is lazily evaluated.
iex> meaning_of_life = fn x -> x * 2 end
...> went_wrong = fn reason -> "something went wrong because #{reason}" end
...> 21
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.map_ok_or(meaning_of_life, went_wrong)
42
iex> meaning_of_life = fn x -> x * 2 end
...> went_wrong = fn reason -> "something went wrong because #{reason}" end
...> "a sleepy bear"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.map_ok_or(meaning_of_life, went_wrong)
"something went wrong because a sleepy bear"
Wraps a value into an ok/0
result.
iex> OnePiece.Result.ok(42)
{:ok, 42}
When nil
is passed then calls the on_nil
function and wrap the result into a err/0
. When t/0
is passed
then returns it as it is. Otherwise wraps the value into a ok/0
.
iex> OnePiece.Result.reject_nil(nil, "ooopps")
{:error, "ooopps"}
iex> OnePiece.Result.reject_nil(42, "ooopps")
{:ok, 42}
iex> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.reject_nil("ooopps")
{:ok, 42}
iex> "my error"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.reject_nil("ooopps")
{:error, "my error"}
Lazy Evaluation
It is recommended to pass a function as the default value, which is lazily evaluated.
iex> new_error = fn -> "ooops" end
...> OnePiece.Result.reject_nil(nil, new_error)
{:error, "ooops"}
Tap into err/0
results.
iex> failure_log = fn err -> "Failure because #{err}" end
...> "ooopsy"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.tap_err(failure_log)
{:error, "ooopsy"}
Tap into ok/0
results.
iex> success_log = fn x -> "Success #{x}" end
...> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.tap_ok(success_log)
{:ok, 42}
Unwrap an err/0
result, or raise an exception.
iex> try do
...> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.unwrap_err!()
...> rescue
...> OnePiece.Result.ErrUnwrapError -> "was a unwrap failure"
...> end
"oops"
iex> try do
...> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.unwrap_err!()
...> rescue
...> OnePiece.Result.ErrUnwrapError -> "was a unwrap failure"
...> end
"was a unwrap failure"
Unwrap an ok/0
result, or raise an exception.
iex> try do
...> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.unwrap_ok!()
...> rescue
...> OnePiece.Result.OkUnwrapError -> "was a unwrap failure"
...> end
42
iex> try do
...> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.unwrap_ok!()
...> rescue
...> OnePiece.Result.OkUnwrapError -> "was a unwrap failure"
...> end
"was a unwrap failure"
Returns the contained ok/0
value or a provided default.
iex> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.unwrap_ok(21)
42
iex> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.unwrap_ok(21)
21
Lazy Evaluation
It is recommended to pass a function as the default value, which is lazily evaluated.
iex> say_hello_world = fn _x -> "hello, world!" end
...> 42
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.unwrap_ok(say_hello_world)
42
iex> say_hello_world = fn _x -> "hello, world!" end
...> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.unwrap_ok(say_hello_world)
"hello, world!"
Applies a function or returns the value if the result is err/0
, otherwise returns the ok/0
value.
iex> "something wrong happened"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.when_err("ooops")
"ooops"
iex> 2
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.when_err("ooops")
{:ok, 2}
You can also pass a function to achieve lazy evaluation:
iex> failure = fn _error -> "lazy ooops" end
...> "something wrong happened"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.when_err(failure)
"lazy ooops"
Applies a function or returns the value when a ok/0
is given, or propagates the error.
iex> 21
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.when_ok(42)
42
iex> "oops"
...> |> OnePiece.Result.err()
...> |> OnePiece.Result.when_ok(42)
{:error, "oops"}
You can also pass a function to achieve lazy evaluation:
iex> meaning_of_life = fn x -> x * 2 end
...> 21
...> |> OnePiece.Result.ok()
...> |> OnePiece.Result.when_ok(meaning_of_life)
42