Trait CauseExt

pub trait CauseExt: Sealed {
    // Required methods
    fn has_cause<T>(&self) -> bool
       where T: Error + 'static;
    fn find_cause<T>(&self) -> Option<&T>
       where T: Error + 'static;
    fn any_cause(
        &self,
        predicate: impl FnMut(&(dyn Error + 'static)) -> bool,
    ) -> bool;
    fn root_cause(&self) -> &(dyn Error + 'static);
    fn context_fields(&self) -> impl Iterator<Item = &ContextField>;
    fn context_value<T>(&self, key: &str) -> Option<&T>
       where T: Any;
}

Expand description

Look up causes of an error by type.

The lookup walks the same chain as error_chain, so it also finds an error that a std::io::Error wraps, and it enters every failure of an ErrorList, not only the primary one. At most 64 errors are visited in total.

Implemented for every concrete error type and for dyn Error trait objects, which includes BoxError through auto-deref.

use rama_error::{BoxError, CauseExt, ErrorExt};

#[derive(Debug)]
struct Timeout;

impl std::fmt::Display for Timeout {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("timeout")
    }
}

impl std::error::Error for Timeout {}

let error: BoxError = std::io::Error::other(Timeout).context("connect");
assert!(error.has_cause::<Timeout>());
assert!(error.find_cause::<std::io::Error>().is_some());
assert!(!error.has_cause::<std::fmt::Error>());
assert!(error.any_cause(|cause| cause
    .downcast_ref::<std::io::Error>()
    .is_some_and(|io| io.kind() == std::io::ErrorKind::Other)));

Required Methods§

fn has_cause<T>(&self) -> bool
where T: Error + 'static,

Whether this error or one of its causes is a T.

fn find_cause<T>(&self) -> Option<&T>
where T: Error + 'static,

The first error of type T, starting with this error itself.

fn any_cause( &self, predicate: impl FnMut(&(dyn Error + 'static)) -> bool, ) -> bool

Whether predicate holds for this error or one of its causes, visited in the same order and within the same bound as Self::find_cause.

fn root_cause(&self) -> &(dyn Error + 'static)

The last error in the chain: this error when it has no cause. Through an ErrorList the chain follows its primary failure.

The walk visits at most 64 errors, as error_chain does; for a longer or cyclic chain this is the last error visited.

fn context_fields(&self) -> impl Iterator<Item = &ContextField>

Every context field on the chain, outermost error first and in the order each error received them. Follows the same chain as error_chain: through an ErrorList only its primary failure.