Value-or-error container that holds either a T (success) or an ErrorPayload (failure) in a single std::variant.
Use Result<T> instead of an exception when a failure must be
propagated across a boundary that cannot safely unwind C++ exceptions:
the pybind11 FFI surface (when noexcept is required), async callbacks
dispatched onto a worker queue, or any C ABI shim. Inside the engine
itself, ops typically throw a LucidError directly because the
stack-unwinding cost is acceptable and the typed exception carries
richer state.
Invariants
is_ok()⟺data_holds aT(variant index 0).is_err()⟺data_holds anErrorPayload(variant index 1).
Thread safety
Result<T> instances are not internally synchronised. Sharing a
single instance across threads requires external coordination.
See Also
Ok : Factory that wraps a value as a successful Result.
Err : Factory that builds an ErrorPayload,
implicitly convertible to Result<T> for any T.
Parameters
TtypenameConstructors
1Methods
5const ErrorPayload & error()Accesses the stored error payload (const lvalue overload).
Returns
const ErrorPayload&Const reference to the error descriptor. Lifetime is tied to *this.
Raises
:bad_variant_accessis_ok is true.Returns whether this result holds an error.
Returns
booltrue if the error arm is active, false otherwise.
Returns whether this result holds a value.
Returns
booltrue if the success arm is active, false otherwise.
Accesses the stored value (lvalue overload).
Returns
T&Reference to the success payload. Lifetime is tied to *this.
Raises
:bad_variant_accessis_err is true. In release builds this is equivalent to undefined behaviour — call is_ok first.Returns the stored value or throws the error as a LucidError.
The rvalue-ref qualifier means this method consumes the Result —
callers should write std::move(r).value_or_throw() (or call it
on a prvalue) to avoid an unnecessary copy of T.
Returns
TThe success payload, moved out of the variant.
Raises
LucidErrormsg is forwarded to ErrorBuilder::fail, which prepends "Result: " and the current ErrorContext trace.Examples
`
T x = std::move(compute()).value_or_throw();
`