Trait derive_more::Error
1.0.0 · source · pub trait Error: Debug + Display {
// Provided methods
fn source(&self) -> Option<&(dyn Error + 'static)> { ... }
fn description(&self) -> &str { ... }
fn cause(&self) -> Option<&dyn Error> { ... }
fn provide<'a>(&'a self, demand: &mut Demand<'a>) { ... }
}
Expand description
Error
is a trait representing the basic expectations for error values,
i.e., values of type E
in Result<T, E>
.
Errors must describe themselves through the Display
and Debug
traits. Error messages are typically concise lowercase sentences without
trailing punctuation:
let err = "NaN".parse::<u32>().unwrap_err();
assert_eq!(err.to_string(), "invalid digit found in string");
Errors may provide cause information. Error::source()
is generally
used when errors cross “abstraction boundaries”. If one module must report
an error that is caused by an error from a lower-level module, it can allow
accessing that error via Error::source()
. This makes it possible for the
high-level module to provide its own errors while also revealing some of the
implementation for debugging.
Provided Methods§
1.30.0 · sourcefn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
The lower-level source of this error, if any.
Examples
use std::error::Error;
use std::fmt;
#[derive(Debug)]
struct SuperError {
source: SuperErrorSideKick,
}
impl fmt::Display for SuperError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "SuperError is here!")
}
}
impl Error for SuperError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
Some(&self.source)
}
}
#[derive(Debug)]
struct SuperErrorSideKick;
impl fmt::Display for SuperErrorSideKick {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "SuperErrorSideKick is here!")
}
}
impl Error for SuperErrorSideKick {}
fn get_super_error() -> Result<(), SuperError> {
Err(SuperError { source: SuperErrorSideKick })
}
fn main() {
match get_super_error() {
Err(e) => {
println!("Error: {e}");
println!("Caused by: {}", e.source().unwrap());
}
_ => println!("No error"),
}
}
sourcefn description(&self) -> &str
fn description(&self) -> &str
if let Err(e) = "xc".parse::<u32>() {
// Print `e` itself, no need for description().
eprintln!("Error: {e}");
}
sourcefn cause(&self) -> Option<&dyn Error>
fn cause(&self) -> Option<&dyn Error>
sourcefn provide<'a>(&'a self, demand: &mut Demand<'a>)
fn provide<'a>(&'a self, demand: &mut Demand<'a>)
error_generic_member_access
)Provides type based access to context intended for error reports.
Used in conjunction with Demand::provide_value
and Demand::provide_ref
to extract
references to member variables from dyn Error
trait objects.
Example
#![feature(provide_any)]
#![feature(error_generic_member_access)]
use core::fmt;
use core::any::Demand;
#[derive(Debug)]
struct MyBacktrace {
// ...
}
impl MyBacktrace {
fn new() -> MyBacktrace {
// ...
}
}
#[derive(Debug)]
struct SourceError {
// ...
}
impl fmt::Display for SourceError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "Example Source Error")
}
}
impl std::error::Error for SourceError {}
#[derive(Debug)]
struct Error {
source: SourceError,
backtrace: MyBacktrace,
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "Example Error")
}
}
impl std::error::Error for Error {
fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
demand
.provide_ref::<MyBacktrace>(&self.backtrace)
.provide_ref::<dyn std::error::Error + 'static>(&self.source);
}
}
fn main() {
let backtrace = MyBacktrace::new();
let source = SourceError {};
let error = Error { source, backtrace };
let dyn_error = &error as &dyn std::error::Error;
let backtrace_ref = dyn_error.request_ref::<MyBacktrace>().unwrap();
assert!(core::ptr::eq(&error.backtrace, backtrace_ref));
}
Implementations§
source§impl<'a> dyn Error + 'a
impl<'a> dyn Error + 'a
sourcepub fn request_ref<T>(&'a self) -> Option<&'a T>where
T: 'static + ?Sized,
🔬This is a nightly-only experimental API. (error_generic_member_access
)Available on crate feature error
only.
pub fn request_ref<T>(&'a self) -> Option<&'a T>where T: 'static + ?Sized,
error_generic_member_access
)error
only.Request a reference of type T
as context about this error.
sourcepub fn request_value<T>(&'a self) -> Option<T>where
T: 'static,
🔬This is a nightly-only experimental API. (error_generic_member_access
)Available on crate feature error
only.
pub fn request_value<T>(&'a self) -> Option<T>where T: 'static,
error_generic_member_access
)error
only.Request a value of type T
as context about this error.
source§impl dyn Error
impl dyn Error
1.3.0 · sourcepub fn is<T>(&self) -> boolwhere
T: Error + 'static,
Available on crate feature error
only.
pub fn is<T>(&self) -> boolwhere T: Error + 'static,
error
only.Returns true
if the inner type is the same as T
.
1.3.0 · sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: Error + 'static,
Available on crate feature error
only.
pub fn downcast_ref<T>(&self) -> Option<&T>where T: Error + 'static,
error
only.Returns some reference to the inner value if it is of type T
, or
None
if it isn’t.
1.3.0 · sourcepub fn downcast_mut<T>(&mut self) -> Option<&mut T>where
T: Error + 'static,
Available on crate feature error
only.
pub fn downcast_mut<T>(&mut self) -> Option<&mut T>where T: Error + 'static,
error
only.Returns some mutable reference to the inner value if it is of type T
, or
None
if it isn’t.
source§impl dyn Error + Send
impl dyn Error + Send
1.3.0 · sourcepub fn is<T>(&self) -> boolwhere
T: Error + 'static,
Available on crate feature error
only.
pub fn is<T>(&self) -> boolwhere T: Error + 'static,
error
only.Forwards to the method defined on the type dyn Error
.
1.3.0 · sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: Error + 'static,
Available on crate feature error
only.
pub fn downcast_ref<T>(&self) -> Option<&T>where T: Error + 'static,
error
only.Forwards to the method defined on the type dyn Error
.
1.3.0 · sourcepub fn downcast_mut<T>(&mut self) -> Option<&mut T>where
T: Error + 'static,
Available on crate feature error
only.
pub fn downcast_mut<T>(&mut self) -> Option<&mut T>where T: Error + 'static,
error
only.Forwards to the method defined on the type dyn Error
.
sourcepub fn request_ref<T>(&self) -> Option<&T>where
T: 'static + ?Sized,
🔬This is a nightly-only experimental API. (error_generic_member_access
)Available on crate feature error
only.
pub fn request_ref<T>(&self) -> Option<&T>where T: 'static + ?Sized,
error_generic_member_access
)error
only.Request a reference of type T
as context about this error.
sourcepub fn request_value<T>(&self) -> Option<T>where
T: 'static,
🔬This is a nightly-only experimental API. (error_generic_member_access
)Available on crate feature error
only.
pub fn request_value<T>(&self) -> Option<T>where T: 'static,
error_generic_member_access
)error
only.Request a value of type T
as context about this error.
source§impl dyn Error + Send + Sync
impl dyn Error + Send + Sync
1.3.0 · sourcepub fn is<T>(&self) -> boolwhere
T: Error + 'static,
Available on crate feature error
only.
pub fn is<T>(&self) -> boolwhere T: Error + 'static,
error
only.Forwards to the method defined on the type dyn Error
.
1.3.0 · sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: Error + 'static,
Available on crate feature error
only.
pub fn downcast_ref<T>(&self) -> Option<&T>where T: Error + 'static,
error
only.Forwards to the method defined on the type dyn Error
.
1.3.0 · sourcepub fn downcast_mut<T>(&mut self) -> Option<&mut T>where
T: Error + 'static,
Available on crate feature error
only.
pub fn downcast_mut<T>(&mut self) -> Option<&mut T>where T: Error + 'static,
error
only.Forwards to the method defined on the type dyn Error
.
sourcepub fn request_ref<T>(&self) -> Option<&T>where
T: 'static + ?Sized,
🔬This is a nightly-only experimental API. (error_generic_member_access
)Available on crate feature error
only.
pub fn request_ref<T>(&self) -> Option<&T>where T: 'static + ?Sized,
error_generic_member_access
)error
only.Request a reference of type T
as context about this error.
sourcepub fn request_value<T>(&self) -> Option<T>where
T: 'static,
🔬This is a nightly-only experimental API. (error_generic_member_access
)Available on crate feature error
only.
pub fn request_value<T>(&self) -> Option<T>where T: 'static,
error_generic_member_access
)error
only.Request a value of type T
as context about this error.
source§impl dyn Error
impl dyn Error
sourcepub fn sources(&self) -> Source<'_>
🔬This is a nightly-only experimental API. (error_iter
)Available on crate feature error
only.
pub fn sources(&self) -> Source<'_>
error_iter
)error
only.Returns an iterator starting with the current error and continuing with
recursively calling Error::source
.
If you want to omit the current error and only use its sources,
use skip(1)
.
Examples
#![feature(error_iter)]
use std::error::Error;
use std::fmt;
#[derive(Debug)]
struct A;
#[derive(Debug)]
struct B(Option<Box<dyn Error + 'static>>);
impl fmt::Display for A {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "A")
}
}
impl fmt::Display for B {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "B")
}
}
impl Error for A {}
impl Error for B {
fn source(&self) -> Option<&(dyn Error + 'static)> {
self.0.as_ref().map(|e| e.as_ref())
}
}
let b = B(Some(Box::new(A)));
// let err : Box<Error> = b.into(); // or
let err = &b as &(dyn Error);
let mut iter = err.sources();
assert_eq!("B".to_string(), iter.next().unwrap().to_string());
assert_eq!("A".to_string(), iter.next().unwrap().to_string());
assert!(iter.next().is_none());
assert!(iter.next().is_none());
Trait Implementations§
source§impl<'a> From<&str> for Box<dyn Error + Send + Sync + 'a, Global>
Available on non-no_global_oom_handling
only.
impl<'a> From<&str> for Box<dyn Error + Send + Sync + 'a, Global>
no_global_oom_handling
only.1.6.0 · source§impl From<&str> for Box<dyn Error, Global>
Available on non-no_global_oom_handling
only.
impl From<&str> for Box<dyn Error, Global>
no_global_oom_handling
only.1.22.0 · source§impl<'a> From<Cow<'a, str>> for Box<dyn Error, Global>
Available on non-no_global_oom_handling
only.
impl<'a> From<Cow<'a, str>> for Box<dyn Error, Global>
no_global_oom_handling
only.1.22.0 · source§impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + Send + Sync + 'a, Global>
Available on non-no_global_oom_handling
only.
impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + Send + Sync + 'a, Global>
no_global_oom_handling
only.source§fn from(err: Cow<'b, str>) -> Box<dyn Error + Send + Sync + 'a, Global>
fn from(err: Cow<'b, str>) -> Box<dyn Error + Send + Sync + 'a, Global>
Converts a Cow
into a box of dyn Error
+ Send
+ Sync
.
Examples
use std::error::Error;
use std::mem;
use std::borrow::Cow;
let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_cow_str_error);
assert!(
mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
source§impl<'a, E> From<E> for Box<dyn Error + 'a, Global>where
E: Error + 'a,
Available on non-no_global_oom_handling
only.
impl<'a, E> From<E> for Box<dyn Error + 'a, Global>where E: Error + 'a,
no_global_oom_handling
only.source§fn from(err: E) -> Box<dyn Error + 'a, Global>
fn from(err: E) -> Box<dyn Error + 'a, Global>
Converts a type of Error
into a box of dyn Error
.
Examples
use std::error::Error;
use std::fmt;
use std::mem;
#[derive(Debug)]
struct AnError;
impl fmt::Display for AnError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "An error")
}
}
impl Error for AnError {}
let an_error = AnError;
assert!(0 == mem::size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error>::from(an_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
source§impl<'a, E> From<E> for Box<dyn Error + Send + Sync + 'a, Global>where
E: Error + Send + Sync + 'a,
Available on non-no_global_oom_handling
only.
impl<'a, E> From<E> for Box<dyn Error + Send + Sync + 'a, Global>where E: Error + Send + Sync + 'a,
no_global_oom_handling
only.source§fn from(err: E) -> Box<dyn Error + Send + Sync + 'a, Global>
fn from(err: E) -> Box<dyn Error + Send + Sync + 'a, Global>
Converts a type of Error
+ Send
+ Sync
into a box of
dyn Error
+ Send
+ Sync
.
Examples
use std::error::Error;
use std::fmt;
use std::mem;
#[derive(Debug)]
struct AnError;
impl fmt::Display for AnError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "An error")
}
}
impl Error for AnError {}
unsafe impl Send for AnError {}
unsafe impl Sync for AnError {}
let an_error = AnError;
assert!(0 == mem::size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(an_error);
assert!(
mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
source§impl From<String> for Box<dyn Error + Send + Sync, Global>
Available on non-no_global_oom_handling
only.
impl From<String> for Box<dyn Error + Send + Sync, Global>
no_global_oom_handling
only.source§fn from(err: String) -> Box<dyn Error + Send + Sync, Global>
fn from(err: String) -> Box<dyn Error + Send + Sync, Global>
Converts a String
into a box of dyn Error
+ Send
+ Sync
.
Examples
use std::error::Error;
use std::mem;
let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_string_error);
assert!(
mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
Implementors§
impl !Error for &str
impl Error for Infallible
impl Error for VarError
impl Error for RecvTimeoutError
impl Error for TryRecvError
impl Error for BinaryError
add
and crate feature std
and (crate features add
or not
) only.impl Error for !
impl Error for TryReserveError
impl Error for FromVecWithNulError
impl Error for IntoStringError
impl Error for NulError
impl Error for FromUtf8Error
impl Error for FromUtf16Error
impl Error for LayoutError
impl Error for AllocError
impl Error for TryFromSliceError
impl Error for BorrowError
impl Error for BorrowMutError
impl Error for CharTryFromError
impl Error for ParseCharError
impl Error for DecodeUtf16Error
impl Error for TryFromCharError
impl Error for FromBytesUntilNulError
impl Error for FromBytesWithNulError
impl Error for core::fmt::Error
impl Error for AddrParseError
impl Error for ParseFloatError
impl Error for ParseIntError
impl Error for TryFromIntError
impl Error for ParseBoolError
impl Error for Utf8Error
impl Error for TryFromFloatSecsError
impl Error for JoinPathsError
impl Error for WriterPanicked
impl Error for std::io::error::Error
impl Error for StripPrefixError
impl Error for ExitStatusError
impl Error for RecvError
impl Error for AccessError
impl Error for SystemTimeError
impl Error for UnitError
add
or not
) and crate feature std
only.impl Error for WrongVariantError
add
and crate feature std
and (crate features add
or not
) only.impl Error for FromStrError
from_str
and std
only.impl<'a, K, V> Error for alloc::collections::btree::map::entry::OccupiedError<'a, K, V, Global>where K: Debug + Ord, V: Debug,
impl<'a, K, V> Error for std::collections::hash::map::OccupiedError<'a, K, V>where K: Debug, V: Debug,
impl<'a, T> Error for &'a Twhere T: Error + ?Sized,
impl<T> Error for TrySendError<T>
impl<T> Error for TryLockError<T>
impl<T> Error for Box<T, Global>where T: Error,
impl<T> Error for ThinBox<T>where T: Error + ?Sized,
impl<T> Error for Arc<T, Global>where T: Error + ?Sized,
impl<T> Error for SendError<T>
impl<T> Error for PoisonError<T>
impl<T: Debug> Error for TryIntoError<T>
try_into
and std
only.impl<T: Debug> Error for TryUnwrapError<T>
try_unwrap
and std
only.