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");§Error source
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.
In error types that wrap an underlying error, the underlying error
should be either returned by the outer error’s Error::source(), or rendered
by the outer error’s Display implementation, but not both.
§Example
Implementing the Error trait only requires that Debug and Display are implemented too.
use std::error::Error;
use std::fmt;
use std::path::PathBuf;
#[derive(Debug)]
struct ReadConfigError {
path: PathBuf
}
impl fmt::Display for ReadConfigError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let path = self.path.display();
write!(f, "unable to read configuration at {path}")
}
}
impl Error for ReadConfigError {}Provided Methods§
1.30.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.0.0 · Sourcefn description(&self) -> &str
👎Deprecated since 1.42.0: use the Display impl or to_string()
fn description(&self) -> &str
if let Err(e) = "xc".parse::<u32>() {
// Print `e` itself, no need for description().
eprintln!("Error: {e}");
}fn cause(&self) -> Option<&dyn Error>
👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting
Sourcefn provide<'a>(&'a self, request: &mut Request<'a>)
🔬This is a nightly-only experimental API. (error_generic_member_access)
fn provide<'a>(&'a self, request: &mut Request<'a>)
error_generic_member_access)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
impl dyn Error
1.3.0 · Sourcepub fn is<T>(&self) -> boolwhere
T: Error + 'static,
pub fn is<T>(&self) -> boolwhere
T: Error + 'static,
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,
pub fn downcast_ref<T>(&self) -> Option<&T>where
T: Error + 'static,
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,
pub fn downcast_mut<T>(&mut self) -> Option<&mut T>where
T: Error + 'static,
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,
pub fn is<T>(&self) -> boolwhere
T: Error + 'static,
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,
pub fn downcast_ref<T>(&self) -> Option<&T>where
T: Error + 'static,
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,
pub fn downcast_mut<T>(&mut self) -> Option<&mut T>where
T: Error + 'static,
Forwards to the method defined on the type dyn Error.
Source§impl dyn Error + Send + Sync
impl dyn Error + Send + Sync
1.3.0 · Sourcepub fn is<T>(&self) -> boolwhere
T: Error + 'static,
pub fn is<T>(&self) -> boolwhere
T: Error + 'static,
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,
pub fn downcast_ref<T>(&self) -> Option<&T>where
T: Error + 'static,
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,
pub fn downcast_mut<T>(&mut self) -> Option<&mut T>where
T: Error + 'static,
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)
pub fn sources(&self) -> Source<'_>
error_iter)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());