Skip to content

std::results

A Result<T, E> is the outcome of something that can fail: Ok(value) or Err(error). Result, Ok and Err are in the prelude, so a program writes them without an import.

Test a Result with is_ok and is_err. Change the value with map and flat_map, and the error with map_err. Take the value out with with_default. Drop the error with to_maybe. collect and partition work over many results at once. Infallible is the error type of a Result that cannot fail.

A Result renders, in Display and in Debug, as Ok(...) or Err(...) around the rendered value, never as the bare value.

Import with import std::results.

type Infallible

A type with no values. It is the error type of a Result that cannot fail.

impl Display for Infallible

fn to_string(value: Infallible) -> String

impl Display.to_string

impl Equatable for Infallible

fn equal(a: Infallible, _b: Infallible) -> Bool

impl Equatable.equal

impl Hashable for Infallible

fn hash(value: Infallible) -> Int

impl Hashable.hash

impl Debug for Infallible

fn inspect(value: Infallible) -> String

impl Debug.inspect

enum Result<T, E>
    Ok T
    Err E
end

A value that is either a success (Ok) or a failure (Err).

ok: Result<Int, String> = Result.Ok(1)
failed: Result<Int, String> = Result.Err("no")
assert "${ok}" == "Ok(1)"
assert "${failed}" == "Err(no)"

parse = fn s: String ->
    if s == "" then
        Result.Err("empty")
    else
        Result.Ok(s)
    end
end

value = case parse("hi")
    .Ok(v)  -> v
    .Err(_) -> "?"
end

assert value == "hi"
fn is_ok<T, E>(result: Result<T, E>) -> Bool

type function on Result

Returns True when the value is Ok.

assert Result.is_ok(Result.Ok(3))
refute Result.is_ok(Result.Err("bad"))
fn is_err<T, E>(result: Result<T, E>) -> Bool

type function on Result

Returns True when the value is Err.

refute Result.is_err(Result.Ok(3))
assert Result.is_err(Result.Err("bad"))
fn map<T, E, U>(result: Result<T, E>, f: (T) -> U) -> Result<U, E>

type function on Result

Applies f to the Ok value. An Err stays as it is.

assert Result.map(Result.Ok(3), &(&1 * 2)) == Result.Ok(6)
assert Result.map(Result.Err("bad"), &(&1 * 2)) == Result.Err("bad")
fn with_default<T, E>(result: Result<T, E>, default: T) -> T

type function on Result

Returns the Ok value, or the default if Err.

assert Result.with_default(Result.Ok(5), 0) == 5
assert Result.with_default(Result.Err("bad"), 0) == 0
fn flat_map<T, E, U>(result: Result<T, E>, f: (T) -> Result<U, E>) -> Result<U, E>

type function on Result

Applies f, which returns a Result itself, to the Ok value and returns what f returns, not a Result of a Result. An Err stays as it is.

parse_int = fn s: String ->
    if s == "1" then
        Result.Ok(1)
    else
        Result.Err("nope")
    end
end

assert Result.flat_map(Result.Ok("1"), &parse_int(&1)) == Result.Ok(1)
assert Result.flat_map(Result.Ok("x"), &parse_int(&1)) == Result.Err("nope")
fn map_err<T, E, F>(result: Result<T, E>, f: (E) -> F) -> Result<T, F>

type function on Result

Applies f to the Err value. An Ok stays as it is.

assert Result.map_err(Result.Err("bad"), &("error: " + &1)) == Result.Err("error: bad")
assert Result.map_err(Result.Ok(3), &("error: " + &1)) == Result.Ok(3)
fn to_maybe<T, E>(result: Result<T, E>) -> Maybe<T>

type function on Result

Converts Result to Maybe. Err becomes None; the error value is discarded.

assert Result.to_maybe(Result.Ok(3)) == Some(3)
assert Result.to_maybe(Result.Err("bad")) == None
fn collect<T, E>(results: Iter<Result<T, E>>) -> Result<List<T>, E>

type function on Result

Returns Ok of every value in order when every result is Ok, and otherwise the first Err. It stops consuming the iterator at that Err.

import std::ranges.Range

assert Result.collect([Result.Ok(1), Result.Ok(2)]) == Result.Ok([1, 2])
assert Result.collect([Result.Ok(1), Result.Err("a"), Result.Err("b")]) == Result.Err("a")
none: List<Result<Int, String>> = []
assert Result.collect(none) == Result.Ok([])

checked =
    [3, 1, 2]
    |> Iter.map(fn n ->
        if n > 0 then Result.Ok(n * 10) else Result.Err(n)
    end)
    |> Result.collect()

assert checked == Result.Ok([30, 10, 20])

// On an endless source, collect stops reading at the first Err.
stopped =
    Range.naturals()
    |> Iter.map(fn n -> if n < 3 then Result.Ok(n) else Result.Err(n))
    |> Result.collect()

assert stopped == Result.Err(3)
fn partition<T, E>(results: Iter<Result<T, E>>) -> (List<T>, List<E>)

type function on Result

Splits results into every Ok value and every Err value, each list in input order. It consumes the whole iterator.

mixed = [Result.Ok(1), Result.Err("a"), Result.Ok(2), Result.Err("b")]
assert Result.partition(mixed) == ([1, 2], ["a", "b"])
oks: List<Result<Int, String>> = [Result.Ok(1), Result.Ok(2)]
(all_oks, no_errs) = Result.partition(oks)
assert all_oks == [1, 2]
assert no_errs == []

none: List<Result<Int, String>> = []
(no_oks, still_no_errs) = Result.partition(none)
assert no_oks == []
assert still_no_errs == []

split =
    [1, -2, 3, -4]
    |> Iter.map(fn n -> if n > 0 then Result.Ok(n) else Result.Err(n))
    |> Result.partition()

assert split == ([1, 3], [-2, -4])

impl Debug for Result<T, E>

fn inspect<T, E>(value: Result<T, E>) -> String where T: Debug, E: Debug

impl Debug.inspect

impl Display for Result<T, E>

fn to_string<T, E>(value: Result<T, E>) -> String where T: Display, E: Display

impl Display.to_string

impl Equatable for Result<T, E>

fn equal<T, E>(a: Result<T, E>, b: Result<T, E>) -> Bool where T: Equatable, E: Equatable

impl Equatable.equal

impl Hashable for Result<T, E>

fn hash<T, E>(value: Result<T, E>) -> Int where T: Hashable, E: Hashable

impl Hashable.hash