Skip to main content

Result

Reference for mo:core/Result in the core library.

Result is the conventional { #ok; #err } shape for fallible APIs. Its combinators preserve variant shape in contracts; as with Option, callbacks need known summaries when used in verified higher-order paths.

Import​

mo:core/Result

Status​

  • Runtime module

Public API​

Types​

  • Result

Functions​

equal<Ok, Err>(result1 : Result<Ok, Err>, result2 : Result<Ok, Err>, equalOk : (Ok, Ok) -> Bool, equalErr : (Err, Err) -> Bool) : Bool​

Compares the supplied values and relates the result to the underlying order.

Contract

ensures (switch (result1, result2) {
case (#ok(_), #err(_)) { result == false };
case (#err(_), #ok(_)) { result == false };
case _ { true }
});

Use when: code or contracts need an explicit comparison helper instead of an operator.

compare<Ok, Err>(result1 : Result<Ok, Err>, result2 : Result<Ok, Err>, compareOk : (Ok, Ok) -> Types.Order, compareErr : (Err, Err) -> Types.Order) : Types.Order​

Compares the supplied values and relates the result to the underlying order.

Contract

ensures (switch (result1, result2) {
case (#ok(_), #err(_)) { result == #greater };
case (#err(_), #ok(_)) { result == #less };
case _ { true }
});

Use when: code or contracts need an explicit comparison helper instead of an operator.

chain<Ok1, Ok2, Err>(res : Result<Ok1, Err>, f : Ok1 -> Result<Ok2, Err>) : Result<Ok2, Err>​

Sequences a fallible or optional computation without adding an extra nesting layer.

Contract

ensures (switch res { case (#err(err)) { result == #err(err) }; case _ { true } });

Use when: code or specifications need this operation with the documented contract.

flatten<Ok, Err>(res : Result<Result<Ok, Err>, Err>) : Result<Ok, Err>​

Removes one layer of nested Option or Result structure.

Contract

ensures result == (switch res {
case (#ok(ok)) { ok };
case (#err(err)) { #err(err) }
});

Use when: code or specifications need this operation with the documented contract.

mapOk<Ok1, Ok2, Err>(res : Result<Ok1, Err>, f : Ok1 -> Ok2) : Result<Ok2, Err>​

Transforms the contained values with the supplied function while preserving the documented shape.

Contract

ensures (switch res {
case (#err(err)) { result == #err(err) };
case (#ok(_)) { switch result { case (#ok(_)) { true }; case _ { false } } }
});
ensures (switch result {
case (#err(err)) { res == #err(err) };
case _ { true }
});

Use when: code or specifications need this operation with the documented contract.

mapErr<Ok, Err1, Err2>(res : Result<Ok, Err1>, f : Err1 -> Err2) : Result<Ok, Err2>​

Transforms the contained values with the supplied function while preserving the documented shape.

Contract

ensures (switch res {
case (#ok(ok)) { result == #ok(ok) };
case (#err(_)) { switch result { case (#err(_)) { true }; case _ { false } } }
});
ensures (switch result {
case (#ok(ok)) { res == #ok(ok) };
case _ { true }
});

Use when: code or specifications need this operation with the documented contract.

fromOption<Ok, Err>(x : ?Ok, err : Err) : Result<Ok, Err>​

Converts between the module type and the target representation.

Contract

ensures result == (switch x { case null { #err(err) }; case (?value) { #ok(value) } });

Use when: crossing between this module's value and another representation.

toOption<Ok, Err>(res : Result<Ok, Err>) : ?Ok​

Converts between the module type and the target representation.

Contract

ensures result == (switch res { case (#ok(value)) { ?value }; case (#err(_)) { null } });

Use when: crossing between this module's value and another representation.

forOk<Ok, Err>(res : Result<Ok, Err>, f : Ok -> ())​

Runs the supplied callback only for the matching contained value.

Use when: code or specifications need this operation with the documented contract.

forErr<Ok, Err>(res : Result<Ok, Err>, f : Err -> ())​

Runs the supplied callback only for the matching contained value.

Use when: code or specifications need this operation with the documented contract.

isOk<Ok, Err>(res : Result<Ok, Err>) : Bool​

Checks the predicate described by the return contract.

Contract

ensures result == (switch res { case (#ok(_)) { true }; case (#err(_)) { false } });

Use when: a branch condition or contract needs this predicate as a named fact.

isErr<Ok, Err>(res : Result<Ok, Err>) : Bool​

Checks the predicate described by the return contract.

Contract

ensures result == (switch res { case (#err(_)) { true }; case (#ok(_)) { false } });

Use when: a branch condition or contract needs this predicate as a named fact.

assertOk<Ok, Err>(res : Result<Ok, Err>)​

Asserts that the result has the expected variant shape.

Contract

ensures isOk(res);

Use when: code or specifications need this operation with the documented contract.

assertErr<Ok, Err>(res : Result<Ok, Err>)​

Asserts that the result has the expected variant shape.

Contract

ensures isErr(res);

Use when: code or specifications need this operation with the documented contract.

fromUpper<Ok, Err>(upper : { #Ok : Ok; #Err : Err }) : Result<Ok, Err>​

Converts between the module type and the target representation.

Contract

ensures result == (switch upper { case (#Ok(ok)) { #ok(ok) }; case (#Err(err)) { #err(err) } });

Use when: crossing between this module's value and another representation.

toUpper<Ok, Err>(res : Result<Ok, Err>) : { #Ok : Ok; #Err : Err }​

Converts between the module type and the target representation.

Contract

ensures result == (switch res { case (#ok(ok)) { #Ok(ok) }; case (#err(err)) { #Err(err) } });

Use when: crossing between this module's value and another representation.

Summary​

  • Runtime module under mo:core/Result.
  • Exposes 16 public functions.