Trait std::error::Error
pub trait Error: Debug + Display { fn source(&self) -> Option<&(dyn Error + 'static)> { ... } fn backtrace(&self) -> Option<&Backtrace> { ... } fn description(&self) -> &str { ... } fn cause(&self) -> Option<&dyn Error> { ... } }
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 chain 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 via source
chains.
Provided methods
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 { side: 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.side) } } #[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 { side: SuperErrorSideKick }) } fn main() { match get_super_error() { Err(e) => { println!("Error: {}", e); println!("Caused by: {}", e.source().unwrap()); } _ => println!("No error"), } }
fn backtrace(&self) -> Option<&Backtrace>
Returns a stack backtrace, if available, of where this error occurred.
This function allows inspecting the location, in code, of where an error happened. The returned Backtrace
contains information about the stack trace of the OS thread of execution of where the error originated from.
Note that not all errors contain a Backtrace
. Also note that a Backtrace
may actually be empty. For more information consult the Backtrace
type itself.
fn description(&self) -> &str
use the Display impl or to_string()
if let Err(e) = "xc".parse::<u32>() { // Print `e` itself, no need for description(). eprintln!("Error: {}", e); }
fn cause(&self) -> Option<&dyn Error>
replaced by Error::source, which can support downcasting
Implementations
impl dyn Error + 'static
pub fn is<T: Error + 'static>(&self) -> bool
Returns true
if the boxed type is the same as T
pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T>
Returns some reference to the boxed value if it is of type T
, or None
if it isn’t.
pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T>
Returns some mutable reference to the boxed value if it is of type T
, or None
if it isn’t.
impl dyn Error + Send + 'static
pub fn is<T: Error + 'static>(&self) -> bool
Forwards to the method defined on the type dyn Error
.
pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T>
Forwards to the method defined on the type dyn Error
.
pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T>
Forwards to the method defined on the type dyn Error
.
impl dyn Error + Send + Sync + 'static
pub fn is<T: Error + 'static>(&self) -> bool
Forwards to the method defined on the type dyn Error
.
pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T>
Forwards to the method defined on the type dyn Error
.
pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T>
Forwards to the method defined on the type dyn Error
.
impl dyn Error
pub fn downcast<T: Error + 'static>(
self: Box<Self>
) -> Result<Box<T>, Box<dyn Error>>
Attempts to downcast the box to a concrete type.
pub fn chain(&self) -> Chain<'_>
impl<'a> Iterator for Chain<'a> type Item = &'a (dyn Error + 'static);
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.chain(); 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());
impl dyn Error + Send
pub fn downcast<T: Error + 'static>(
self: Box<Self>
) -> Result<Box<T>, Box<dyn Error + Send>>
Attempts to downcast the box to a concrete type.
impl dyn Error + Send + Sync
pub fn downcast<T: Error + 'static>(
self: Box<Self>
) -> Result<Box<T>, Box<Self>>
Attempts to downcast the box to a concrete type.
Implementations on Foreign Types
impl Error for FromSecsError
Implementors
impl Error for Infallible
impl Error for VarError
impl Error for RecvTimeoutError
impl Error for TryRecvError
impl Error for !
impl Error for AllocError
impl Error for LayoutError
impl Error for TryFromSliceError
impl Error for BorrowError
impl Error for BorrowMutError
impl Error for CharTryFromError
impl Error for DecodeUtf16Error
impl Error for ParseCharError
impl Error for TryReserveError
impl Error for JoinPathsError
impl Error for FromBytesWithNulError
impl Error for FromVecWithNulError
impl Error for IntoStringError
impl Error for NulError
impl Error for std::fmt::Error
impl Error for std::io::Error
impl Error for WriterPanicked
impl Error for AddrParseError
impl Error for ParseFloatError
impl Error for ParseIntError
impl Error for TryFromIntError
impl Error for StripPrefixError
impl Error for ExitStatusError
impl Error for ParseBoolError
impl Error for Utf8Error
impl Error for FromUtf8Error
impl Error for FromUtf16Error
impl Error for RecvError
impl Error for AccessError
impl Error for SystemTimeError
impl<'a, K: Debug + Ord, V: Debug> Error for std::collections::btree_map::OccupiedError<'a, K, V>
impl<'a, K: Debug, V: Debug> Error for std::collections::hash_map::OccupiedError<'a, K, V>
impl<'a, T: Error + ?Sized> Error for &'a T
impl<T> Error for TryLockError<T>
impl<T> Error for PoisonError<T>
impl<T: Send> Error for TrySendError<T>
impl<T: Send> Error for SendError<T>
impl<T: Error + ?Sized> Error for Arc<T>
impl<T: Error> Error for Box<T>
impl<W: Send + Debug> Error for IntoInnerError<W>
© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/error/trait.Error.html