fp.mojo v1.0.0
Search /
API reference

fp.data

fp.data provides two sum types: Result for success or failure, and ControlFlow for continuing or stopping a fold. Use attempt and raise_on_err to convert between stored failures and native exceptions. The results tutorial introduces these operations with a complete program.

Typed results, early termination and bridges between raised and stored errors.

Result[T, E] holds a success value Ok[T] or a stored failure Err[E]; ControlFlow[B, C] holds Break[B] or Continue[C]. Both are stored in place and matched by fp.match. Mojo's typed native errors are efficient; Result is for failures that must be stored, collected or passed along as values, not a replacement for raises.

The bridges: attempt and attempt_once turn a raising call into a Result, raise_on_err turns it back, each with the original error type, and collect_results collects a source of Results into one.

Summary

Name Kind Summary
attempt function Call function once and capture its outcome: Ok(result), or Err(error) for its declared error.
attempt_once function Consume a OnceThunk, call it once and capture its outcome.
collect_results function Collect the success values of a source of Results, or return the first Err.
raise_on_err function Consume a Result and return its value, or raise its stored error.
Break struct Stop a fold_until with a value.
Continue struct Continue a fold_until with the next accumulator.
Err struct A failed Result: the error, stored as data rather than raised.
Ok struct A successful Result: the value.
Result struct A success value Ok[T] or a stored failure Err[E], held in place in a native Variant.
ControlFlow alias Break[B] or Continue[C], stored in place: the outcome of a fold_until step.

Functions

attempt

Source: fp/data/_result.mojo

