Struct Handled

Source

pub struct Handled<E = Error> { /* private fields */ }

Expand description

Error wrapper that captures context and stack traces for any error.

Handled<E> wraps an error type E while adding:

A trace of frames showing where the error propagated
Context messages and key-value attachments at each frame

§Type Parameters

E - The underlying error type. Defaults to Error for type-erased errors (the common case with handle! macro).

The handle! macro produces Handled<Error> (aliased as Handled), with the concrete error type preserved inside for downcasting via TryCatch.

§Examples

use handle_this::{handle, Handled, Result};

fn read_file(path: &str) -> Result<String> {
    handle! { try { std::fs::read_to_string(path)? } with "reading config" }
}

Implementations§

Source §

impl<E> Handled<E>

Source

pub fn new(source: E) -> Self
where E: Display,

Create a new Handled wrapper around an error. Message is computed lazily on first access.

Source

pub fn message(&self) -> &str
where E: Display,

Get the error message, computing it lazily on first access.

Source

pub fn source_ref(&self) -> &E

Get the underlying error source.

Source

pub fn into_source(self) -> E

Consume and return the underlying error.

Source

pub fn frames(&self) -> impl Iterator<Item = FrameView<'_>>

Iterate over frames in the trace. Combines locations with their optional contexts.

Source

pub fn depth(&self) -> usize

Number of location frames in the trace.

Source

pub fn is_empty(&self) -> bool

Whether the trace is empty.

Source

pub fn context_count(&self) -> usize

Number of context entries (frames with messages/attachments).

Source

pub fn here(self) -> Self

Add a frame at the caller’s location.

Source

pub fn erase(self) -> Handled<Error>
where E: StdError + Send + Sync + 'static,

Convert to a type-erased Handled.

Source

pub fn map_err<F, O>(self, f: F) -> Handled<O>
where F: FnOnce(E) -> O, O: Display,

Map the error type while preserving context.

Source §

impl Handled<Error>

Source

pub fn wrap<E>(e: E) -> Self
where E: StdError + Send + Sync + 'static,

Wrap any error, avoiding double-boxing if already Handled. Message is computed lazily on first access.

Source

pub fn wrap_box(e: Box<dyn StdError + Send + Sync + 'static>) -> Self

Wrap a boxed error into a type-erased Handled. If the boxed error is already a Handled, unwrap it to avoid double-wrapping. Message is computed lazily on first access.

Source

pub fn wrap_erased(e: Error) -> Self

Wrap an Error directly. Message is computed lazily on first access.

Source

pub fn msg(message: impl Into<String>) -> Self

Create from a message string. Message is pre-initialized since we already have it.

Source

pub fn root(&self) -> &(dyn StdError + 'static)

Get the root error as a trait object.

Source

pub fn downcast_ref<T: StdError + 'static>(&self) -> Option<&T>

Try to downcast to a specific error type.

Source

pub fn downcast<T: StdError + 'static>(self) -> Result<T, Self>

Try to downcast and consume the error.

Source

pub fn chain_any<T: StdError + 'static>(&self) -> Option<&T>

Find the first error of type T in the cause chain.

Walks the error chain via std::error::Error::source() and returns a reference to the first error that matches type T.

§Example

use handle_this::{Handled, Result};
use std::io;

fn check_chain(err: &Handled) {
    if let Some(io_err) = err.chain_any::<io::Error>() {
        println!("Found IO error in chain: {:?}", io_err.kind());
    }
}

Source

pub fn chain_all<T: StdError + 'static>(&self) -> Vec<&T>

Find all errors of type T in the cause chain.

Walks the error chain via std::error::Error::source() and collects references to all errors that match type T.

§Example

use handle_this::{Handled, Result};
use std::io;

fn check_all(err: &Handled) {
    let io_errors = err.chain_all::<io::Error>();
    for e in io_errors {
        println!("IO error: {:?}", e.kind());
    }
}