library/core/src/error.rs

   1 #![doc = include_str!("error.md")]
   2 #![unstable(feature = "error_in_core", issue = "103765")]
   3
   4 #[cfg(test)]
   5 mod tests;
   6
   7 use crate::any::{Demand, Provider, TypeId};
   8 use crate::fmt::{Debug, Display};
   9
  10 /// `Error` is a trait representing the basic expectations for error values,
  11 /// i.e., values of type `E` in [`Result<T, E>`].
  12 ///
  13 /// Errors must describe themselves through the [`Display`] and [`Debug`]
  14 /// traits. Error messages are typically concise lowercase sentences without
  15 /// trailing punctuation:
  16 ///
  17 /// ```
  18 /// let err = "NaN".parse::<u32>().unwrap_err();
  19 /// assert_eq!(err.to_string(), "invalid digit found in string");
  20 /// ```
  21 ///
  22 /// Errors may provide cause information. [`Error::source()`] is generally
  23 /// used when errors cross "abstraction boundaries". If one module must report
  24 /// an error that is caused by an error from a lower-level module, it can allow
  25 /// accessing that error via [`Error::source()`]. This makes it possible for the
  26 /// high-level module to provide its own errors while also revealing some of the
  27 /// implementation for debugging.
  28 #[stable(feature = "rust1", since = "1.0.0")]
  29 #[cfg_attr(not(test), rustc_diagnostic_item = "Error")]
  30 #[rustc_has_incoherent_inherent_impls]
  31 pub trait Error: Debug + Display {
  32     /// The lower-level source of this error, if any.
  33     ///
  34     /// # Examples
  35     ///
  36     /// ```
  37     /// use std::error::Error;
  38     /// use std::fmt;
  39     ///
  40     /// #[derive(Debug)]
  41     /// struct SuperError {
  42     ///     source: SuperErrorSideKick,
  43     /// }
  44     ///
  45     /// impl fmt::Display for SuperError {
  46     ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  47     ///         write!(f, "SuperError is here!")
  48     ///     }
  49     /// }
  50     ///
  51     /// impl Error for SuperError {
  52     ///     fn source(&self) -> Option<&(dyn Error + 'static)> {
  53     ///         Some(&self.source)
  54     ///     }
  55     /// }
  56     ///
  57     /// #[derive(Debug)]
  58     /// struct SuperErrorSideKick;
  59     ///
  60     /// impl fmt::Display for SuperErrorSideKick {
  61     ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  62     ///         write!(f, "SuperErrorSideKick is here!")
  63     ///     }
  64     /// }
  65     ///
  66     /// impl Error for SuperErrorSideKick {}
  67     ///
  68     /// fn get_super_error() -> Result<(), SuperError> {
  69     ///     Err(SuperError { source: SuperErrorSideKick })
  70     /// }
  71     ///
  72     /// fn main() {
  73     ///     match get_super_error() {
  74     ///         Err(e) => {
  75     ///             println!("Error: {e}");
  76     ///             println!("Caused by: {}", e.source().unwrap());
  77     ///         }
  78     ///         _ => println!("No error"),
  79     ///     }
  80     /// }
  81     /// ```
  82     #[stable(feature = "error_source", since = "1.30.0")]
  83     fn source(&self) -> Option<&(dyn Error + 'static)> {
  84         None
  85     }
  86
  87     /// Gets the `TypeId` of `self`.
  88     #[doc(hidden)]
  89     #[unstable(
  90         feature = "error_type_id",
  91         reason = "this is memory-unsafe to override in user code",
  92         issue = "60784"
  93     )]
  94     fn type_id(&self, _: private::Internal) -> TypeId
  95     where
  96         Self: 'static,
  97     {
  98         TypeId::of::<Self>()
  99     }
 100
 101     /// ```
 102     /// if let Err(e) = "xc".parse::<u32>() {
 103     ///     // Print `e` itself, no need for description().
 104     ///     eprintln!("Error: {e}");
 105     /// }
 106     /// ```
 107     #[stable(feature = "rust1", since = "1.0.0")]
 108     #[deprecated(since = "1.42.0", note = "use the Display impl or to_string()")]
 109     fn description(&self) -> &str {
 110         "description() is deprecated; use Display"
 111     }
 112
 113     #[stable(feature = "rust1", since = "1.0.0")]
 114     #[deprecated(
 115         since = "1.33.0",
 116         note = "replaced by Error::source, which can support downcasting"
 117     )]
 118     #[allow(missing_docs)]
 119     fn cause(&self) -> Option<&dyn Error> {
 120         self.source()
 121     }
 122
 123     /// Provides type based access to context intended for error reports.
 124     ///
 125     /// Used in conjunction with [`Demand::provide_value`] and [`Demand::provide_ref`] to extract
 126     /// references to member variables from `dyn Error` trait objects.
 127     ///
 128     /// # Example
 129     ///
 130     /// ```rust
 131     /// #![feature(provide_any)]
 132     /// #![feature(error_generic_member_access)]
 133     /// use core::fmt;
 134     /// use core::any::Demand;
 135     ///
 136     /// #[derive(Debug)]
 137     /// struct MyBacktrace {
 138     ///     // ...
 139     /// }
 140     ///
 141     /// impl MyBacktrace {
 142     ///     fn new() -> MyBacktrace {
 143     ///         // ...
 144     ///         # MyBacktrace {}
 145     ///     }
 146     /// }
 147     ///
 148     /// #[derive(Debug)]
 149     /// struct SourceError {
 150     ///     // ...
 151     /// }
 152     ///
 153     /// impl fmt::Display for SourceError {
 154     ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 155     ///         write!(f, "Example Source Error")
 156     ///     }
 157     /// }
 158     ///
 159     /// impl std::error::Error for SourceError {}
 160     ///
 161     /// #[derive(Debug)]
 162     /// struct Error {
 163     ///     source: SourceError,
 164     ///     backtrace: MyBacktrace,
 165     /// }
 166     ///
 167     /// impl fmt::Display for Error {
 168     ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 169     ///         write!(f, "Example Error")
 170     ///     }
 171     /// }
 172     ///
 173     /// impl std::error::Error for Error {
 174     ///     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
 175     ///         demand
 176     ///             .provide_ref::<MyBacktrace>(&self.backtrace)
 177     ///             .provide_ref::<dyn std::error::Error + 'static>(&self.source);
 178     ///     }
 179     /// }
 180     ///
 181     /// fn main() {
 182     ///     let backtrace = MyBacktrace::new();
 183     ///     let source = SourceError {};
 184     ///     let error = Error { source, backtrace };
 185     ///     let dyn_error = &error as &dyn std::error::Error;
 186     ///     let backtrace_ref = dyn_error.request_ref::<MyBacktrace>().unwrap();
 187     ///
 188     ///     assert!(core::ptr::eq(&error.backtrace, backtrace_ref));
 189     /// }
 190     /// ```
 191     #[unstable(feature = "error_generic_member_access", issue = "99301")]
 192     #[allow(unused_variables)]
 193     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {}
 194 }
 195
 196 #[unstable(feature = "error_generic_member_access", issue = "99301")]
 197 impl<E> Provider for E
 198 where
 199     E: Error + ?Sized,
 200 {
 201     fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
 202         self.provide(demand)
 203     }
 204 }
 205
 206 mod private {
 207     // This is a hack to prevent `type_id` from being overridden by `Error`
 208     // implementations, since that can enable unsound downcasting.
 209     #[unstable(feature = "error_type_id", issue = "60784")]
 210     #[derive(Debug)]
 211     pub struct Internal;
 212 }
 213
 214 #[unstable(feature = "never_type", issue = "35121")]
 215 impl Error for ! {}
 216
 217 impl<'a> dyn Error + 'a {
 218     /// Request a reference of type `T` as context about this error.
 219     #[unstable(feature = "error_generic_member_access", issue = "99301")]
 220     pub fn request_ref<T: ?Sized + 'static>(&'a self) -> Option<&'a T> {
 221         core::any::request_ref(self)
 222     }
 223
 224     /// Request a value of type `T` as context about this error.
 225     #[unstable(feature = "error_generic_member_access", issue = "99301")]
 226     pub fn request_value<T: 'static>(&'a self) -> Option<T> {
 227         core::any::request_value(self)
 228     }
 229 }
 230
 231 // Copied from `any.rs`.
 232 impl dyn Error + 'static {
 233     /// Returns `true` if the inner type is the same as `T`.
 234     #[stable(feature = "error_downcast", since = "1.3.0")]
 235     #[inline]
 236     pub fn is<T: Error + 'static>(&self) -> bool {
 237         // Get `TypeId` of the type this function is instantiated with.
 238         let t = TypeId::of::<T>();
 239
 240         // Get `TypeId` of the type in the trait object (`self`).
 241         let concrete = self.type_id(private::Internal);
 242
 243         // Compare both `TypeId`s on equality.
 244         t == concrete
 245     }
 246
 247     /// Returns some reference to the inner value if it is of type `T`, or
 248     /// `None` if it isn't.
 249     #[stable(feature = "error_downcast", since = "1.3.0")]
 250     #[inline]
 251     pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T> {
 252         if self.is::<T>() {
 253             // SAFETY: `is` ensures this type cast is correct
 254             unsafe { Some(&*(self as *const dyn Error as *const T)) }
 255         } else {
 256             None
 257         }
 258     }
 259
 260     /// Returns some mutable reference to the inner value if it is of type `T`, or
 261     /// `None` if it isn't.
 262     #[stable(feature = "error_downcast", since = "1.3.0")]
 263     #[inline]
 264     pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T> {
 265         if self.is::<T>() {
 266             // SAFETY: `is` ensures this type cast is correct
 267             unsafe { Some(&mut *(self as *mut dyn Error as *mut T)) }
 268         } else {
 269             None
 270         }
 271     }
 272 }
 273
 274 impl dyn Error + 'static + Send {
 275     /// Forwards to the method defined on the type `dyn Error`.
 276     #[stable(feature = "error_downcast", since = "1.3.0")]
 277     #[inline]
 278     pub fn is<T: Error + 'static>(&self) -> bool {
 279         <dyn Error + 'static>::is::<T>(self)
 280     }
 281
 282     /// Forwards to the method defined on the type `dyn Error`.
 283     #[stable(feature = "error_downcast", since = "1.3.0")]
 284     #[inline]
 285     pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T> {
 286         <dyn Error + 'static>::downcast_ref::<T>(self)
 287     }
 288
 289     /// Forwards to the method defined on the type `dyn Error`.
 290     #[stable(feature = "error_downcast", since = "1.3.0")]
 291     #[inline]
 292     pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T> {
 293         <dyn Error + 'static>::downcast_mut::<T>(self)
 294     }
 295
 296     /// Request a reference of type `T` as context about this error.
 297     #[unstable(feature = "error_generic_member_access", issue = "99301")]
 298     pub fn request_ref<T: ?Sized + 'static>(&self) -> Option<&T> {
 299         <dyn Error>::request_ref(self)
 300     }
 301
 302     /// Request a value of type `T` as context about this error.
 303     #[unstable(feature = "error_generic_member_access", issue = "99301")]
 304     pub fn request_value<T: 'static>(&self) -> Option<T> {
 305         <dyn Error>::request_value(self)
 306     }
 307 }
 308
 309 impl dyn Error + 'static + Send + Sync {
 310     /// Forwards to the method defined on the type `dyn Error`.
 311     #[stable(feature = "error_downcast", since = "1.3.0")]
 312     #[inline]
 313     pub fn is<T: Error + 'static>(&self) -> bool {
 314         <dyn Error + 'static>::is::<T>(self)
 315     }
 316
 317     /// Forwards to the method defined on the type `dyn Error`.
 318     #[stable(feature = "error_downcast", since = "1.3.0")]
 319     #[inline]
 320     pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T> {
 321         <dyn Error + 'static>::downcast_ref::<T>(self)
 322     }
 323
 324     /// Forwards to the method defined on the type `dyn Error`.
 325     #[stable(feature = "error_downcast", since = "1.3.0")]
 326     #[inline]
 327     pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T> {
 328         <dyn Error + 'static>::downcast_mut::<T>(self)
 329     }
 330
 331     /// Request a reference of type `T` as context about this error.
 332     #[unstable(feature = "error_generic_member_access", issue = "99301")]
 333     pub fn request_ref<T: ?Sized + 'static>(&self) -> Option<&T> {
 334         <dyn Error>::request_ref(self)
 335     }
 336
 337     /// Request a value of type `T` as context about this error.
 338     #[unstable(feature = "error_generic_member_access", issue = "99301")]
 339     pub fn request_value<T: 'static>(&self) -> Option<T> {
 340         <dyn Error>::request_value(self)
 341     }
 342 }
 343
 344 impl dyn Error {
 345     /// Returns an iterator starting with the current error and continuing with
 346     /// recursively calling [`Error::source`].
 347     ///
 348     /// If you want to omit the current error and only use its sources,
 349     /// use `skip(1)`.
 350     ///
 351     /// # Examples
 352     ///
 353     /// ```
 354     /// #![feature(error_iter)]
 355     /// use std::error::Error;
 356     /// use std::fmt;
 357     ///
 358     /// #[derive(Debug)]
 359     /// struct A;
 360     ///
 361     /// #[derive(Debug)]
 362     /// struct B(Option<Box<dyn Error + 'static>>);
 363     ///
 364     /// impl fmt::Display for A {
 365     ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 366     ///         write!(f, "A")
 367     ///     }
 368     /// }
 369     ///
 370     /// impl fmt::Display for B {
 371     ///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 372     ///         write!(f, "B")
 373     ///     }
 374     /// }
 375     ///
 376     /// impl Error for A {}
 377     ///
 378     /// impl Error for B {
 379     ///     fn source(&self) -> Option<&(dyn Error + 'static)> {
 380     ///         self.0.as_ref().map(|e| e.as_ref())
 381     ///     }
 382     /// }
 383     ///
 384     /// let b = B(Some(Box::new(A)));
 385     ///
 386     /// // let err : Box<Error> = b.into(); // or
 387     /// let err = &b as &(dyn Error);
 388     ///
 389     /// let mut iter = err.sources();
 390     ///
 391     /// assert_eq!("B".to_string(), iter.next().unwrap().to_string());
 392     /// assert_eq!("A".to_string(), iter.next().unwrap().to_string());
 393     /// assert!(iter.next().is_none());
 394     /// assert!(iter.next().is_none());
 395     /// ```
 396     #[unstable(feature = "error_iter", issue = "58520")]
 397     #[inline]
 398     pub fn sources(&self) -> Source<'_> {
 399         // You may think this method would be better in the Error trait, and you'd be right.
 400         // Unfortunately that doesn't work, not because of the object safety rules but because we
 401         // save a reference to self in Sources below as a trait object. If this method was
 402         // declared in Error, then self would have the type &T where T is some concrete type which
 403         // implements Error. We would need to coerce self to have type &dyn Error, but that requires
 404         // that Self has a known size (i.e., Self: Sized). We can't put that bound on Error
 405         // since that would forbid Error trait objects, and we can't put that bound on the method
 406         // because that means the method can't be called on trait objects (we'd also need the
 407         // 'static bound, but that isn't allowed because methods with bounds on Self other than
 408         // Sized are not object-safe). Requiring an Unsize bound is not backwards compatible.
 409
 410         Source { current: Some(self) }
 411     }
 412 }
 413
 414 /// An iterator over an [`Error`] and its sources.
 415 ///
 416 /// If you want to omit the initial error and only process
 417 /// its sources, use `skip(1)`.
 418 #[unstable(feature = "error_iter", issue = "58520")]
 419 #[derive(Clone, Debug)]
 420 pub struct Source<'a> {
 421     current: Option<&'a (dyn Error + 'static)>,
 422 }
 423
 424 #[unstable(feature = "error_iter", issue = "58520")]
 425 impl<'a> Iterator for Source<'a> {
 426     type Item = &'a (dyn Error + 'static);
 427
 428     fn next(&mut self) -> Option<Self::Item> {
 429         let current = self.current;
 430         self.current = self.current.and_then(Error::source);
 431         current
 432     }
 433 }
 434
 435 #[stable(feature = "error_by_ref", since = "1.51.0")]
 436 impl<'a, T: Error + ?Sized> Error for &'a T {
 437     #[allow(deprecated, deprecated_in_future)]
 438     fn description(&self) -> &str {
 439         Error::description(&**self)
 440     }
 441
 442     #[allow(deprecated)]
 443     fn cause(&self) -> Option<&dyn Error> {
 444         Error::cause(&**self)
 445     }
 446
 447     fn source(&self) -> Option<&(dyn Error + 'static)> {
 448         Error::source(&**self)
 449     }
 450
 451     fn provide<'b>(&'b self, demand: &mut Demand<'b>) {
 452         Error::provide(&**self, demand);
 453     }
 454 }
 455
 456 #[stable(feature = "fmt_error", since = "1.11.0")]
 457 impl Error for crate::fmt::Error {
 458     #[allow(deprecated)]
 459     fn description(&self) -> &str {
 460         "an error occurred when formatting an argument"
 461     }
 462 }
 463
 464 #[stable(feature = "try_borrow", since = "1.13.0")]
 465 impl Error for crate::cell::BorrowError {
 466     #[allow(deprecated)]
 467     fn description(&self) -> &str {
 468         "already mutably borrowed"
 469     }
 470 }
 471
 472 #[stable(feature = "try_borrow", since = "1.13.0")]
 473 impl Error for crate::cell::BorrowMutError {
 474     #[allow(deprecated)]
 475     fn description(&self) -> &str {
 476         "already borrowed"
 477     }
 478 }
 479
 480 #[stable(feature = "try_from", since = "1.34.0")]
 481 impl Error for crate::char::CharTryFromError {
 482     #[allow(deprecated)]
 483     fn description(&self) -> &str {
 484         "converted integer out of range for `char`"
 485     }
 486 }
 487
 488 #[stable(feature = "char_from_str", since = "1.20.0")]
 489 impl Error for crate::char::ParseCharError {
 490     #[allow(deprecated)]
 491     fn description(&self) -> &str {
 492         self.__description()
 493     }
 494 }
 495
 496 #[stable(feature = "duration_checked_float", since = "1.66.0")]
 497 impl Error for crate::time::TryFromFloatSecsError {}
 498
 499 #[stable(feature = "frombyteswithnulerror_impls", since = "1.17.0")]
 500 impl Error for crate::ffi::FromBytesWithNulError {
 501     #[allow(deprecated)]
 502     fn description(&self) -> &str {
 503         self.__description()
 504     }
 505 }
 506
 507 #[unstable(feature = "cstr_from_bytes_until_nul", issue = "95027")]
 508 impl Error for crate::ffi::FromBytesUntilNulError {}
 509
 510 #[unstable(feature = "get_many_mut", issue = "104642")]
 511 impl<const N: usize> Error for crate::slice::GetManyMutError<N> {}