def attempt[T, //, F: def() -> T](function: F) -> Result[T, Never]

Call function once and capture its outcome: Ok(result), or Err(error) for its declared error.

Overloads take zero, one or two positional arguments with their native read, var or mut conventions, and a native keyword pack var **kwargs: K after them (homogeneous values, or a StringDict[K] expanded with **options^). Pass consumed arguments with ^. Changes made through a mut argument before a failure remain visible. Every declared positional parameter must be supplied, including defaulted ones; other call shapes are written as a closure passed to the zero-argument form.

The function is borrowed and reusable. A returned Result is ordinary success data, and a declared StopIteration is captured like any other error; process aborts are never caught.

Parameters

  • T (Movable & Deinitable, inferred): The result type.
  • F (def() -> T): The function's type: a plain function or a closure.

Arguments

  • function (F): The function, borrowed; it runs once.

Returns

Result[T, Never]: Ok(result); a pure function never produces Err, so the error type is Never.

51 more overloads

Call once and retain the exact native error as an Err payload.

def attempt[T, E, //, F: def() raises E -> T](function: F) -> Result[T, E]

Capture a pure call once; its error channel is Never.

def attempt[A, T, //, F: def(A) -> T](
    function: F,
    first: A,
) -> Result[T, Never] where not conforms_to(A, TrivialRegisterPassable)

Invoke once with native argument conventions and retain the exact typed error.

def attempt[A, T, E, //, F: def(A) raises E -> T](
    function: F,
    first: A,
) -> Result[T, E] where not conforms_to(A, TrivialRegisterPassable)

Capture a pure call once; its error channel is Never.

def attempt[A, T, //, F: def(var A) -> T](
    function: F,
    var first: A,
) -> Result[T, Never]

Invoke once with native argument conventions and retain the exact typed error.

def attempt[A, T, E, //, F: def(var A) raises E -> T](
    function: F,
    var first: A,
) -> Result[T, E]

Capture a pure call once; its error channel is Never.

def attempt[A, B, T, //, F: def(A, B) -> T](
    function: F,
    first: A,
    second: B,
) -> Result[T, Never] where not conforms_to(A, TrivialRegisterPassable) and not conforms_to(B, TrivialRegisterPassable)

Invoke once with native argument conventions and retain the exact typed error.

def attempt[A, B, T, E, //, F: def(A, B) raises E -> T](
    function: F,
    first: A,
    second: B,
) -> Result[T, E] where not conforms_to(A, TrivialRegisterPassable) and not conforms_to(B, TrivialRegisterPassable)

Capture a pure call once; its error channel is Never.

def attempt[A, B, T, //, F: def(var A, B) -> T](
    function: F,
    var first: A,
    second: B,
) -> Result[T, Never] where not conforms_to(B, TrivialRegisterPassable)

Invoke once with native argument conventions and retain the exact typed error.

def attempt[A, B, T, E, //, F: def(var A, B) raises E -> T](
    function: F,
    var first: A,
    second: B,
) -> Result[T, E] where not conforms_to(B, TrivialRegisterPassable)

Capture a pure call once; its error channel is Never.

def attempt[A, B, T, //, F: def(A, var B) -> T](
    function: F,
    first: A,
    var second: B,
) -> Result[T, Never] where not conforms_to(A, TrivialRegisterPassable)

Invoke once with native argument conventions and retain the exact typed error.

def attempt[A, B, T, E, //, F: def(A, var B) raises E -> T](
    function: F,
    first: A,
    var second: B,
) -> Result[T, E] where not conforms_to(A, TrivialRegisterPassable)

Capture a pure call once; its error channel is Never.

def attempt[A, B, T, //, F: def(var A, var B) -> T](
    function: F,
    var first: A,
    var second: B,
) -> Result[T, Never]

Invoke once with native argument conventions and retain the exact typed error.

def attempt[A, B, T, E, //, F: def(var A, var B) raises E -> T](
    function: F,
    var first: A,
    var second: B,
) -> Result[T, E]

Forward native keyword values once; preserve the selected native error channel.

def attempt[K, T, //, F: def(var **kwargs: K) -> T](
    function: F,
    /,
    var **values: K,
) -> Result[T, Never]

Forward native keyword values once; preserve the selected native error channel.

def attempt[K, T, E, //, F: def(var **kwargs: K) raises E -> T](
    function: F,
    /,
    var **values: K,
) -> Result[T, E]

Forward native keyword values once; preserve the selected native error channel.

def attempt[A, K, T, //, F: def(A, /, var **kwargs: K) -> T](
    function: F,
    first: A,
    /,
    var **values: K,
) -> Result[T, Never] where not conforms_to(A, TrivialRegisterPassable)

Forward native keyword values once; preserve the selected native error channel.

def attempt[A, K, T, E, //, F: def(A, /, var **kwargs: K) raises E -> T](
    function: F,
    first: A,
    /,
    var **values: K,
) -> Result[T, E] where not conforms_to(A, TrivialRegisterPassable)

Forward native keyword values once; preserve the selected native error channel.

def attempt[A, K, T, //, F: def(var A, /, var **kwargs: K) -> T](
    function: F,
    var first: A,
    /,
    var **values: K,
) -> Result[T, Never]

Forward native keyword values once; preserve the selected native error channel.

def attempt[A, K, T, E, //, F: def(var A, /, var **kwargs: K) raises E -> T](
    function: F,
    var first: A,
    /,
    var **values: K,
) -> Result[T, E]

Forward native keyword values once; preserve the selected native error channel.

def attempt[A, B, K, T, //, F: def(A, B, /, var **kwargs: K) -> T](
    function: F,
    first: A,
    second: B,
    /,
    var **values: K,
) -> Result[T, Never] where not conforms_to(A, TrivialRegisterPassable) and not conforms_to(B, TrivialRegisterPassable)

Forward native keyword values once; preserve the selected native error channel.

def attempt[A, B, K, T, E, //, F: def(A, B, /, var **kwargs: K) raises E -> T](
    function: F,
    first: A,
    second: B,
    /,
    var **values: K,
) -> Result[T, E] where not conforms_to(A, TrivialRegisterPassable) and not conforms_to(B, TrivialRegisterPassable)

Forward native keyword values once; preserve the selected native error channel.

def attempt[A, B, K, T, //, F: def(var A, B, /, var **kwargs: K) -> T](
    function: F,
    var first: A,
    second: B,
    /,
    var **values: K,
) -> Result[T, Never] where not conforms_to(B, TrivialRegisterPassable)

Forward native keyword values once; preserve the selected native error channel.

def attempt[
    A, B, K, T, E, //, F: def(var A, B, /, var **kwargs: K) raises E -> T,
](
    function: F,
    var first: A,
    second: B,
    /,
    var **values: K,
) -> Result[T, E] where not conforms_to(B, TrivialRegisterPassable)

Forward native keyword values once; preserve the selected native error channel.

def attempt[A, B, K, T, //, F: def(A, var B, /, var **kwargs: K) -> T](
    function: F,
    first: A,
    var second: B,
    /,
    var **values: K,
) -> Result[T, Never] where not conforms_to(A, TrivialRegisterPassable)

Forward native keyword values once; preserve the selected native error channel.

def attempt[
    A, B, K, T, E, //, F: def(A, var B, /, var **kwargs: K) raises E -> T,
](
    function: F,
    first: A,
    var second: B,
    /,
    var **values: K,
) -> Result[T, E] where not conforms_to(A, TrivialRegisterPassable)

Forward native keyword values once; preserve the selected native error channel.

def attempt[A, B, K, T, //, F: def(var A, var B, /, var **kwargs: K) -> T](
    function: F,
    var first: A,
    var second: B,
    /,
    var **values: K,
) -> Result[T, Never]

Forward native keyword values once; preserve the selected native error channel.

def attempt[
    A, B, K, T, E, //, F: def(var A, var B, /, var **kwargs: K) raises E -> T,
](
    function: F,
    var first: A,
    var second: B,
    /,
    var **values: K,
) -> Result[T, E]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, T, //, F: def(mut A) -> T](
    function: F,
    mut first: A,
) -> Result[T, Never]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, T, E, //, F: def(mut A) raises E -> T](
    function: F,
    mut first: A,
) -> Result[T, E]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, T, //, F: def(A, mut B) -> T](
    function: F,
    first: A,
    mut second: B,
) -> Result[T, Never] where not conforms_to(A, TrivialRegisterPassable)

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, T, E, //, F: def(A, mut B) raises E -> T](
    function: F,
    first: A,
    mut second: B,
) -> Result[T, E] where not conforms_to(A, TrivialRegisterPassable)

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, T, //, F: def(var A, mut B) -> T](
    function: F,
    var first: A,
    mut second: B,
) -> Result[T, Never]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, T, E, //, F: def(var A, mut B) raises E -> T](
    function: F,
    var first: A,
    mut second: B,
) -> Result[T, E]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, T, //, F: def(mut A, B) -> T](
    function: F,
    mut first: A,
    second: B,
) -> Result[T, Never] where not conforms_to(B, TrivialRegisterPassable)

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, T, E, //, F: def(mut A, B) raises E -> T](
    function: F,
    mut first: A,
    second: B,
) -> Result[T, E] where not conforms_to(B, TrivialRegisterPassable)

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, T, //, F: def(mut A, var B) -> T](
    function: F,
    mut first: A,
    var second: B,
) -> Result[T, Never]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, T, E, //, F: def(mut A, var B) raises E -> T](
    function: F,
    mut first: A,
    var second: B,
) -> Result[T, E]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, T, //, F: def(mut A, mut B) -> T](
    function: F,
    mut first: A,
    mut second: B,
) -> Result[T, Never]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, T, E, //, F: def(mut A, mut B) raises E -> T](
    function: F,
    mut first: A,
    mut second: B,
) -> Result[T, E]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, K, T, //, F: def(mut A, /, var **kwargs: K) -> T](
    function: F,
    mut first: A,
    /,
    var **values: K,
) -> Result[T, Never]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, K, T, E, //, F: def(mut A, /, var **kwargs: K) raises E -> T](
    function: F,
    mut first: A,
    /,
    var **values: K,
) -> Result[T, E]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, K, T, //, F: def(A, mut B, /, var **kwargs: K) -> T](
    function: F,
    first: A,
    mut second: B,
    /,
    var **values: K,
) -> Result[T, Never] where not conforms_to(A, TrivialRegisterPassable)

