Trait Error

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>) { ... }
}

core A trait representing the basic expectations for error values.

Re-exported from core::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 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

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<'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;
use std::mem;

let a_str_error = "a str error";
let a_boxed_error = Box::<dyn Error>::from(a_str_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::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;
use std::mem;

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

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::mem;
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!(mem::size_of::<Box<dyn Error>>() == mem::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::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))

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;
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))

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;
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))

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;
use std::mem;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error>::from(a_string_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::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;
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))

impl Pointee for dyn Error

type Metadata = DynMetadata<dyn Error>

The metadata type for pointers and references to this type.

impl Pointee for dyn Error + Send

type Metadata = DynMetadata<dyn Error + Send>

The metadata type for pointers and references to this type.

impl Pointee for dyn Error + Send + Sync

type Metadata = DynMetadata<dyn Error + Send + Sync>

The metadata type for pointers and references to this type.

impl Pointee for dyn Error + Sync

type Metadata = DynMetadata<dyn Error + Sync>

The metadata type for pointers and references to this type.

impl Value for dyn Error

fn record(&self, key: &Field, visitor: &mut dyn Visit)

Visits this value with the given Visitor.

impl Value for dyn Error + Send

fn record(&self, key: &Field, visitor: &mut dyn Visit)

Visits this value with the given Visitor.

impl Value for dyn Error + Send + Sync

fn record(&self, key: &Field, visitor: &mut dyn Visit)

Visits this value with the given Visitor.

impl Value for dyn Error + Sync

fn record(&self, key: &Field, visitor: &mut dyn Visit)

Visits this value with the given Visitor.

Implementors

impl !Error for &str

impl Error for GetManyMutError

impl Error for VarError

impl Error for RecvTimeoutError

impl Error for TryRecvError

impl Error for CheckedCastError

impl Error for PodCastError

impl Error for devela::_dep::kira::backend::cpal::Error

impl Error for FromFileError

impl Error for PortInfoError

impl Error for devela::_dep::midir::SendError

impl Error for ShaderError

impl Error for Panic

impl Error for BuildStreamError

impl Error for DefaultStreamConfigError

impl Error for DeviceNameError

impl Error for PauseStreamError

impl Error for PlayStreamError

impl Error for devela::_dep::rodio::cpal::StreamError

impl Error for SupportedStreamConfigsError

impl Error for DecoderError

impl Error for devela::_dep::rodio::decoder::symphonia::SeekError

impl Error for DevicesError

impl Error for PlayError

impl Error for devela::_dep::rodio::StreamError

impl Error for devela::_dep::rodio::source::SeekError

impl Error for devela::_dep::symphonia::core::errors::Error

impl Error for ErrorKind

impl Error for Infallible

impl Error for DataNotEnough

impl Error for MismatchedBounds

impl Error for PartialSpace

impl Error for NumError

impl Error for InvalidText

impl Error for devela::ui::LayoutError

Available on crate feature layout only.

impl Error for UiError

Available on ui·· only.

impl Error for AudioError

Available on crate feature audio only.

impl Error for ColorError

Available on crate feature color only.

impl Error for DrawError

Available on crate feature draw only.

impl Error for FontError

Available on crate feature font only.

impl Error for ImageError

Available on crate feature image only.

impl Error for MediaError

Available on media·· only.

impl Error for MidiError

Available on crate feature midi only.

impl Error for NotAvailable

impl Error for !

impl Error for AllocError

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 TryFromCharError

impl Error for FromBytesUntilNulError

impl Error for FromBytesWithNulError

impl Error for AddrParseError

impl Error for ParseBoolError

impl Error for Utf8Error

impl Error for UnorderedKeyError

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 JoinPathsError

impl Error for WriterPanicked

impl Error for ExitStatusError

impl Error for RecvError

impl Error for devela::_dep::_std::time::SystemTimeError

impl Error for devela::_dep::jiff::Error

impl Error for devela::_dep::js_sys::TryFromIntError

impl Error for ResourceLimitReached

impl Error for NonexistentRoute

impl Error for devela::_dep::log::ParseLevelError

impl Error for SetLoggerError

impl Error for InitError

impl Error for DowncastError<'_, '_>

impl Error for DowncastIntoError<'_>

impl Error for PyErr

impl Error for devela::_dep::rand_core::Error

impl Error for ThreadPoolBuildError

impl Error for devela::_dep::regex_lite::Error

impl Error for BoxedError

impl Error for devela::_dep::rkyv::bytecheck::rancor::Error

impl Error for Failure

impl Error for IteratorLengthMismatch

impl Error for BackendSpecificError

impl Error for HostUnavailable

impl Error for Errno

impl Error for devela::_dep::serde::de::value::Error

impl Error for SetGlobalDefaultError

impl Error for ParseLevelFilterError

impl Error for devela::_dep::tracing::metadata::ParseLevelError

impl Error for DataOverflow

impl Error for ElementNotFound

impl Error for IndexOutOfBounds

impl Error for InvalidAxisLength

impl Error for KeyAlreadyExists

impl Error for MismatchedCapacity

impl Error for MismatchedDimensions

impl Error for MismatchedIndices

impl Error for NodeEmpty

impl Error for NodeLinkNotSet

impl Error for NodeLinkNotUnique

impl Error for NotEnoughElements

impl Error for NotEnoughSpace

impl Error for PartiallyAdded

impl Error for TryFromFloatSecsError

impl Error for devela::phys::SystemTimeError

Available on crate feature std only.

impl Error for InvalidChar

impl Error for InvalidUtf8

impl Error for ParseFloatError

impl Error for ParseIntError

impl Error for AccessError

impl Error for getrandom::error::Error

impl Error for FailedErrorConversion

impl Error for devela::all::FmtError

impl Error for devela::all::IoError

impl Error for devela::all::LayoutError

impl Error for NotImplemented

impl Error for NotSupported

impl Error for StripPrefixError

impl Error for devela::all::TryFromIntError

impl Error for ArenaFull

impl Error for ChunkError

impl Error for Error

impl Error for InsertWithKeyError

impl Error for ParseError

impl Error for PeekError

impl Error for PopError

impl<'a, K, V> Error for devela::_dep::_alloc::collections::btree_map::OccupiedError<'a, K, V>

where K: Debug + Ord, V: Debug,

impl<'a, K, V> Error for devela::_dep::_std::collections::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 PlaySoundError<E>

where E: Debug,

impl<E> Error for Box<E>

where E: Error,

impl<I> Error for InputError<I>

where I: Clone + Debug + Display + Sync + Send + 'static,

impl<I, C> Error for TreeError<I, C>

where I: Stream + Clone + Debug + Display + Sync + Send + 'static, C: Display + Debug,

impl<T> Error for SendTimeoutError<T>

impl<T> Error for TrySendError<T>

impl<T> Error for TryLockError<T>

impl<T> Error for ThinBox<T>

where T: Error + ?Sized,

impl<T> Error for devela::_dep::_std::sync::mpmc::SendError<T>

impl<T> Error for ConnectError<T>

impl<T> Error for InvalidEnumDiscriminantError<T>

where T: Debug + Display,

impl<T> Error for Arc<T>

where T: Error + ?Sized,

impl<T> Error for PoisonError<T>

impl<T> Error for CapacityError<T>

where T: Any,

Requires features="std".

impl<T> Error for PushError<T>

impl<W> Error for IntoInnerError<W>

where W: Send + Debug,