Trait ErrorTrait

pub trait ErrorTrait: 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>) { ... }
}

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.

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

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"),
    }
}

fn description(&self) -> &str

👎Deprecated since 1.42.0: 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>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (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

impl dyn Error

pub fn is<T>(&self) -> bool

where T: Error + 'static,

Returns true if the inner type is the same as T.

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.

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.

impl dyn Error + Send

pub fn is<T>(&self) -> bool

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

pub fn downcast_mut<T>(&mut self) -> Option<&mut T>

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

impl dyn Error + Send + Sync

pub fn is<T>(&self) -> bool

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

pub fn downcast_mut<T>(&mut self) -> Option<&mut T>

where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

impl dyn Error

pub fn sources(&self) -> Source<'_>

🔬This is a nightly-only experimental API. (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());

impl dyn Error

pub fn downcast<T>(self: Box<dyn Error>) -> Result<Box<T>, Box<dyn Error>>

where T: Error + 'static,

Attempts to downcast the box to a concrete type.

impl dyn Error + Send

pub fn downcast<T>( self: Box<dyn Error + Send>, ) -> Result<Box<T>, Box<dyn Error + Send>>

where T: Error + 'static,

Attempts to downcast the box to a concrete type.

impl dyn Error + Send + Sync

pub fn downcast<T>( self: Box<dyn Error + Send + Sync>, ) -> Result<Box<T>, Box<dyn Error + Send + Sync>>

where T: Error + 'static,

Attempts to downcast the box to a concrete type.

Trait Implementations

impl AsRef<dyn Error> for Error

fn as_ref(&self) -> &(dyn Error + 'static)

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<dyn Error + Send + Sync> for Error

fn as_ref(&self) -> &(dyn Error + Send + Sync + 'static)

Converts this type into a shared reference of the (usually inferred) input type.

impl<'a> From<&str> for Box<dyn Error + 'a>

fn from(err: &str) -> Box<dyn Error + 'a>

Converts a str into a box of dyn Error.

Examples

use std::error::Error;

let a_str_error = "a str error";
let a_boxed_error = Box::<dyn Error>::from(a_str_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))

impl<'a> From<&str> for Box<dyn Error + Send + Sync + 'a>

fn from(err: &str) -> Box<dyn Error + Send + Sync + 'a>

Converts a str into a box of dyn Error + Send + Sync.

Examples

use std::error::Error;

let a_str_error = "a str error";
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_str_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))

impl From<ColoredString> for Box<dyn Error>

fn from(cs: ColoredString) -> Box<dyn Error>

Converts to this type from the input type.

impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + 'a>

fn from(err: Cow<'b, str>) -> Box<dyn Error + 'a>

Converts a Cow into a box of dyn Error.

Examples

use std::error::Error;
use std::borrow::Cow;

let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error>::from(a_cow_str_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))

impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + Send + Sync + 'a>

fn from(err: Cow<'b, str>) -> Box<dyn Error + Send + Sync + 'a>

Converts a Cow into a box of dyn Error + Send + Sync.

Examples

use std::error::Error;
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!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))

impl<'a, E> From<E> for Box<dyn Error + 'a>

where E: Error + 'a,

fn from(err: E) -> Box<dyn Error + 'a>

Converts a type of Error into a box of dyn Error.

Examples

use std::error::Error;
use std::fmt;

#[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 == size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error>::from(an_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))

impl<'a, E> From<E> for Box<dyn Error + Send + Sync + 'a>

where E: Error + Send + Sync + 'a,

fn from(err: E) -> Box<dyn Error + Send + Sync + 'a>

Converts a type of Error + Send + Sync into a box of dyn Error + Send + Sync.

Examples

use std::error::Error;
use std::fmt;

#[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 == size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(an_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))

impl From<Error> for Box<dyn Error>

fn from(error: Error) -> Box<dyn Error>

Converts to this type from the input type.

impl From<Error> for Box<dyn Error + Send>

fn from(error: Error) -> Box<dyn Error + Send>