Forward once, preserving caller mutation and the exact native error channel.

def attempt[
    A, B, K, T, E, //, F: def(A, mut B, /, var **kwargs: K) raises E -> T,
](
    function: F,
    first: A,
    mut second: B,
    /,
    var **values: K,
) -> Result[T, E] where not conforms_to(A, TrivialRegisterPassable)

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, K, T, //, F: def(var A, mut B, /, var **kwargs: K) -> T](
    function: F,
    var first: A,
    mut second: B,
    /,
    var **values: K,
) -> Result[T, Never]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[
    A, B, K, T, E, //, F: def(var A, mut B, /, var **kwargs: K) raises E -> T,
](
    function: F,
    var first: A,
    mut second: B,
    /,
    var **values: K,
) -> Result[T, E]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, K, T, //, F: def(mut A, B, /, var **kwargs: K) -> T](
    function: F,
    mut first: A,
    second: B,
    /,
    var **values: K,
) -> Result[T, Never] where not conforms_to(B, TrivialRegisterPassable)

Forward once, preserving caller mutation and the exact native error channel.

def attempt[
    A, B, K, T, E, //, F: def(mut A, B, /, var **kwargs: K) raises E -> T,
](
    function: F,
    mut first: A,
    second: B,
    /,
    var **values: K,
) -> Result[T, E] where not conforms_to(B, TrivialRegisterPassable)

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, K, T, //, F: def(mut A, var B, /, var **kwargs: K) -> T](
    function: F,
    mut first: A,
    var second: B,
    /,
    var **values: K,
) -> Result[T, Never]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[
    A, B, K, T, E, //, F: def(mut A, var B, /, var **kwargs: K) raises E -> T,
](
    function: F,
    mut first: A,
    var second: B,
    /,
    var **values: K,
) -> Result[T, E]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[A, B, K, T, //, F: def(mut A, mut B, /, var **kwargs: K) -> T](
    function: F,
    mut first: A,
    mut second: B,
    /,
    var **values: K,
) -> Result[T, Never]

