Skip to main content

error_kind/traits/
error_kind.rs

1// =============================================================================
2// USES
3// =============================================================================
4
5// -----------------------------------------------------------------------------
6use crate::details::StaticString;
7use crate::envelopes::ErrorEnvelope;
8use crate::{Context, ErrorContext};
9use core::fmt::{Debug, Display};
10
11// =============================================================================
12// TRAITS
13// =============================================================================
14
15/// A marker trait for a type that denotes a kind of error that took place.
16///
17/// These types are expected to be very simple enums, which contain only unit
18/// variants denoting the kind of error that occurred.
19///
20/// If you want to compose an `ErrorKind` which is a combination of multiple
21/// different `ErrorKind`, see the [`ErrorDomain`] trait.
22///
23/// [`ErrorDomain`]: crate::ErrorDomain
24///
25/// # Display Formatting
26///
27/// The derive macro for this trait will automatically implement `Display` for
28/// you. The default process is to break the variant name into words, lowercase
29/// it, and then separate the words by spaces.
30///
31/// ```rust
32/// # use error_kind::ErrorKind;
33/// #[derive(Clone, Copy, Debug, ErrorKind)]
34/// enum IoErrorKind {
35///     BadFileDescriptor, // Prints "bad file descriptor"
36///     FileNotFound,      // Prints "file not found"
37///     // ...
38/// }
39/// ```
40///
41/// If you don't like a particular display format, you can change it with the
42/// `#[error(...)]` attribute on a variant.
43///
44/// ```rust
45/// # use error_kind::ErrorKind;
46/// #[derive(Clone, Copy, Debug, ErrorKind)]
47/// enum IoErrorKind {
48///     BadFileDescriptor, // Prints "bad file descriptor"
49///     #[error("custom display")]
50///     FileNotFound,      // Prints "custom display"
51///     // ...
52/// }
53/// ```
54///
55/// # Examples
56///
57/// An error kind denotes a set of semantically related errors.
58///
59/// ```rust
60/// # use error_kind::ErrorKind;
61/// #[derive(Clone, Copy, Debug, ErrorKind)]
62/// enum IoErrorKind {
63///     BadFileDescriptor,
64///     FileNotFound,
65///     // ...
66/// }
67/// ```
68///
69/// You can define multiple kinds of errors by creating separate enums.
70///
71/// ```rust
72/// # use error_kind::ErrorKind;
73/// #[derive(Clone, Copy, Debug, ErrorKind)]
74/// enum IoErrorKind {
75///     BadFileDescriptor,
76///     FileNotFound,
77///     // ...
78/// }
79///
80/// #[derive(Clone, Copy, Debug, ErrorKind)]
81/// enum ParseErrorKind {
82///     InvalidFormat,
83///     UnexpectedEndOfData,
84///     // ...
85/// }
86/// ```
87pub trait ErrorKind: Clone + Copy + Debug + Display {}
88
89// =============================================================================
90// TRAIT IMPLS
91// =============================================================================
92
93// -----------------------------------------------------------------------------
94impl<K: ErrorKind> ErrorEnvelope for K {
95    type Kind = Self;
96    type Envelope<T: ErrorKind> = T;
97
98    #[track_caller]
99    #[inline(always)]
100    fn convert<T>(self) -> Self::Envelope<T>
101    where
102        T: ErrorKind + From<Self::Kind>,
103    {
104        From::from(self)
105    }
106
107    #[inline(always)]
108    fn error_kind(&self) -> Self::Kind {
109        *self
110    }
111
112    #[inline(always)]
113    fn new(kind: Self::Kind) -> Self {
114        kind
115    }
116
117    #[inline(always)]
118    fn with_description<S>(kind: Self::Kind, _description: S) -> Self
119    where
120        S: StaticString,
121    {
122        kind
123    }
124}
125
126// -----------------------------------------------------------------------------
127impl<K: ErrorKind> ErrorContext for K {
128    #[track_caller]
129    #[inline(always)]
130    fn with_context<C, F>(self, _context: F) -> Self
131    where
132        C: Context,
133        F: FnOnce() -> C,
134    {
135        self
136    }
137}