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, request: &mut Request<'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.81.0 · sourcefn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
Returns 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"),
}
}
1.81.0 · sourcefn description(&self) -> &str
👎Deprecated since 1.42.0: use the Display impl or to_string()
fn description(&self) -> &str
fn cause(&self) -> Option<&dyn Error>
sourcefn provide<'a>(&'a self, request: &mut Request<'a>)
🔬This is a nightly-only experimental API. (error_generic_member_access
#99301)
fn provide<'a>(&'a self, request: &mut Request<'a>)
error_generic_member_access
#99301)Provides type-based access to context intended for error reports.
Used in conjunction with Request::provide_value
and Request::provide_ref
to extract
references to member variables from dyn Error
trait objects.
§Example
#![feature(error_generic_member_access)]
use core::fmt;
use core::error::{request_ref, Request};
#[derive(Debug)]
enum MyLittleTeaPot {
Empty,
}
#[derive(Debug)]
struct MyBacktrace {
// ...
}
impl MyBacktrace {
fn new() -> MyBacktrace {
// ...
}
}
#[derive(Debug)]
struct Error {
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, request: &mut Request<'a>) {
request
.provide_ref::<MyBacktrace>(&self.backtrace);
}
}
fn main() {
let backtrace = MyBacktrace::new();
let error = Error { backtrace };
let dyn_error = &error as &dyn std::error::Error;
let backtrace_ref = request_ref::<MyBacktrace>(dyn_error).unwrap();
assert!(core::ptr::eq(&error.backtrace, backtrace_ref));
assert!(request_ref::<MyLittleTeaPot>(dyn_error).is_none());
}
Implementations§
source§impl dyn Error + 'static
impl dyn Error + 'static
1.3.0 · sourcepub fn is<T: Error + 'static>(&self) -> bool
pub fn is<T: Error + 'static>(&self) -> bool
Returns true
if the inner type is the same as T
.
1.3.0 · sourcepub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T>
pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T>
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: Error + 'static>(&mut self) -> Option<&mut T>
pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T>
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 + 'static
impl dyn Error + Send + 'static
1.3.0 · sourcepub fn is<T: Error + 'static>(&self) -> bool
pub fn is<T: Error + 'static>(&self) -> bool
Forwards to the method defined on the type dyn Error
.
1.3.0 · sourcepub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T>
pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T>
Forwards to the method defined on the type dyn Error
.
1.3.0 · sourcepub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T>
pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T>
Forwards to the method defined on the type dyn Error
.
source§impl dyn Error + Send + Sync + 'static
impl dyn Error + Send + Sync + 'static
1.3.0 · sourcepub fn is<T: Error + 'static>(&self) -> bool
pub fn is<T: Error + 'static>(&self) -> bool
Forwards to the method defined on the type dyn Error
.
1.3.0 · sourcepub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T>
pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T>
Forwards to the method defined on the type dyn Error
.
1.3.0 · sourcepub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T>
pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T>
Forwards to the method defined on the type dyn Error
.
source§impl dyn Error
impl dyn Error
sourcepub fn sources(&self) -> Source<'_> ⓘ
🔬This is a nightly-only experimental API. (error_iter
#58520)
pub fn sources(&self) -> Source<'_> ⓘ
error_iter
#58520)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());