std.result

Construction and unpacking of Result(T, E), and field access for the Error carrier.

use std.result

Runtime Representation

Value	Representation
Result.ok(value)	enum variant, carrying value
Result.err(error)	enum variant, carrying error
Error	struct, with fields (code, message)

Error.code is a registered code from the E6xxx / E7xxx range per RFC-013 (a stable contract across versions), and Error.message is a human-readable description.

Function Summary

Function	Signature
is_ok	(T: Type, E: Type)(self: &Result(T, E)) -> Bool
is_err	(T: Type, E: Type)(self: &Result(T, E)) -> Bool
unwrap	(T: Type, E: Type)(self: &Result(T, E)) -> T
unwrap_or	(T: Type, E: Type)(self: &Result(T, E), default: T) -> T
ok	(T: Type, E: Type)(value: T) -> Result(T, E)
err	(T: Type, E: Type)(error: E) -> Result(T, E)
unwrap_err	(T: Type, E: Type)(self: &Result(T, E)) -> E
code	(self: &Error) -> String
message	(self: &Error) -> String

Construction

ok

ok: (T: Type, E: Type)(value: T) -> Result(T, E)

Wraps a success value.

The Ok value unpacked by ? must be re-wrapped before it can continue to propagate along a Result return type; ok is that wrapper.

use std.assert
use std.result

main: () -> Void = {
    r = result.ok(42)
    assert(result.is_ok(r))
}

err

err: (T: Type, E: Type)(error: E) -> Result(T, E)

Wraps an error value.

use std.assert
use std.result

main: () -> Void = {
    r = result.err("boom")
    assert(result.is_err(r))
}

Predicates

is_ok

is_ok: (T: Type, E: Type)(self: &Result(T, E)) -> Bool

Whether this is the success variant. Read-only borrow; self can be used repeatedly.

use std.assert
use std.result

main: () -> Void = {
    r = result.ok(1)
    assert(result.is_ok(r))
    assert(result.is_ok(r))      // reusable
}

is_err

is_err: (T: Type, E: Type)(self: &Result(T, E)) -> Bool

Whether this is the error variant. Read-only borrow.

use std.assert
use std.result

main: () -> Void = {
    r = result.err("e")
    assert(result.is_err(r))
}

Extracting Values

unwrap

unwrap: (T: Type, E: Type)(self: &Result(T, E)) -> T

Extracts the success value.

Returns: the value carried by the Ok variant. Error: calling on an Err value throws E6007, with the message including the original error code and description, in a form like unwrap called on Err value (E6010: parse_int: ...), so the failure reason is visible without first calling unwrap_err.

use std.assert
use std.result
use std.string

main: () -> Void = {
    r = string.parse_int("42")
    assert(result.unwrap(r) == 42)
}

unwrap_or

unwrap_or: (T: Type, E: Type)(self: &Result(T, E), default: T) -> T

Extracts the success value, or returns default on Err.

• default —— fallback value when Err

use std.assert
use std.result
use std.string

main: () -> Void = {
    good = string.parse_int("42")
    assert(result.unwrap_or(good, 0) == 42)

    bad = string.parse_int("abc")
    assert(result.unwrap_or(bad, 0) == 0)
}

unwrap_err

unwrap_err: (T: Type, E: Type)(self: &Result(T, E)) -> E

Extracts the error value.

Returns: the value carried by the Err variant. Error: calling on an Ok value throws E6007.

use std.assert
use std.result
use std.string

main: () -> Void = {
    r = string.parse_int("abc")
    e = result.unwrap_err(r)
    assert(result.is_err(r))
}

Error Fields

code

code: (self: &Error) -> String

Reads the error code string, such as "E6010".

The signature type is Error, but the runtime error carrier is a struct with fields (code, message). Call directly on an Error value.

use std.assert
use std.result
use std.string

main: () -> Void = {
    r = string.parse_int("abc")
    e = result.unwrap_err(r)
    assert(result.code(e) == "E6010")
}

message

message: (self: &Error) -> String

Reads the error description text.

use std.assert
use std.result
use std.string

main: () -> Void = {
    r = string.parse_int("abc")
    e = result.unwrap_err(r)
    assert(string.len(result.message(e)) > 0)
}

Related

• std.string —— parsing function that produces a Result
• Error code reference —— runtime error value codes such as E6010 / E6011