1 #![doc = include_str!("error.md")]
2 #![unstable(feature = "error_in_core", issue = "103765")]
7 use crate::any::{Demand, Provider, TypeId};
8 use crate::fmt::{Debug, Display};
10 /// `Error` is a trait representing the basic expectations for error values,
11 /// i.e., values of type `E` in [`Result<T, E>`].
13 /// Errors must describe themselves through the [`Display`] and [`Debug`]
14 /// traits. Error messages are typically concise lowercase sentences without
15 /// trailing punctuation:
18 /// let err = "NaN".parse::<u32>().unwrap_err();
19 /// assert_eq!(err.to_string(), "invalid digit found in string");
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.
37 /// use std::error::Error;
41 /// struct SuperError {
42 /// source: SuperErrorSideKick,
45 /// impl fmt::Display for SuperError {
46 /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
47 /// write!(f, "SuperError is here!")
51 /// impl Error for SuperError {
52 /// fn source(&self) -> Option<&(dyn Error + 'static)> {
53 /// Some(&self.source)
58 /// struct SuperErrorSideKick;
60 /// impl fmt::Display for SuperErrorSideKick {
61 /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
62 /// write!(f, "SuperErrorSideKick is here!")
66 /// impl Error for SuperErrorSideKick {}
68 /// fn get_super_error() -> Result<(), SuperError> {
69 /// Err(SuperError { source: SuperErrorSideKick })
73 /// match get_super_error() {
75 /// println!("Error: {e}");
76 /// println!("Caused by: {}", e.source().unwrap());
78 /// _ => println!("No error"),
82 #[stable(feature = "error_source", since = "1.30.0")]
83 fn source(&self) -> Option<&(dyn Error + 'static)> {
87 /// Gets the `TypeId` of `self`.
90 feature = "error_type_id",
91 reason = "this is memory-unsafe to override in user code",
94 fn type_id(&self, _: private::Internal) -> TypeId
102 /// if let Err(e) = "xc".parse::<u32>() {
103 /// // Print `e` itself, no need for description().
104 /// eprintln!("Error: {e}");
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"
113 #[stable(feature = "rust1", since = "1.0.0")]
116 note = "replaced by Error::source, which can support downcasting"
118 #[allow(missing_docs)]
119 fn cause(&self) -> Option<&dyn Error> {
123 /// Provides type based access to context intended for error reports.
125 /// Used in conjunction with [`Demand::provide_value`] and [`Demand::provide_ref`] to extract
126 /// references to member variables from `dyn Error` trait objects.
131 /// #![feature(provide_any)]
132 /// #![feature(error_generic_member_access)]
134 /// use core::any::Demand;
137 /// struct MyBacktrace {
141 /// impl MyBacktrace {
142 /// fn new() -> MyBacktrace {
149 /// struct SourceError {
153 /// impl fmt::Display for SourceError {
154 /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
155 /// write!(f, "Example Source Error")
159 /// impl std::error::Error for SourceError {}
163 /// source: SourceError,
164 /// backtrace: MyBacktrace,
167 /// impl fmt::Display for Error {
168 /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
169 /// write!(f, "Example Error")
173 /// impl std::error::Error for Error {
174 /// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
176 /// .provide_ref::<MyBacktrace>(&self.backtrace)
177 /// .provide_ref::<dyn std::error::Error + 'static>(&self.source);
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();
188 /// assert!(core::ptr::eq(&error.backtrace, backtrace_ref));
191 #[unstable(feature = "error_generic_member_access", issue = "99301")]
192 #[allow(unused_variables)]
193 fn provide<'a>(&'a self, demand: &mut Demand<'a>) {}
196 #[unstable(feature = "error_generic_member_access", issue = "99301")]
197 impl<E> Provider for E
201 fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
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")]
214 #[unstable(feature = "never_type", issue = "35121")]
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)
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)
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")]
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>();
240 // Get `TypeId` of the type in the trait object (`self`).
241 let concrete = self.type_id(private::Internal);
243 // Compare both `TypeId`s on equality.
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")]
251 pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T> {
253 // SAFETY: `is` ensures this type cast is correct
254 unsafe { Some(&*(self as *const dyn Error as *const T)) }
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")]
264 pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T> {
266 // SAFETY: `is` ensures this type cast is correct
267 unsafe { Some(&mut *(self as *mut dyn Error as *mut T)) }
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")]
278 pub fn is<T: Error + 'static>(&self) -> bool {
279 <dyn Error + 'static>::is::<T>(self)
282 /// Forwards to the method defined on the type `dyn Error`.
283 #[stable(feature = "error_downcast", since = "1.3.0")]
285 pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T> {
286 <dyn Error + 'static>::downcast_ref::<T>(self)
289 /// Forwards to the method defined on the type `dyn Error`.
290 #[stable(feature = "error_downcast", since = "1.3.0")]
292 pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T> {
293 <dyn Error + 'static>::downcast_mut::<T>(self)
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)
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)
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")]
313 pub fn is<T: Error + 'static>(&self) -> bool {
314 <dyn Error + 'static>::is::<T>(self)
317 /// Forwards to the method defined on the type `dyn Error`.
318 #[stable(feature = "error_downcast", since = "1.3.0")]
320 pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T> {
321 <dyn Error + 'static>::downcast_ref::<T>(self)
324 /// Forwards to the method defined on the type `dyn Error`.
325 #[stable(feature = "error_downcast", since = "1.3.0")]
327 pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T> {
328 <dyn Error + 'static>::downcast_mut::<T>(self)
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)
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)
345 /// Returns an iterator starting with the current error and continuing with
346 /// recursively calling [`Error::source`].
348 /// If you want to omit the current error and only use its sources,
354 /// #![feature(error_iter)]
355 /// use std::error::Error;
362 /// struct B(Option<Box<dyn Error + 'static>>);
364 /// impl fmt::Display for A {
365 /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
370 /// impl fmt::Display for B {
371 /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
376 /// impl Error for A {}
378 /// impl Error for B {
379 /// fn source(&self) -> Option<&(dyn Error + 'static)> {
380 /// self.0.as_ref().map(|e| e.as_ref())
384 /// let b = B(Some(Box::new(A)));
386 /// // let err : Box<Error> = b.into(); // or
387 /// let err = &b as &(dyn Error);
389 /// let mut iter = err.sources();
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());
396 #[unstable(feature = "error_iter", issue = "58520")]
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.
410 Source { current: Some(self) }
414 /// An iterator over an [`Error`] and its sources.
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)>,
424 #[unstable(feature = "error_iter", issue = "58520")]
425 impl<'a> Iterator for Source<'a> {
426 type Item = &'a (dyn Error + 'static);
428 fn next(&mut self) -> Option<Self::Item> {
429 let current = self.current;
430 self.current = self.current.and_then(Error::source);
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)
443 fn cause(&self) -> Option<&dyn Error> {
444 Error::cause(&**self)
447 fn source(&self) -> Option<&(dyn Error + 'static)> {
448 Error::source(&**self)
451 fn provide<'b>(&'b self, demand: &mut Demand<'b>) {
452 Error::provide(&**self, demand);
456 #[stable(feature = "fmt_error", since = "1.11.0")]
457 impl Error for crate::fmt::Error {
459 fn description(&self) -> &str {
460 "an error occurred when formatting an argument"
464 #[stable(feature = "try_borrow", since = "1.13.0")]
465 impl Error for crate::cell::BorrowError {
467 fn description(&self) -> &str {
468 "already mutably borrowed"
472 #[stable(feature = "try_borrow", since = "1.13.0")]
473 impl Error for crate::cell::BorrowMutError {
475 fn description(&self) -> &str {
480 #[stable(feature = "try_from", since = "1.34.0")]
481 impl Error for crate::char::CharTryFromError {
483 fn description(&self) -> &str {
484 "converted integer out of range for `char`"
488 #[stable(feature = "char_from_str", since = "1.20.0")]
489 impl Error for crate::char::ParseCharError {
491 fn description(&self) -> &str {
496 #[stable(feature = "duration_checked_float", since = "1.66.0")]
497 impl Error for crate::time::TryFromFloatSecsError {}
499 #[stable(feature = "frombyteswithnulerror_impls", since = "1.17.0")]
500 impl Error for crate::ffi::FromBytesWithNulError {
502 fn description(&self) -> &str {
507 #[unstable(feature = "cstr_from_bytes_until_nul", issue = "95027")]
508 impl Error for crate::ffi::FromBytesUntilNulError {}