Forward once, preserving caller mutation and the exact native error channel.

def attempt[
    A, B, K, T, E, //, F: def(mut A, mut B, /, var **kwargs: K) raises E -> T,
](
    function: F,
    mut first: A,
    mut second: B,
    /,
    var **values: K,
) -> Result[T, E]

attempt_once

Source: fp/data/_result.mojo

def attempt_once[F: OnceThunk](var function: F) -> Result[F.Out, F.Error]

Consume a OnceThunk, call it once and capture its outcome.

Receiver state, results and errors may be move-only; unused state is destroyed on every path. References in the result or error must belong to owners that outlive the thunk.

Parameters

  • F (OnceThunk): The thunk's type.

Arguments

  • function (var F): The thunk, consumed.

Returns

Result[F.Out, F.Error]: Ok(result), or Err(error) for its declared error.

collect_results

Source: fp/data/result.mojo

def collect_results[T, E, I: Iterator](
    var source: I,
) -> Result[List[T], E] where I.Element == Result[T, E]

Collect the success values of a source of Results, or return the first Err.

Pulling stops at the first Err; the collected prefix and the rest of an owned source are destroyed. It shares the collection loop of the algebra's sequence and traverse.

Parameters

  • T (Movable & Deinitable): The success type.
  • E (Movable & Deinitable): The stored error type.
  • I (Iterator): The source's type: a native iterator of Result[T, E].

Arguments

  • source (var I): The source, consumed.

Returns

Result[List[T], E]: Ok of a List of the values in order, or the first Err; Ok of an empty list for an empty source.

raise_on_err

Source: fp/data/_result.mojo

def raise_on_err[T, E](var result: Result[T, E]) raises E -> T

Consume a Result and return its value, or raise its stored error.

Parameters

  • T (Movable & Deinitable): The success type.
  • E (Movable & Deinitable): The stored error type.

Arguments

  • result (var Result[T, E]): The Result, consumed.

Returns

T: The success value.

Raises

