Skip to main content

error_kind/details/
match_into.rs

1// =============================================================================
2// TRAITS
3// =============================================================================
4
5/// Match and convert the fields of an enum.
6///
7/// This is a generic way to use the trait system to implement a match, followed
8/// by a type conversion. That way you don't need to know the variants at the
9/// callsite, only that you *can* convert from all possible field values.
10///
11/// # Detailed Explanation
12///
13/// At first glance, the `MatchInto` trait can feel a lot like a duplicate of
14/// the `Into` trait. But there's two things that set it apart.
15///
16/// 1. We don't want to compete in the same trait space as `Into`.
17/// 2. We want to implement from the perspective of `*Into`.
18///
19/// When we are creating an enum, we obviously know all the variants of that
20/// enum. The same is true about when we're deriving traits for an enum's
21/// implementation.
22///
23/// So we can name our own arms, but we cannot name the target arms.
24///
25/// ```compile_fail
26/// pub enum SubsetEnum {
27///     Bool(bool),
28///     Unsigned(u32),
29/// }
30///
31/// // When deriving, we know enough to write the following trait impl.
32/// impl MatchInto<_> for SubsetEnum {
33///     fn match_into(self) -> _ {
34///         match self {
35///             Self::Bool(value) => _,
36///             Self::Unsigned(value) => _,
37///         }
38///     }
39/// }
40/// ```
41///
42/// But if our types are defined in such a way, where the variant itself doesn't
43/// matter, and only the *fields* matter - we can abstract the match away and
44/// process the conversion over the field data.
45///
46/// ```
47/// # use error_kind::details::MatchInto;
48/// pub enum SubsetEnum {
49///     Bool(bool),
50///     Unsigned(u32),
51/// }
52///
53/// // When deriving, we know enough to write the following trait impl.
54/// impl<T> MatchInto<T> for SubsetEnum
55/// where
56///     T: From<bool> + From<u32>,
57/// {
58///     fn match_into(self) -> T {
59///         match self {
60///             Self::Bool(value) => From::from(value),
61///             Self::Unsigned(value) => From::from(value),
62///         }
63///     }
64/// }
65/// ```
66///
67/// This, it turns out, allows us to have enough information to implement `From`
68/// to convert from another structured type, even if we can't name the variants.
69///
70/// ```
71/// # use error_kind::details::MatchInto;
72/// # pub enum SubsetEnum { Bool(bool), Unsigned(u32), }
73/// # impl<T: From<bool> + From<u32>> MatchInto<T> for SubsetEnum {
74/// #     fn match_into(self) -> T {
75/// #         match self {
76/// #             Self::Bool(value) => From::from(value),
77/// #             Self::Unsigned(value) => From::from(value),
78/// #         }
79/// #     }
80/// # }
81/// pub enum SupersetEnum {
82///     Bool(bool),
83///     Char(char),
84///     Unsigned(u32),
85/// }
86///
87/// // When deriving, we only need to know the *name* of the other types.
88/// impl From<SubsetEnum> for SupersetEnum {
89///     fn from(value: SubsetEnum) -> Self {
90///         value.match_into()
91///     }
92/// }
93///
94/// // Because we can say how we can convert from each value.
95/// impl From<bool> for SupersetEnum {
96///     fn from(value: bool) -> Self {
97///         Self::Bool(value)
98///     }
99/// }
100/// impl From<char> for SupersetEnum {
101///     fn from(value: char) -> Self {
102///         Self::Char(value)
103///     }
104/// }
105/// impl From<u32> for SupersetEnum {
106///     fn from(value: u32) -> Self {
107///         Self::Unsigned(value)
108///     }
109/// }
110/// ```
111///
112/// This is what allows us to implement conversion between different
113/// [`ErrorDomain`]s, without having to know the variant names of the subset
114/// domains.
115///
116/// *We only need to be told that a subset domain exists.*
117///
118/// ```
119/// # use error_kind::{ErrorDomain, ErrorKind};
120/// # #[derive(Copy, Clone, Debug, ErrorKind)]
121/// # pub enum ErrorKindA {
122/// #     Variant,
123/// # }
124/// # #[derive(Copy, Clone, Debug, ErrorKind)]
125/// # pub enum ErrorKindB {
126/// #     Variant,
127/// # }
128/// # #[derive(Copy, Clone, Debug, ErrorKind)]
129/// # pub enum ErrorKindC {
130/// #     Variant,
131/// # }
132/// #[derive(Copy, Clone, Debug, ErrorDomain)]
133/// pub enum ErrorDomainA {
134///     A(ErrorKindA),
135///     B(ErrorKindB),
136/// }
137///
138/// #[derive(Copy, Clone, Debug, ErrorDomain)]
139/// #[error(domains(ErrorDomainA))] // <- Inform about subset domain.
140/// pub enum ErrorDomainB {
141///     A(ErrorKindA),
142///     B(ErrorKindB),
143///     C(ErrorKindC),
144/// }
145///
146/// #[derive(Clone, Debug, error_kind::Error)]
147/// #[error(domains(ErrorDomainA, ErrorDomainB))] // <- Register all domains.
148/// pub struct Error<K: ErrorKind>(K);
149///
150/// fn emit_result_domain_a() -> Result<(), Error<ErrorDomainA>> {
151///     # unimplemented!()
152///     // ...
153/// }
154///
155/// // Thanks to `MatchInto`, we can do this!
156/// fn emit_result_domain_b() -> Result<(), Error<ErrorDomainB>> {
157///     emit_result_domain_a()?; // Converts to `ErrorDomainB`!
158///     Ok(())
159/// }
160/// ```
161///
162/// [`ErrorDomain`]: crate::ErrorDomain
163pub trait MatchInto<T>: Sized {
164    /// Convert from `Self` into `T` via a match + conversion.
165    fn match_into(self) -> T;
166}