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}