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.
Exports
Section titled “Exports”Types
type Infallible
Section titled “type Infallible”type Infallible
A type with no values. It is the error type of a Result that cannot
fail.
Infallible.to_string
Section titled “Infallible.to_string”impl Display for Infallible
fn to_string(value: Infallible) -> String
impl Display.to_string
Infallible.equal
Section titled “Infallible.equal”impl Equatable for Infallible
fn equal(a: Infallible, _b: Infallible) -> Bool
impl Equatable.equal
Infallible.hash
Section titled “Infallible.hash”impl Hashable for Infallible
fn hash(value: Infallible) -> Int
impl Hashable.hash
Infallible.inspect
Section titled “Infallible.inspect”impl Debug for Infallible
fn inspect(value: Infallible) -> String
impl Debug.inspect
enum Result
Section titled “enum Result”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"
Result.is_ok
Section titled “Result.is_ok”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"))
Result.is_err
Section titled “Result.is_err”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"))
Result.map
Section titled “Result.map”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")
Result.with_default
Section titled “Result.with_default”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
Result.flat_map
Section titled “Result.flat_map”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")
Result.map_err
Section titled “Result.map_err”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)
Result.to_maybe
Section titled “Result.to_maybe”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
Result.collect
Section titled “Result.collect”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)
Result.partition
Section titled “Result.partition”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])
Result.inspect
Section titled “Result.inspect”impl Debug for Result<T, E>
fn inspect<T, E>(value: Result<T, E>) -> String where T: Debug, E: Debug
impl Debug.inspect
Result.to_string
Section titled “Result.to_string”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
Result.equal
Section titled “Result.equal”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
Result.hash
Section titled “Result.hash”impl Hashable for Result<T, E>
fn hash<T, E>(value: Result<T, E>) -> Int where T: Hashable, E: Hashable
impl Hashable.hash