gleam/result
Result represents the result of something that may succeed or not.
Ok means it was successful, Error means it was not successful.
Values
pub fn all(results: List(Result(a, e))) -> Result(List(a), e)Combines a list of results into a single result.
If all elements in the list are Ok then returns an Ok holding the list of values.
If any element is Error then returns the first error.
Examples
assert all([Ok(1), Ok(2)]) == Ok([1, 2])
assert all([Ok(1), Error("e")]) == Error("e")
pub fn flatten(result: Result(Result(a, e), e)) -> Result(a, e)Merges a nested Result into a single layer.
Examples
assert flatten(Ok(Ok(1))) == Ok(1)
assert flatten(Ok(Error(""))) == Error("")
assert flatten(Error(Nil)) == Error(Nil)
pub fn is_error(result: Result(a, e)) -> BoolChecks whether the result is an Error value.
Examples
assert !is_error(Ok(1))
assert is_error(Error(Nil))
pub fn is_ok(result: Result(a, e)) -> BoolChecks whether the result is an Ok value.
Examples
assert is_ok(Ok(1))
assert !is_ok(Error(Nil))
pub fn lazy_or(
first: Result(a, e),
second: fn() -> Result(a, e),
) -> Result(a, e)Returns the first value if it is Ok, otherwise evaluates the given function for a fallback value.
If you need access to the initial error value, use result.try_recover.
Examples
assert lazy_or(Ok(1), fn() { Ok(2) }) == Ok(1)
assert lazy_or(Ok(1), fn() { Error("Error 2") }) == Ok(1)
assert lazy_or(Error("Error 1"), fn() { Ok(2) }) == Ok(2)
assert lazy_or(Error("Error 1"), fn() { Error("Error 2") })
== Error("Error 2")
pub fn lazy_unwrap(
result: Result(a, e),
or default: fn() -> a,
) -> aExtracts the Ok value from a result, evaluating the default function if the result
is an Error.
Examples
assert lazy_unwrap(Ok(1), fn() { 0 }) == 1
assert lazy_unwrap(Error(""), fn() { 0 }) == 0
pub fn map(
over result: Result(a, e),
with fun: fn(a) -> b,
) -> Result(b, e)Updates a value held within the Ok of a result by calling a given function
on it.
If the result is an Error rather than Ok the function is not called and the
result stays the same.
Examples
assert map(over: Ok(1), with: fn(x) { x + 1 }) == Ok(2)
assert map(over: Error(1), with: fn(x) { x + 1 }) == Error(1)
pub fn map_error(
over result: Result(a, e),
with fun: fn(e) -> f,
) -> Result(a, f)Updates a value held within the Error of a result by calling a given function
on it.
If the result is Ok rather than Error the function is not called and the
result stays the same.
Examples
assert map_error(over: Error(1), with: fn(x) { x + 1 }) == Error(2)
assert map_error(over: Ok(1), with: fn(x) { x + 1 }) == Ok(1)
pub fn or(
first: Result(a, e),
second: Result(a, e),
) -> Result(a, e)Returns the first value if it is Ok, otherwise returns the second value.
Examples
assert or(Ok(1), Ok(2)) == Ok(1)
assert or(Ok(1), Error("Error 2")) == Ok(1)
assert or(Error("Error 1"), Ok(2)) == Ok(2)
assert or(Error("Error 1"), Error("Error 2")) == Error("Error 2")
pub fn partition(
results: List(Result(a, e)),
) -> #(List(a), List(e))Given a list of results, returns a pair where the first element is a list
of all the values inside Ok and the second element is a list with all the
values inside Error. The values in both lists appear in reverse order with
respect to their position in the original list of results.
Examples
assert partition([Ok(1), Error("a"), Error("b"), Ok(2)])
== #([2, 1], ["b", "a"])
pub fn replace(result: Result(a, e), value: b) -> Result(b, e)Replace the value within a result
Examples
assert replace(Ok(1), Nil) == Ok(Nil)
assert replace(Error(1), Nil) == Error(1)
pub fn replace_error(
result: Result(a, e),
error: f,
) -> Result(a, f)Replace the error within a result
Examples
assert replace_error(Error(1), Nil) == Error(Nil)
assert replace_error(Ok(1), Nil) == Ok(1)
pub fn try(
result: Result(a, e),
apply fun: fn(a) -> Result(b, e),
) -> Result(b, e)“Updates” an Ok result by passing its value to a function that yields a result,
and returning the yielded result. (This may “replace” the Ok with an Error.)
If the input is an Error rather than an Ok, the function is not called and
the original Error is returned.
This function is the equivalent of calling map followed by flatten, and
it is useful for chaining together multiple functions that may fail.
Examples
assert try(Ok(1), fn(x) { Ok(x + 1) }) == Ok(2)
assert try(Ok(1), fn(x) { Ok(#("a", x)) }) == Ok(#("a", 1))
assert try(Ok(1), fn(_) { Error("Oh no") }) == Error("Oh no")
assert try(Error(Nil), fn(x) { Ok(x + 1) }) == Error(Nil)
pub fn try_recover(
result: Result(a, e),
with fun: fn(e) -> Result(a, f),
) -> Result(a, f)Updates a value held within the Error of a result by calling a given function
on it, where the given function also returns a result. The two results are
then merged together into one result.
If the result is an Ok rather than Error the function is not called and the
result stays the same.
This function is useful for chaining together computations that may fail and trying to recover from possible errors.
If you do not need access to the initial error value, use result.lazy_or.
Examples
assert Ok(1)
|> try_recover(with: fn(_) { Error("failed to recover") })
== Ok(1)
assert Error(1)
|> try_recover(with: fn(error) { Ok(error + 1) })
== Ok(2)
assert Error(1)
|> try_recover(with: fn(error) { Error("failed to recover") })
== Error("failed to recover")
pub fn unwrap(result: Result(a, e), or default: a) -> aExtracts the Ok value from a result, returning a default value if the result
is an Error.
Examples
assert unwrap(Ok(1), 0) == 1
assert unwrap(Error(""), 0) == 0
pub fn unwrap_error(result: Result(a, e), or default: e) -> eExtracts the Error value from a result, returning a default value if the result
is an Ok.
Examples
assert unwrap_error(Error(1), 0) == 1
assert unwrap_error(Ok(""), 0) == 0