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
// =============================================================================
// TRAITS
// =============================================================================
/// Match and convert the fields of an enum.
///
/// This is a generic way to use the trait system to implement a match, followed
/// by a type conversion. That way you don't need to know the variants at the
/// callsite, only that you *can* convert from all possible field values.
///
/// # Detailed Explanation
///
/// At first glance, the `MatchInto` trait can feel a lot like a duplicate of
/// the `Into` trait. But there's two things that set it apart.
///
/// 1. We don't want to compete in the same trait space as `Into`.
/// 2. We want to implement from the perspective of `*Into`.
///
/// When we are creating an enum, we obviously know all the variants of that
/// enum. The same is true about when we're deriving traits for an enum's
/// implementation.
///
/// So we can name our own arms, but we cannot name the target arms.
///
/// ```compile_fail
/// pub enum SubsetEnum {
/// Bool(bool),
/// Unsigned(u32),
/// }
///
/// // When deriving, we know enough to write the following trait impl.
/// impl MatchInto<_> for SubsetEnum {
/// fn match_into(self) -> _ {
/// match self {
/// Self::Bool(value) => _,
/// Self::Unsigned(value) => _,
/// }
/// }
/// }
/// ```
///
/// But if our types are defined in such a way, where the variant itself doesn't
/// matter, and only the *fields* matter - we can abstract the match away and
/// process the conversion over the field data.
///
/// ```
/// # use error_kind::details::MatchInto;
/// pub enum SubsetEnum {
/// Bool(bool),
/// Unsigned(u32),
/// }
///
/// // When deriving, we know enough to write the following trait impl.
/// impl<T> MatchInto<T> for SubsetEnum
/// where
/// T: From<bool> + From<u32>,
/// {
/// fn match_into(self) -> T {
/// match self {
/// Self::Bool(value) => From::from(value),
/// Self::Unsigned(value) => From::from(value),
/// }
/// }
/// }
/// ```
///
/// This, it turns out, allows us to have enough information to implement `From`
/// to convert from another structured type, even if we can't name the variants.
///
/// ```
/// # use error_kind::details::MatchInto;
/// # pub enum SubsetEnum { Bool(bool), Unsigned(u32), }
/// # impl<T: From<bool> + From<u32>> MatchInto<T> for SubsetEnum {
/// # fn match_into(self) -> T {
/// # match self {
/// # Self::Bool(value) => From::from(value),
/// # Self::Unsigned(value) => From::from(value),
/// # }
/// # }
/// # }
/// pub enum SupersetEnum {
/// Bool(bool),
/// Char(char),
/// Unsigned(u32),
/// }
///
/// // When deriving, we only need to know the *name* of the other types.
/// impl From<SubsetEnum> for SupersetEnum {
/// fn from(value: SubsetEnum) -> Self {
/// value.match_into()
/// }
/// }
///
/// // Because we can say how we can convert from each value.
/// impl From<bool> for SupersetEnum {
/// fn from(value: bool) -> Self {
/// Self::Bool(value)
/// }
/// }
/// impl From<char> for SupersetEnum {
/// fn from(value: char) -> Self {
/// Self::Char(value)
/// }
/// }
/// impl From<u32> for SupersetEnum {
/// fn from(value: u32) -> Self {
/// Self::Unsigned(value)
/// }
/// }
/// ```
///
/// This is what allows us to implement conversion between different
/// [`ErrorDomain`]s, without having to know the variant names of the subset
/// domains.
///
/// *We only need to be told that a subset domain exists.*
///
/// ```
/// # use error_kind::{ErrorDomain, ErrorKind};
/// # #[derive(Copy, Clone, Debug, ErrorKind)]
/// # pub enum ErrorKindA {
/// # Variant,
/// # }
/// # #[derive(Copy, Clone, Debug, ErrorKind)]
/// # pub enum ErrorKindB {
/// # Variant,
/// # }
/// # #[derive(Copy, Clone, Debug, ErrorKind)]
/// # pub enum ErrorKindC {
/// # Variant,
/// # }
/// #[derive(Copy, Clone, Debug, ErrorDomain)]
/// pub enum ErrorDomainA {
/// A(ErrorKindA),
/// B(ErrorKindB),
/// }
///
/// #[derive(Copy, Clone, Debug, ErrorDomain)]
/// #[error(domains(ErrorDomainA))] // <- Inform about subset domain.
/// pub enum ErrorDomainB {
/// A(ErrorKindA),
/// B(ErrorKindB),
/// C(ErrorKindC),
/// }
///
/// #[derive(Clone, Debug, error_kind::Error)]
/// #[error(domains(ErrorDomainA, ErrorDomainB))] // <- Register all domains.
/// pub struct Error<K: ErrorKind>(K);
///
/// fn emit_result_domain_a() -> Result<(), Error<ErrorDomainA>> {
/// # unimplemented!()
/// // ...
/// }
///
/// // Thanks to `MatchInto`, we can do this!
/// fn emit_result_domain_b() -> Result<(), Error<ErrorDomainB>> {
/// emit_result_domain_a()?; // Converts to `ErrorDomainB`!
/// Ok(())
/// }
/// ```
///
/// [`ErrorDomain`]: crate::ErrorDomain