Converts to this type from the input type.

impl From<Error> for Box<dyn Error + Send + Sync>

fn from(error: Error) -> Box<dyn Error + Send + Sync>

Converts to this type from the input type.

impl<'a> From<String> for Box<dyn Error + 'a>

fn from(str_err: String) -> Box<dyn Error + 'a>

Converts a String into a box of dyn Error.

Examples

use std::error::Error;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error>::from(a_string_error);
assert!(size_of::<Box<dyn Error>>() == size_of_val(&a_boxed_error))

impl<'a> From<String> for Box<dyn Error + Send + Sync + 'a>

fn from(err: String) -> Box<dyn Error + Send + Sync + 'a>

Converts a String into a box of dyn Error + Send + Sync.

Examples

use std::error::Error;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_string_error);
assert!(
    size_of::<Box<dyn Error + Send + Sync>>() == size_of_val(&a_boxed_error))

Implementors

impl !Error for &str

impl Error for CrateDocError

impl Error for MainHeaderRenewError

impl Error for ModulesHeadersRenewError

impl Error for ManifestError

impl Error for PathError

impl Error for WorkspaceInitError

impl Error for PackageError

impl Error for Infallible

impl Error for FromBytesWithNulError

impl Error for GetDisjointMutError

impl Error for VarError

impl Error for std::fs::TryLockError

impl Error for RecvTimeoutError

impl Error for TryRecvError

impl Error for ParseAlphabetError

impl Error for DecodeError

impl Error for DecodeSliceError

impl Error for EncodeSliceError

impl Error for cargo_metadata::errors::Error

impl Error for StringStreamError

impl Error for UnexpectedParse

impl Error for BinaryError

impl Error for CodepointError

impl Error for FromStrError

impl Error for Utf16ArrayError

impl Error for Utf16PairError

impl Error for Utf16SliceError

impl Error for Utf16TupleError

impl Error for ignore::Error

impl Error for StartError

impl Error for regex_syntax::error::Error

impl Error for regex::error::Error

impl Error for rustls_pki_types::pem::Error

impl Error for webpki::error::Error

impl Error for rustls::error::Error

impl Error for VerifierBuilderError

impl Error for strum::ParseError

impl Error for term::Error

impl Error for term::terminfo::Error

impl Error for term::terminfo::parm::Error

impl Error for ucd_trie::owned::Error

impl Error for ureq::error::Error

impl Error for url::parser::ParseError

impl Error for wca::ca::aggregator::private::Error

impl Error for ValidationError

impl Error for ParserError

impl Error for VerificationError

impl Error for !

impl Error for NormalizeError

impl Error for StripPrefixError

impl Error for willbe::proc_macro2::LexError

impl Error for willbe::syn::Error

impl Error for UnorderedKeyError

impl Error for alloc::collections::TryReserveError

impl Error for FromVecWithNulError

impl Error for IntoStringError

impl Error for NulError

impl Error for alloc::string::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 core::fmt::Error

impl Error for core::net::parser::AddrParseError

impl Error for ParseFloatError

impl Error for ParseIntError

impl Error for TryFromIntError

impl Error for ParseBoolError

impl Error for core::str::error::Utf8Error

impl Error for TryFromFloatSecsError

impl Error for ExpandError

impl Error for proc_macro::LexError

impl Error for JoinPathsError

impl Error for WriterPanicked

impl Error for std::io::error::Error

impl Error for ExitStatusError

impl Error for RecvError

impl Error for AccessError

impl Error for SystemTimeError

impl Error for aho_corasick::util::error::BuildError

impl Error for aho_corasick::util::error::MatchError

impl Error for aho_corasick::util::primitives::PatternIDError

impl Error for aho_corasick::util::primitives::StateIDError

impl Error for bitflags::parser::ParseError

impl Error for bstr::ext_vec::FromUtf8Error

impl Error for bstr::utf8::Utf8Error

impl Error for FromPathBufError

impl Error for FromPathError

impl Error for cargo_platform::error::ParseError

