error/
lib.rs

1#![no_std]
2
3#[cfg(feature = "std")]
4extern crate std;
5
6use core::fmt::*;
7
8#[cfg(feature = "std")]
9pub use std::error::Error;
10
11#[cfg(not(feature = "std"))]
12/// `Error` is a trait representing the basic expectations for error values,
13/// i.e., values of type `E` in [`Result<T, E>`]. Errors must describe
14/// themselves through the [`Display`] and [`Debug`] traits, and may provide
15/// cause chain information:
16///
17/// The [`source`] method is generally used when errors cross "abstraction
18/// boundaries". If one module must report an error that is caused by an error
19/// from a lower-level module, it can allow access to that error via the
20/// [`source`] method. This makes it possible for the high-level module to
21/// provide its own errors while also revealing some of the implementation for
22/// debugging via [`source`] chains.
23///
24/// [`source`]: trait.Error.html#method.source
25pub trait Error: Debug + Display {
26    /// The lower-level source of this error, if any.
27    ///
28    /// # Examples
29    ///
30    /// ```
31    /// use std::error::Error;
32    /// use std::fmt;
33    ///
34    /// #[derive(Debug)]
35    /// struct SuperError {
36    ///     side: SuperErrorSideKick,
37    /// }
38    ///
39    /// impl fmt::Display for SuperError {
40    ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
41    ///         write!(f, "SuperError is here!")
42    ///     }
43    /// }
44    ///
45    /// impl Error for SuperError {
46    ///     fn source(&self) -> Option<&(dyn Error + 'static)> {
47    ///         Some(&self.side)
48    ///     }
49    /// }
50    ///
51    /// #[derive(Debug)]
52    /// struct SuperErrorSideKick;
53    ///
54    /// impl fmt::Display for SuperErrorSideKick {
55    ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
56    ///         write!(f, "SuperErrorSideKick is here!")
57    ///     }
58    /// }
59    ///
60    /// impl Error for SuperErrorSideKick {}
61    ///
62    /// fn get_super_error() -> Result<(), SuperError> {
63    ///     Err(SuperError { side: SuperErrorSideKick })
64    /// }
65    ///
66    /// fn main() {
67    ///     match get_super_error() {
68    ///         Err(e) => {
69    ///             println!("Error: {}", e);
70    ///             println!("Caused by: {}", e.source().unwrap());
71    ///         }
72    ///         _ => println!("No error"),
73    ///     }
74    /// }
75    /// ```
76    fn source(&self) -> Option<&(dyn Error + 'static)> {
77        None
78    }
79
80    /// ```
81    /// if let Err(e) = "xc".parse::<u32>() {
82    ///     // Print `e` itself, no need for description().
83    ///     eprintln!("Error: {}", e);
84    /// }
85    /// ```
86    #[deprecated(since = "1.42.0", note = "use `Display`")]
87    fn description(&self) -> &str { "description() is deprecated; use Display" }
88
89    #[deprecated(since = "1.33.0", note = "obsoleted by Error::source, which can support downcasting")]
90    #[allow(missing_docs)]
91    fn cause(&self) -> Option<&dyn Error> { self.source() }
92}
error/lib.rs

error/
lib.rs
