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 isSend
,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
sourceimpl Error
impl Error
sourcepub fn new<E>(error: E) -> Selfwhere
E: StdError + Send + Sync + 'static,
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.
sourcepub fn from_anyhow(error: Error) -> Self
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.
sourcepub fn wrap<C>(self, context: C) -> Selfwhere
C: Display + Send + Sync + 'static,
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)
})
}
sourcepub fn is<E>(&self) -> boolwhere
E: Display + Debug + Send + Sync + 'static,
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.
sourcepub fn downcast<E>(self) -> Result<E, Self>where
E: Display + Debug + Send + Sync + 'static,
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.
sourcepub fn downcast_ref<E>(&self) -> Option<&E>where
E: Display + Debug + Send + Sync + 'static,
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),
}
sourcepub fn downcast_mut<E>(&mut self) -> Option<&mut E>where
E: Display + Debug + Send + Sync + 'static,
pub fn downcast_mut<E>(&mut self) -> Option<&mut E>where
E: Display + Debug + Send + Sync + 'static,
Downcast this error object by mutable reference.
sourcepub fn chain(&self) -> Chain<'_> ⓘ
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
}
sourcepub fn root_cause(&self) -> &(dyn StdError + 'static)
pub fn root_cause(&self) -> &(dyn StdError + 'static)
The lowest level cause of this error — this error’s cause’s cause’s cause etc.
The root cause is the last error in the iterator produced by
chain()
.
sourcepub fn set_help_owned(&mut self, msg: String)
👎Deprecated
pub fn set_help_owned(&mut self, msg: String)
Set this error’s help message to an owned String
sourcepub fn set_help(&mut self, msg: &'static str)
👎Deprecated
pub fn set_help(&mut self, msg: &'static str)
Set this error’s help message to a static &str