E: The stored error, with its original type.

Structs

Break

Source: fp/data/control.mojo

struct Break[T](Movable, Copyable where conforms_to(T, Copyable))

Stop a fold_until with a value.

Parameters

  • T (Movable & Deinitable): The value's type.

Implements

Copyable

Fields

  • value (T): The value.

Break.into_payload

def into_payload(deinit self) -> T

Consume the constructor and return its value.

Returns

T: The value, moved out.

Continue

Source: fp/data/control.mojo

struct Continue[T](Movable, Copyable where conforms_to(T, Copyable))

Continue a fold_until with the next accumulator.

It stays distinct from Break even when the two payload types are equal.

Parameters

  • T (Movable & Deinitable): The accumulator's type.

Implements

Copyable

Fields

  • value (T): The accumulator.

Continue.into_payload

def into_payload(deinit self) -> T

Consume the constructor and return its value.

Returns

T: The value, moved out.

Err

Source: fp/data/_result.mojo

struct Err[E](Movable, Copyable where conforms_to(E, Copyable))

A failed Result: the error, stored as data rather than raised.

Parameters

  • E (Movable & Deinitable): The error's type.

Implements

Copyable

Fields

  • value (E): The error.

Err.into_payload

def into_payload(deinit self) -> E

Consume the constructor and return its error.

Returns

E: The error, moved out.

Ok

Source: fp/data/_result.mojo

struct Ok[T](Movable, Copyable where conforms_to(T, Copyable))

A successful Result: the value.

It stays distinct from Err[T] even when the two payload types are equal.

Parameters

  • T (Movable & Deinitable): The value's type.

Implements

Copyable

Fields

  • value (T): The value.

Ok.into_payload

def into_payload(deinit self) -> T

Consume the constructor and return its value.

Returns

T: The value, moved out.

Result

Source: fp/data/_result.mojo

struct Result[T, E](
    _ResultType,
    _ChoiceType,
    Movable,
    Copyable where conforms_to(T, Copyable) and conforms_to(E, Copyable),
)

A success value Ok[T] or a stored failure Err[E], held in place in a native Variant.

Ok and Err convert to a Result wherever its type is known, as in return Ok(value); a payload must already have the exact type. fp.match matches a Result with clauses for Ok[T] and Err[E], which borrow the stored constructor. It is Copyable only when both payloads are, and adds constant tag work and no heap storage.

The transformations (map, flat_map, map_err, or_else) consume the Result, so they chain: parse(text).map(twice).flat_map(check). A callback never runs on the inactive case, which passes through unchanged. A native error a callback raises stays a native error: it never becomes the stored Err, even when the types coincide. Callbacks are plain functions, closures, or library values (Unary for the transformations and fold_owned, BorrowCallable for fold, and the consuming forms of fold_once and fold_owned_once). A generic wrapper names a raising callback's error with X=, as in value^.map[X=X](callback).

Parameters

  • T (Movable & Deinitable): The success value's type.
  • E (Movable & Deinitable): The stored error's type.

Implements

Copyable, _ChoiceType, _ResultType

Aliases

  • Value
  • Error
  • Of

