Skip to main content

error_kind/details/
is_not.rs

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