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

## 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.

## 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]
``````