Struct narrate::Error

source ·

pub struct Error { /* private fields */ }

Expand description

Wrapper around a dynamic error type with an optional help message.

Error works a lot like Box<dyn std::error::Error>, but with these differences:

Error requires that the error is Send, Sync, and 'static.
Error is represented as a narrow pointer — exactly one word in size instead of two.
Error may contain a help message in order to suggest further actions a user might take.

Implementations

source

impl Error

source

pub fn new<E>(error: E) -> Selfwhere
E: StdError + Send + Sync + 'static,

Create a new error object from any error type.

The error type must be thread-safe and 'static, so that the Error will be as well.

source

pub fn from_anyhow(error: Error) -> Self

Convert an anyhow::Error into an error object.

Due to the generic implementation of From for Error: we cannot add a From<anyhow::Error> impl. Use this instead.

source

pub fn wrap<C>(self, context: C) -> Selfwhere
C: Display + Send + Sync + 'static,

Wrap the error value with additional context.

For attaching context to a Result as it is propagated, the ErrorWrap extension trait may be more convenient than this function.

The primary reason to use error.warp(...) instead of result.warp(...) via the ErrorWrap trait would be if the context needs to depend on some data held by the underlying error:

use narrate::Result;
use std::fs::File;
use std::path::Path;

struct ParseError {
    line: usize,
    column: usize,
}

fn parse_impl(file: File) -> Result<T, ParseError> {
    ...
}

pub fn parse(path: impl AsRef<Path>) -> Result<T> {
    let file = File::open(&path)?;
    parse_impl(file).map_err(|error| {
        let context = format!(
            "only the first {} lines of {} are valid",
            error.line, path.as_ref().display(),
        );
        narrate::Error::new(error).wrap(context)
    })
}

source

pub fn is<E>(&self) -> boolwhere
E: Display + Debug + Send + Sync + 'static,

Returns true if E is the type held by this error object.

For wrapped errors, this method returns true if E matches the type of the context C or the type of the error on which the context has been attached.

source

pub fn downcast<E>(self) -> Result<E, Self>where
E: Display + Debug + Send + Sync + 'static,

Attempt to downcast the error object to a concrete type.

source

pub fn downcast_ref<E>(&self) -> Option<&E>where
E: Display + Debug + Send + Sync + 'static,

Downcast this error object by reference.

Example

// If the error was caused by redaction, then return a tombstone instead
// of the content.
match root_cause.downcast_ref::<DataStoreError>() {
    Some(DataStoreError::Censored(_)) => Ok(Poll::Ready(REDACTED_CONTENT)),
    None => Err(error),
}

source

pub fn downcast_mut<E>(&mut self) -> Option<&mut E>where
E: Display + Debug + Send + Sync + 'static,

Downcast this error object by mutable reference.

source

pub fn chain(&self) -> Chain<'_> ⓘ

An iterator of the chain of source errors contained by this Error.

This iterator will visit every error in the cause chain of this error object, beginning with the error that this error object was created from.

Example

use narrate::Error;
use std::io;

pub fn underlying_io_error_kind(error: &Error) -> Option<io::ErrorKind> {
    for cause in error.chain() {
        if let Some(io_error) = cause.downcast_ref::<io::Error>() {
            return Some(io_error.kind());
        }
    }
    None
}