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

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.

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

nil_error

</>
``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)
``````

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

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

Updates a value held within the `Ok` 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 `Error` rather than `Ok` the function is not called and the result stays the same.

This function is the equivalent of calling `map` followed by `flatten`, and it is useful for chaining together multiple functions that may fail.

Examples

``````> then(Ok(1), fn(x) { Ok(x + 1) })
Ok(2)
``````
``````> then(Ok(1), fn(x) { Ok(#("a", x)) })
Ok(#("a", 1))
``````
``````> then(Ok(1), fn(_) { Error("Oh no") })
Error("Oh no")
``````
``````> then(Error(Nil), fn(x) { Ok(x + 1) })
Error(Nil)
``````

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), None, Ok(3)])
[1, 3]
``````