gleam/result
Result represents the result of something that may succeed or not.
Ok
means it was successful, Error
means it was not successful.
Functions
pub fn all(results: List(Result(a, b))) -> Result(List(a), b)
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
all([Ok(1), Ok(2)])
// -> Ok([1, 2])
all([Ok(1), Error("e")])
// -> Error("e")
pub fn flatten(result: Result(Result(a, b), b)) -> Result(a, b)
Merges a nested Result
into a single layer.
Examples
flatten(Ok(Ok(1)))
// -> Ok(1)
flatten(Ok(Error("")))
// -> Error("")
flatten(Error(Nil))
// -> Error(Nil)
pub fn is_error(result: Result(a, b)) -> Bool
Checks whether the result is an Error
value.
Examples
is_error(Ok(1))
// -> False
is_error(Error(Nil))
// -> True
pub fn is_ok(result: Result(a, b)) -> Bool
Checks whether the result is an Ok
value.
Examples
is_ok(Ok(1))
// -> True
is_ok(Error(Nil))
// -> False
pub fn lazy_or(
first: Result(a, b),
second: fn() -> Result(a, b),
) -> Result(a, b)
Returns the first value if it is Ok
, otherwise evaluates the given function for a fallback value.
Examples
lazy_or(Ok(1), fn() { Ok(2) })
// -> Ok(1)
lazy_or(Ok(1), fn() { Error("Error 2") })
// -> Ok(1)
lazy_or(Error("Error 1"), fn() { Ok(2) })
// -> Ok(2)
lazy_or(Error("Error 1"), fn() { Error("Error 2") })
// -> Error("Error 2")
pub fn lazy_unwrap(
result: Result(a, b),
or default: fn() -> a,
) -> a
Extracts the Ok
value from a result, evaluating the default function if the result
is an Error
.
Examples
lazy_unwrap(Ok(1), fn() { 0 })
// -> 1
lazy_unwrap(Error(""), fn() { 0 })
// -> 0
pub fn map(
over result: Result(a, b),
with fun: fn(a) -> c,
) -> Result(c, b)
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
map(over: Ok(1), with: fn(x) { x + 1 })
// -> Ok(2)
map(over: Error(1), with: fn(x) { x + 1 })
// -> Error(1)
pub fn map_error(
over result: Result(a, b),
with fun: fn(b) -> c,
) -> Result(a, c)
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
map_error(over: Error(1), with: fn(x) { x + 1 })
// -> Error(2)
map_error(over: Ok(1), with: fn(x) { x + 1 })
// -> Ok(1)
pub fn nil_error(result: Result(a, b)) -> Result(a, Nil)
Transforms any error into Error(Nil)
.
Examples
nil_error(Error(1))
// -> Error(Nil)
nil_error(Ok(1))
// -> Ok(1)
pub fn or(
first: Result(a, b),
second: Result(a, b),
) -> Result(a, b)
Returns the first value if it is Ok
, otherwise returns the second value.
Examples
or(Ok(1), Ok(2))
// -> Ok(1)
or(Ok(1), Error("Error 2"))
// -> Ok(1)
or(Error("Error 1"), Ok(2))
// -> Ok(2)
or(Error("Error 1"), Error("Error 2"))
// -> Error("Error 2")
pub fn partition(
results: List(Result(a, b)),
) -> #(List(a), List(b))
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
partition([Ok(1), Error("a"), Error("b"), Ok(2)])
// -> #([2, 1], ["b", "a"])
pub fn replace(result: Result(a, b), value: c) -> Result(c, b)
Replace the value within a result
Examples
replace(Ok(1), Nil)
// -> Ok(Nil)
replace(Error(1), Nil)
// -> Error(1)
pub fn replace_error(
result: Result(a, b),
error: c,
) -> Result(a, c)
Replace the error within a result
Examples
replace_error(Error(1), Nil)
// -> Error(Nil)
replace_error(Ok(1), Nil)
// -> Ok(1)
pub fn then(
result: Result(a, b),
apply fun: fn(a) -> Result(c, b),
) -> Result(c, b)
An alias for try
. See the documentation for that function for more information.
pub fn try(
result: Result(a, b),
apply fun: fn(a) -> Result(c, b),
) -> Result(c, b)
“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
try(Ok(1), fn(x) { Ok(x + 1) })
// -> Ok(2)
try(Ok(1), fn(x) { Ok(#("a", x)) })
// -> Ok(#("a", 1))
try(Ok(1), fn(_) { Error("Oh no") })
// -> Error("Oh no")
try(Error(Nil), fn(x) { Ok(x + 1) })
// -> Error(Nil)
pub fn try_recover(
result: Result(a, b),
with fun: fn(b) -> Result(a, c),
) -> Result(a, c)
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.
Examples
Ok(1) |> try_recover(with: fn(_) { Error("failed to recover") })
// -> Ok(1)
Error(1) |> try_recover(with: fn(error) { Ok(error + 1) })
// -> Ok(2)
Error(1) |> try_recover(with: fn(error) { Error("failed to recover") })
// -> Error("failed to recover")
pub fn unwrap(result: Result(a, b), or default: a) -> a
Extracts the Ok
value from a result, returning a default value if the result
is an Error
.
Examples
unwrap(Ok(1), 0)
// -> 1
unwrap(Error(""), 0)
// -> 0
pub fn unwrap_both(result: Result(a, a)) -> a
Extracts the inner value from a result. Both the value and error must be of the same type.
Examples
unwrap_both(Error(1))
// -> 1
unwrap_both(Ok(2))
// -> 2
pub fn unwrap_error(result: Result(a, b), or default: b) -> b
Extracts the Error
value from a result, returning a default value if the result
is an Ok
.
Examples
unwrap_error(Error(1), 0)
// -> 1
unwrap_error(Ok(""), 0)
// -> 0