Result.__init__ { #Result.init .api-name }

def __init__(out self, var value: Ok[T])

Store a success; an Ok converts to a Result wherever the Result type is known.

Arguments

  • value (var Ok[T]): The success, moved in.
1 more overload

An `Err` converts to a Result wherever the Result type is known.

def __init__(out self, var error: Err[E])

Result.flat_map

def flat_map[U, //, F: def(var T) -> Result[U, E]](
    deinit self,
    function: F,
) -> Result[U, E]

Continue with the Result the callback returns; an error passes through.

The callback's stored error type must be exactly E; combine different error types with map_err first.

Parameters

  • U (Movable & Deinitable, inferred): The new success type.
  • F (def(var T) -> Result[U, E]): The callback's type: a plain function or a closure returning Result[U, E].

Arguments

  • function (F): The callback, borrowed; it runs at most once.

Returns

Result[U, E]: function(value), or the original Err.

2 more overloads

Raising form of `flat_map`; the callback's error type is kept.

def flat_map[U, //, X, F: def(var T) raises X -> Result[U, E]](
    deinit self,
    function: F,
) raises X -> Result[U, E]

Continue with a library unary callback returning a Result.

def flat_map[F: UnaryContract & Movable & Deinitable](
    deinit self,
    var function: F,
) raises F.Error -> F.Out where F.Arg == T

Result.fold

def fold[R, //, F: def(T) -> R, G: def(E) -> R](self, on_ok: F, on_err: G) -> R

Call on_ok with the value or on_err with the error, borrowed, and return its result.

Exactly one callback runs. The two callbacks return the same type; when both raise, they raise one error type, or one of them nothing.

Parameters

  • R (Movable & Deinitable, inferred): The result type of both callbacks.
  • F (def(T) -> R): The success callback's type: a plain function or a closure.
  • G (def(E) -> R): The error callback's type: a plain function or a closure.

Arguments

  • on_ok (F): The callback for Ok, borrowed.
  • on_err (G): The callback for Err, borrowed.

Returns

R: The result of the callback that ran.

4 more overloads

Fold with a raising success callback.

def fold[R, X, //, F: def(T) raises X -> R, G: def(E) -> R](
    self,
    on_ok: F,
    on_err: G,
) raises X -> R

Fold with a raising error callback.

def fold[R, X, //, F: def(T) -> R, G: def(E) raises X -> R](
    self,
    on_ok: F,
    on_err: G,
) raises X -> R

Fold with two raising callbacks, which raise one error type.

def fold[R, X, Y, //, F: def(T) raises X -> R, G: def(E) raises Y -> R](
    self,
    on_ok: F,
    on_err: G,
) raises _ResultFailure[X, Y] -> R where X == Never or Y == Never or X == Y

Fold with two `BorrowCallable` handlers.

def fold[F: BorrowCallable, G: BorrowCallable](
    self,
    on_ok: F,
    on_err: G,
) raises _ResultFailure[F.Failure, G.Failure] -> F.Result where F.Payload == T and G.Payload == E and F.Result == G.Result and (F.Failure == Never or G.Failure == Never or F.Failure == G.Failure)

Result.fold_once

def fold_once[F: BorrowOnceCallable, G: BorrowOnceCallable](
    self,
    var on_ok: F,
    var on_err: G,
) raises _ResultFailure[F.Failure, G.Failure] -> F.Result where F.Payload == T and G.Payload == E and F.Result == G.Result and (F.Failure == Never or G.Failure == Never or F.Failure == G.Failure)

Fold with two consuming handlers: borrow the payload, and call only the selected handler.

Both handlers move in; the one that does not run is destroyed. No Copyable requirement is added. A result may refer to owners that outlive the call, never into a consumed handler.

Parameters

  • F (BorrowOnceCallable): The success handler's type, a BorrowOnceCallable taking T.
  • G (BorrowOnceCallable): The error handler's type, a BorrowOnceCallable taking E.

Arguments

  • on_ok (var F): The handler for Ok, consumed.
  • on_err (var G): The handler for Err, consumed.

Returns

F.Result: The result of the handler that ran.

Raises

The error of the handler that ran; both raise one error type, or one of them nothing.

Result.fold_owned

def fold_owned[R, //, F: def(var T) -> R, G: def(var E) -> R](
    deinit self,
    on_ok: F,
    on_err: G,
) -> R

Consume the Result and move its value or error into the matching callback.

Parameters

  • R (Movable & Deinitable, inferred): The result type of both callbacks.
  • F (def(var T) -> R): The success callback's type: a plain function or a closure.
  • G (def(var E) -> R): The error callback's type: a plain function or a closure.

Arguments

  • on_ok (F): The callback for Ok, borrowed; it receives the value.
  • on_err (G): The callback for Err, borrowed; it receives the error.

Returns

R: The result of the callback that ran.

4 more overloads

Consuming fold with a raising success callback.

def fold_owned[R, X, //, F: def(var T) raises X -> R, G: def(var E) -> R](
    deinit self,
    on_ok: F,
    on_err: G,
) raises X -> R

Consuming fold with a raising error callback.

def fold_owned[R, X, //, F: def(var T) -> R, G: def(var E) raises X -> R](
    deinit self,
    on_ok: F,
    on_err: G,
) raises X -> R

Consuming fold with two raising callbacks, which raise one error type.

def fold_owned[
    R, X, Y, //, F: def(var T) raises X -> R, G: def(var E) raises Y -> R,
](
    deinit self,
    on_ok: F,
    on_err: G,
) raises _ResultFailure[X, Y] -> R where X == Never or Y == Never or X == Y

Consuming fold with two library `Unary` handlers.

def fold_owned[F: Unary, G: Unary](
    deinit self,
    on_ok: F,
    on_err: G,
) raises _ResultFailure[F.Error, G.Error] -> F.Out where F.Arg == T and G.Arg == E and F.Out == G.Out and (F.Error == Never or G.Error == Never or F.Error == G.Error)

Result.fold_owned_once

def fold_owned_once[F: OnceUnary, G: OnceUnary](
    deinit self,
    var on_ok: F,
    var on_err: G,
) raises _ResultFailure[F.Error, G.Error] -> F.Out where F.Arg == T and G.Arg == E and F.Out == G.Out and (F.Error == Never or G.Error == Never or F.Error == G.Error)

Consume the Result and two consuming handlers, and move the payload into the selected one.

Parameters

  • F (OnceUnary): The success handler's type, a OnceUnary taking T.
  • G (OnceUnary): The error handler's type, a OnceUnary taking E.

Arguments

  • on_ok (var F): The handler for Ok, consumed.
  • on_err (var G): The handler for Err, consumed.

Returns

F.Out: The result of the handler that ran.

Raises

The error of the handler that ran; both raise one error type, or one of them nothing.

Result.is_err

def is_err(self) -> Bool

Whether the Result holds Err.

Returns

Bool: True for Err, False for Ok.

Result.is_ok

def is_ok(self) -> Bool

Whether the Result holds Ok.

Returns

Bool: True for Ok, False for Err.

Result.map

def map[U, //, F: def(var T) -> U](deinit self, function: F) -> Result[U, E]

Transform the success value; an error passes through and function does not run.

map keeps a returned Result as nested data; flat_map sequences.

Parameters

  • U (Movable & Deinitable, inferred): The new success type.
  • F (def(var T) -> U): The callback's type: a plain function or a closure.

Arguments

  • function (F): The callback, borrowed; it runs at most once.

Returns

Result[U, E]: Ok(function(value)), or the original Err.

2 more overloads

Raising form of `map`; the callback's error type is kept.

def map[U, //, X, F: def(var T) raises X -> U](
    deinit self,
    function: F,
) raises X -> Result[U, E]

Transform the success value with a library unary callback.

def map[F: UnaryContract & Movable & Deinitable](
    deinit self,
    var function: F,
) raises F.Error -> Result[F.Out, E] where F.Arg == T

Result.map_err

def map_err[U, //, F: def(var E) -> U](deinit self, function: F) -> Result[T, U]

Transform the stored error; a success passes through and function does not run.

Parameters

  • U (Movable & Deinitable, inferred): The new error type.
  • F (def(var E) -> U): The callback's type: a plain function or a closure.

Arguments

  • function (F): The callback, borrowed; it runs at most once.

Returns

Result[T, U]: Err(function(error)), or the original Ok.

2 more overloads

Raising form of `map_err`; the callback's error type is kept.

def map_err[U, //, X, F: def(var E) raises X -> U](
    deinit self,
    function: F,
) raises X -> Result[T, U]

Transform the error with a library unary callback.

def map_err[F: UnaryContract & Movable & Deinitable](
    deinit self,
    var function: F,
) raises F.Error -> Result[T, F.Out] where F.Arg == E

Result.or_else

def or_else[U, //, F: def(var E) -> Result[T, U]](
    deinit self,
    function: F,
) -> Result[T, U]

Recover from the stored error with the Result the callback returns; a success passes through.

The callback's success type must be exactly T.

Parameters

  • U (Movable & Deinitable, inferred): The new error type.
  • F (def(var E) -> Result[T, U]): The callback's type: a plain function or a closure returning Result[T, U].

Arguments

  • function (F): The callback, borrowed; it runs at most once.

Returns

Result[T, U]: function(error), or the original Ok.

2 more overloads

Raising form of `or_else`; the callback's error type is kept.

def or_else[U, //, X, F: def(var E) raises X -> Result[T, U]](
    deinit self,
    function: F,
) raises X -> Result[T, U]

Recover with a library unary callback returning a Result.

def or_else[F: UnaryContract & Movable & Deinitable](
    deinit self,
    var function: F,
) raises F.Error -> F.Out where F.Arg == E

Result.raise_on_err

def raise_on_err(deinit self) raises E -> T

Consume the Result and return its value, or raise its stored error.

Returns

T: The success value, moved out.

Raises

E: The stored error, with its original type.

Aliases

ControlFlow

Source: fp/data/control.mojo

comptime ControlFlow[B, C] = Choice[_ControlCases[B, C]]

Break[B] or Continue[C], stored in place: the outcome of a fold_until step.

A Choice of the two constructors: a step returns Break(value) or Continue(value), and the outcome is read with isa, indexing, the consuming unwrap, or fp.match.

Parameters

  • B (Movable & Deinitable): The type a fold stops with.
  • C (Movable & Deinitable): The accumulator type.

Consume handlers in a transformation and a fold

result_once.mojo Download
"""Move a formatter into one Result transformation and consume the final handler."""
from fp.callables import OnceUnary
from fp.data import Result, Ok


@fieldwise_init
struct Format(OnceUnary):
    var prefix: String
    comptime Arg = Int
    comptime Out = String
    def call_once(deinit self, var number: Int) -> String:
        self.prefix += String(number)
        return self.prefix^


@fieldwise_init
struct Show[T: Writable & Movable & Deinitable](OnceUnary):
    var label: String
    comptime Arg = Self.T
    comptime Out = Int
    def call_once(deinit self, var value: Self.T) -> Int:
        print(self.label, value)
        return 0


def main():
    var formatter = Format(String('value '))
    var value: Result[Int, Int] = Ok(12)
    var result = value^.map(formatter^)
    _ = result^.fold_owned_once(Show[String](String('used once:')), Show[Int](String('error:')))

Run from the repository root pixi run mojo run -I src docs/examples/result_once.mojo

Output

used once: value 12

Format is a OnceUnary that owns its prefix. value^.map(formatter^) moves it in and calls it once, turning Ok(12) into Ok("value 12"). fold_owned_once consumes both Show handlers and calls only the one for the Ok branch, which prints used once: value 12.

Capture the failure of a consuming thunk

attempt_once.mojo Download
"""Capture a native failure while consuming a thunk's owned state once."""
from fp.callables import OnceThunk
from fp.data import attempt_once


@fieldwise_init
struct Message(OnceThunk):
    var text: String
    comptime Out = String
    comptime Error = Int
    def call_once(deinit self) raises Int -> String:
        if self.text.byte_length() == 0:
            raise 7
        return self.text^


def show_message(var text: String) -> Int:
    print('message:', text)
    return 0


def show_error(var code: Int) -> Int:
    print('error:', code)
    return code


def main():
    var message = Message(String('used once'))
    var success = attempt_once(message^)
    _ = success^.fold_owned(show_message, show_error)
    var failure = attempt_once(Message(String()))
    _ = failure^.fold_owned(show_message, show_error)

Run from the repository root pixi run mojo run -I src docs/examples/attempt_once.mojo

Output

message: used once
error: 7

attempt_once(message^) consumes Message("used once"), calls it once, and returns Ok("used once"), which prints message: used once. An empty message raises 7, so attempt_once returns Err(7) with the thunk's declared Int error, and the program prints error: 7.