Result ok err : [ Ok ok, Err err ]

The result of an operation that could fail: either the operation went okay, or else there was an error of some sort.

is_ok : Result ok err -> Bool

Returns Bool.true if the result indicates a success, else returns Bool.false.

Result.is_ok(Ok(5))

is_err : Result ok err -> Bool

Returns Bool.true if the result indicates a failure, else returns Bool.false.

Result.is_err(Err("uh oh"))

with_default : Result ok err, ok -> ok

If the result is Ok, returns the value it holds. Otherwise, returns the given default value.

Note: This function should be used sparingly, because it hides that an error happened, which will make debugging harder. Prefer using ? to forward errors or handle them explicitly with when.

Result.with_default(Err("uh oh"), 42) # = 42

Result.with_default(Ok(7), 42) # = 7

map_ok : Result a err, (a -> b) -> Result b err

If the result is Ok, transforms the value it holds by running a conversion function on it. Then returns a new Ok holding the transformed value. If the result is Err, this has no effect. Use map_err to transform an Err.

Result.map_ok(Ok(12), Num.neg) # = Ok(-12)

Result.map_ok(Err("yipes!"), Num.neg) # = Err("yipes!")

Functions like map are common in Roc; see for example List.map, Set.map, and Dict.map.

map_err : Result ok a, (a -> b) -> Result ok b

If the result is Err, transforms the value it holds by running a conversion function on it. Then returns a new Err holding the transformed value. If the result is Ok, this has no effect. Use map_ok to transform an Ok.

List.last([]) |> Result.map_err(|_| ProvidedListIsEmpty) # = Err(ProvidedListIsEmpty)

List.last([4]) |> Result.map_err(|_| ProvidedListIsEmpty) # = Ok(4)

on_err : Result a err, (err -> Result a other_err) -> Result a other_err

If the result is Err, transforms the entire result by running a conversion function on the value the Err holds. Then returns that new result. If the result is Ok, this has no effect. Use ? or try to transform an Ok.

Result.on_err(Ok(10), Str.to_u64) # = Ok(10)

Result.on_err(Err("42"), Str.to_u64) # = Ok(42)

Result.on_err(Err("string"), Str.to_u64) # = Err(InvalidNumStr)

on_err! : Result a err, (err => Result a other_err) => Result a other_err

Like on_err, but it allows the transformation function to produce effects.

Result.on_err(
    Err("missing user"),
    |msg|
        Stdout.line!("ERROR: ${msg}")?
        Err(msg)
)

map_both : Result ok1 err1, (ok1 -> ok2), (err1 -> err2) -> Result ok2 err2

Maps both the Ok and Err values of a Result to new values.

map2 : Result a err, Result b err, (a, b -> c) -> Result c err

Maps the Ok values of two Results to a new value using a given transformation, or returns the first Err value encountered.

try : Result a err, (a -> Result b err) -> Result b err

If the result is Ok, transforms the entire result by running a conversion function on the value the Ok holds. Then returns that new result. If the result is Err, this has no effect.

We recommend using ? instead of try, it makes the code easier to read.

Result.try(Ok(-1), (|num| if num < 0 then Err("negative!") else Ok(-num))) # = Err("negative!")

Result.try(Err("yipes!"), (|num| -> if num < 0 then Err("negative!") else Ok(-num))) # = Err("yipes!")