pub trait MonadError<E>: Monad {
// Required methods
fn throw<T>(error: E) -> Self::Output<T>;
fn catch<F>(&self, f: F) -> Self::Output<Self::Source>
where F: Fn(&E) -> Self::Output<Self::Source>,
Self::Source: Clone;
fn catch_owned<F>(self, f: F) -> Self::Output<Self::Source>
where F: Fn(E) -> Self::Output<Self::Source>,
Self::Source: Clone,
Self: Sized;
}Expand description
A trait for monads that can handle errors, extending the basic Monad trait.
MonadError provides operations for throwing errors and catching errors within a monadic context. It allows for robust error handling while maintaining the benefits of monadic computation chains.
§Type Parameters
E: The error type that can be thrown and caught (no additional constraints required)
§Category Theory
In category theory, MonadError represents a monad with additional structure for error handling.
The error type E doesn’t need to satisfy any particular constraints beyond what’s required
for the specific operations being performed.
§Laws
For a valid MonadError implementation, the following laws must hold:
-
Left Catch Law: throw(e).catch(h) == h(&e) Catching an error that was just thrown should be equivalent to just handling that error.
-
Right Catch Law: m.catch(|e| throw(e)) == m Catching with re-throw as the handler should be a no-op.
-
Associativity Catch Law: m.catch(h1).catch(h2) == m.catch(e -> h1(e).catch(h2)) Nested catches can be rewritten as a single catch with a composed handler.
Required Methods§
Sourcefn throw<T>(error: E) -> Self::Output<T>
fn throw<T>(error: E) -> Self::Output<T>
Creates a new instance in an error state.
This is the equivalent of throwing an exception in languages with exceptions. In category theory, this corresponds to the η (eta) transformation for the error case.
§Type Parameters
T: The type of value that would be contained in a successful result
§Parameters
error: The error value to throw
§Returns
A new monadic value in an error state
Sourcefn catch<F>(&self, f: F) -> Self::Output<Self::Source>
fn catch<F>(&self, f: F) -> Self::Output<Self::Source>
Handles an error by applying a function that can recover from the error.
If this monadic value is in an error state, applies the given function to recover. Otherwise, returns the current successful value.
This operation is category-theoretically sound and doesn’t require additional constraints on the error type beyond what’s needed for the specific implementation.
§Type Parameters
F: The type of the error-handling function
§Parameters
f: A function that takes an error and returns a new monadic value
§Returns
Either the original successful value or the result of applying the recovery function to the error
Sourcefn catch_owned<F>(self, f: F) -> Self::Output<Self::Source>
fn catch_owned<F>(self, f: F) -> Self::Output<Self::Source>
Handles an error by applying a function that can recover from the error, consuming self.
This variant of catch takes ownership of self, allowing for more efficient
implementations when the original monad is no longer needed.
This is the ownership-based version that avoids cloning when possible.
§Type Parameters
F: The type of the error-handling function
§Parameters
f: A function that takes an error and returns a new monadic value
§Returns
Either the original successful value or the result of applying the recovery function to the error
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".