gleam/result · gleam_stdlib

all

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")

flatten

</>

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)

is_error

</>

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

is_ok

</>

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

lazy_or

</>

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.

If you need access to the initial error value, use result.try_recover.

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")

lazy_unwrap

</>

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

map

</>

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)

map_error

</>

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)

Examples

nil_error(Error(1))
// -> Error(Nil)

nil_error(Ok(1))
// -> Ok(1)

or

</>

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")

partition

</>

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"])

replace

</>

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)

replace_error

</>

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)

then

</>

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.

try

</>

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)

try_recover

</>

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.

If you do not need access to the initial error value, use result.lazy_or.

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")

unwrap

</>

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

unwrap_both

</>

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

unwrap_error

</>

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

values

</>

pub fn values(results: List(Result(a, b))) -> List(a)

Given a list of results, returns only the values inside Ok.

Examples

values([Ok(1), Error("a"), Ok(3)])
// -> [1, 3]