impl Error for csv::deserializer::DeserializeError

impl Error for csv::error::Error

impl Error for csv::error::FromUtf8Error

impl Error for csv::error::Utf8Error

impl Error for WrongVariantError

impl Error for UnitError

impl Error for EmptyStrError

impl Error for NonAsciiError

impl Error for NonBmpError

impl Error for encode_unicode::errors::Utf8Error

impl Error for Utf16FirstUnitError

impl Error for CompressError

impl Error for DecompressError

impl Error for globset::Error

impl Error for GlobError

impl Error for RenderError

impl Error for handlebars::error::TemplateError

impl Error for idna::uts46::Errors

impl Error for indexmap::TryReserveError

impl Error for indicatif::style::TemplateError

impl Error for parse_display::ParseError

impl Error for parse_display::ParseError

impl Error for ThreadPoolBuildError

impl Error for regex_automata::dfa::onepass::BuildError

impl Error for regex_automata::hybrid::error::BuildError

impl Error for CacheError

impl Error for regex_automata::meta::error::BuildError

impl Error for regex_automata::nfa::thompson::error::BuildError

impl Error for GroupInfoError

impl Error for UnicodeWordBoundaryError

impl Error for regex_automata::util::primitives::PatternIDError

impl Error for SmallIndexError

impl Error for regex_automata::util::primitives::StateIDError

impl Error for regex_automata::util::search::MatchError

impl Error for PatternSetInsertError

impl Error for regex_automata::util::wire::DeserializeError

impl Error for SerializeError

impl Error for regex_syntax::ast::Error

impl Error for regex_syntax::hir::Error

impl Error for CaseFoldError

impl Error for UnicodeWordError

impl Error for Errno

impl Error for rustls_pki_types::server_name::AddrParseError

impl Error for InvalidDnsNameError

impl Error for UnsupportedOperationError

impl Error for OtherError

impl Error for semver::parse::Error

impl Error for serde::de::value::Error

impl Error for serde_json::error::Error

impl Error for TomlError

impl Error for Transport

impl Error for walkdir::error::Error

impl Error for UnsupportedPlatformError

impl<'a, K, V> Error for willbe::tool::btree_map::OccupiedError<'a, K, V>

where K: Debug + Ord, V: Debug,

impl<'a, K, V> Error for willbe::tool::hash_map::OccupiedError<'a, K, V>

where K: Debug, V: Debug,

impl<'a, T> Error for &'a T

where T: Error + ?Sized,

impl<E> Error for Box<E>

where E: Error,

impl<E, P> Error for combine::stream::decoder::Error<E, P>

where E: Error, P: Display + Debug,

impl<I> Error for willbe::iter::iter_tools::dependency::itertools::ExactlyOneError<I>

where I: Iterator + Debug, <I as Iterator>::Item: Debug,

impl<I> Error for itertools::exactly_one_err::ExactlyOneError<I>

where I: Iterator + Debug, <I as Iterator>::Item: Debug,

impl<L, R> Error for Either<L, R>

where L: Error, R: Error,

Either implements Error if both L and R implement it.

impl<R> Error for ErrorVariant<R>

where ErrorVariant<R>: Debug + Display,

impl<R> Error for pest::error::Error<R>

where Error<R>: Debug + Display,

impl<T> Error for SendTimeoutError<T>

impl<T> Error for TrySendError<T>

impl<T> Error for std::sync::poison::TryLockError<T>

impl<T> Error for ThinBox<T>

where T: Error + ?Sized,

impl<T> Error for Arc<T>

where T: Error + ?Sized,

impl<T> Error for SendError<T>

impl<T> Error for PoisonError<T>

impl<T> Error for TryIntoError<T>

where T: Debug,

impl<T, R, P> Error for combine::stream::easy::Errors<T, R, P>

where P: Display + Debug, T: Display + Debug, R: Display + Debug,

impl<W> Error for std::io::buffered::IntoInnerError<W>

where W: Send + Debug,

impl<W> Error for csv::error::IntoInnerError<W>

where W: Any,