1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
// =============================================================================
// TRAITS
// =============================================================================
/// Denotes that two types are distinct from one-another.
///
/// Useful for adding a generic negative bounds on a fully-typed trait impl.
///
/// ```
/// # use error_kind::details::IsNot;
/// # struct Wrapper<T>(T);
/// # struct MyType;
/// impl<T> From<Wrapper<T>> for Wrapper<MyType>
/// where
/// T: IsNot<MyType>,
/// MyType: From<T>,
/// {
/// fn from(value: Wrapper<T>) -> Self {
/// Wrapper(From::from(value.0))
/// }
/// }
/// ```
///
/// `IsNot<T>` can only restrict trait bounds when `Self` is *fully-defined*
/// (non-generic).
///
/// This trait **will not help** if a generic type parameter is used in `Self`.
///
/// # Detailed Explanation
///
/// Trait bounds lack the ability to restrict types based on negative trait
/// bounds (`T: !Trait`). Likewise, trait bounds also lack the ability to
/// restrict types to only those not matching a given type (`T != Type`).
///
/// This leads to issues with blanket generic implementations. The most common
/// of which is the `From` trait. The standard library provides the following
/// default implementation.
///
/// ```
/// # trait From<T> { fn from(v: T) -> Self; }
/// impl<T> From<T> for T {
/// fn from(value: T) -> Self {
/// value
/// }
/// }
/// ```
///
/// This usually isn't an issue is because we implement over specific types. The
/// compiler is able to deduce that the two implementations don't conflict.
///
/// ```
/// # struct TypeA;
/// # struct TypeB;
/// // This is okay, since we are certain `TypeA` != `TypeB`.
/// // The implementation over `From<T> for T` is disjoint.
/// impl From<TypeA> for TypeB {
/// fn from(value: TypeA) -> Self {
/// # unimplemented!()
/// // ...
/// }
/// }
/// ```
///
/// Where it becomes annoying is when we have wrapping types. We often want to
/// be able to convert the inside of a wrapping type if the inner type supports
/// `From` conversion.
///
/// **But we cannot do this generically!**
///
/// ```compile_fail
/// # struct TypeA;
/// # struct TypeB;
/// # struct Wrapper<T>(T);
/// # impl From<TypeA> for TypeB { fn from(value: TypeA) -> Self { unimplemented!() } }
/// // This fails to compile...
/// impl<T: From<TypeA>> From<Wrapper<TypeA>> for Wrapper<T> {
/// fn from(value: Wrapper<TypeA>) -> Self {
/// Wrapper(From::from(value.0))
/// }
/// }
/// ```
///
/// ```compile_fail
/// # struct TypeA;
/// # struct TypeB;
/// # struct Wrapper<T>(T);
/// # impl From<TypeA> for TypeB { fn from(value: TypeA) -> Self { unimplemented!() } }
/// // This fails to compile...
/// impl<T> From<Wrapper<T>> for Wrapper<TypeA>
/// where
/// TypeA: From<T>,
/// {
/// fn from(value: Wrapper<T>) -> Self {
/// Wrapper(From::from(value.0))
/// }
/// }
/// ```
///
/// If we had defined the `Wrapper` type, then we can get around this in a
/// similar manner to `TypeA` and `TypeB`, by simply not using generics.
///
/// ```
/// # struct TypeA;
/// # struct TypeB;
/// # struct Wrapper<T>(T);
/// # impl From<TypeA> for TypeB { fn from(value: TypeA) -> Self { unimplemented!() } }
/// # impl From<TypeB> for TypeA { fn from(value: TypeB) -> Self { unimplemented!() } }
/// // These work because they're not generic *and* local types.
/// impl From<Wrapper<TypeA>> for Wrapper<TypeB> {
/// fn from(value: Wrapper<TypeA>) -> Self {
/// Wrapper(From::from(value.0))
/// }
/// }
/// impl From<Wrapper<TypeB>> for Wrapper<TypeA> {
/// fn from(value: Wrapper<TypeB>) -> Self {
/// Wrapper(From::from(value.0))
/// }
/// }
/// ```
///
/// But you cannot do this with types and traits that you haven't defined
/// locally within your crate.
///
/// ```compile_fail
/// # struct TypeA;
/// # struct TypeB;
/// # impl From<TypeA> for TypeB { fn from(value: TypeA) -> Self { unimplemented!() } }
/// # impl From<TypeB> for TypeA { fn from(value: TypeB) -> Self { unimplemented!() } }
/// // This doesn't work because `Option` and `From` are foreign.
/// impl From<Option<TypeA>> for Option<TypeB> {
/// fn from(value: Option<TypeA>) -> Self {
/// value.map(From::from)
/// }
/// }
/// ```
///
/// All this is an issue for this crate. The main way you ergonomically deal
/// with error handling is to allow for errors to convert between one-another.
///
/// We have exactly this issue where we have a wrapping type ([`Error`]), which
/// contains an underlying type ([`ErrorKind`]), and we need to support generic
/// conversion for the wrapping type.
///
/// At first glance, this seems to not work, even with the `IsNot` trait.
///
/// ```compile_fail
/// # struct TypeA;
/// # struct TypeB;
/// # struct Wrapper<T>(T);
/// # use error_kind::details::IsNot;
/// # impl From<TypeA> for TypeB { fn from(value: TypeA) -> Self { unimplemented!() } }
/// // Say that the types are distinct from each other...
/// impl IsNot<TypeA> for TypeB {}
/// impl IsNot<TypeB> for TypeA {}
///
/// // We still conflict with `From<T> for T`... :(
/// impl<T, U> From<Wrapper<T>> for Wrapper<U>
/// where
/// T: IsNot<U>,
/// U: IsNot<T> + From<T>,
/// {
/// fn from(value: Wrapper<T>) -> Self {
/// Wrapper(From::from(value.0))
/// }
/// }
/// ```
///
/// However, if the `Self` type is non-generic, the trait solver can perform
/// this restrictive check on the input bounds. Since you control the
/// implementation of `IsNot` over your local types, nobody can come along and
/// implement this invalidly.
///
/// **So, surprisingly, as long as `Self` is non-generic, this works!**
///
/// ```
/// # struct TypeA;
/// # struct TypeB;
/// # struct Wrapper<T>(T);
/// # use error_kind::details::IsNot;
/// # impl From<TypeA> for TypeB { fn from(value: TypeA) -> Self { unimplemented!() } }
/// // Say that the types are distinct from each other...
/// impl IsNot<TypeA> for TypeB {}
/// impl IsNot<TypeB> for TypeA {}
///
/// // Oh, look! If `Self` is non-generic, this works!!
/// impl<T> From<Wrapper<T>> for Wrapper<TypeA>
/// where
/// T: IsNot<TypeA>,
/// TypeA: From<T>,
/// {
/// fn from(value: Wrapper<T>) -> Self {
/// Wrapper(From::from(value.0))
/// }
/// }
///
/// // We can say the other way around too - for `TypeB`!
/// impl<T> From<Wrapper<T>> for Wrapper<TypeB>
/// where
/// T: IsNot<TypeB>,
/// TypeB: From<T>,
/// {
/// fn from(value: Wrapper<T>) -> Self {
/// Wrapper(From::from(value.0))
/// }
/// }
/// ```
///
/// **This is what allows the following code to compile.**
///
/// - The [`Error`] type is defined in the dependant's crate (it's local).
/// - [`ErrorDomain`] defines `IsNot` for all variant field types.
/// - We only have to name the domain at the `Error` site to register it.
///
/// ```
/// use error_kind::ErrorKind;
///
/// #[derive(Copy, Clone, Debug, ErrorKind)]
/// pub enum ErrorKindA {
/// Variant,
/// }
///
/// #[derive(Copy, Clone, Debug, ErrorKind)]
/// pub enum ErrorKindB {
/// Variant,
/// }
///
/// #[derive(Copy, Clone, Debug, error_kind::ErrorDomain)]
/// pub enum ErrorDomain {
/// A(ErrorKindA),
/// B(ErrorKindB),
/// }
///
/// #[derive(Clone, Debug, error_kind::Error)]
/// #[error(domains(ErrorDomain))]
/// pub struct Error<K: ErrorKind>(K);
///
/// fn emit_result_a() -> Result<(), Error<ErrorKindA>> {
/// # unimplemented!()
/// // ...
/// }
///
/// fn emit_result_b() -> Result<(), Error<ErrorKindB>> {
/// # unimplemented!()
/// // ...
/// }
///
/// // Thanks to `IsNot`, we can do this:
/// fn emit_result_domain() -> Result<(), Error<ErrorDomain>> {
/// emit_result_a()?; // Converts to `ErrorDomain`!
/// emit_result_b()?; // Converts to `ErrorDomain`!
/// Ok(())
/// }
/// ```
///
/// [`ErrorDomain`]: crate::ErrorDomain
/// [`ErrorKind`]: crate::ErrorKind
/// [`Error`]: crate::Error
/// [`Try`]: core::ops::Try