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
|
# try_match
[<img src="https://docs.rs/try_match/badge.svg" alt="docs.rs">](https://docs.rs/try_match/)
Fallible pattern matching with a function-like syntax
## Basic Usage
### Macros
```rust
use try_match::{try_match, match_ok, unwrap_match};
#[derive(Copy, Clone, Debug, PartialEq)]
enum Enum { Var0, Var1(i32), Var2(i32, i32) }
use Enum::*;
// `try_match!` returns `Result`: `Ok(bindings)` on success or
// `Err(input_value)` otherwise
assert_eq!(try_match!(Var1(42), Var1(x)), Ok(42));
assert_eq!(try_match!(Var0, Var1(x)), Err(Var0));
// `match_ok!` returns `Option`
assert_eq!(match_ok!(Var1(42), Var1(x)), Some(42));
assert_eq!(match_ok!(Var0, Var1(x)), None);
// `match_or_default!` returns a default value on failure
assert_eq!(match_or_default!(Var1(42), Var1(x)), 42);
assert_eq!(match_or_default!(Var0, Var1(x)), 0);
// `unwrap_match!` panics on failure:
assert_eq!(unwrap_match!(Var1(42), Var1(x)), 42);
/* unwrap_match!(Var0, Var1(x)); */ // this will panic
```
Match guards (`if <expr>`) are supported:
```rust
assert_eq!(match_ok!(Var1(42), Var1(x)), Some(42));
assert_eq!(match_ok!(Var1(42), Var1(x) if x < 20), None);
```
### Bindings
```rust
// Returns `()` (wrapped by `Ok(_)`) if there are no bound variables
assert_eq!(unwrap_match!(Var1(42), Var1(_)), ());
// ... the bound value if there is exactly one binding
assert_eq!(unwrap_match!(Var1(42), Var1(x)), 42);
// ... an anonymous struct if there are multiple bindings
let vars = unwrap_match!(Var2(12, 34), Var2(a, b));
assert_eq!((vars.a, vars.b), (12, 34));
// ... or a tuple if the binding names are numeric
let (a, b) = unwrap_match!(Var2(12, 34), Var2(_0, _1));
assert_eq!((a, b), (12, 34));
// An optional `=>` clause specifies an explicit mapping
assert_eq!(unwrap_match!(Var1(42), Var1(x) => x + 1), 43);
assert_eq!(unwrap_match!(Var0, Var0 => "yay"), "yay");
```
### Partial Application
```rust
// Omit the scrutinee expression to produce a closure
let _: Option<i32> = match_ok!(Var1(42), Var1(x));
let _: fn(Enum) -> Option<i32> = match_ok!( , Var1(x));
```
## Applications
### `Iterator::filter_map`
```rust
let array = [Var1(42), Var0, Var1(10)];
let filtered: Vec<_> = array
.iter()
.filter_map(match_ok!(, &Var1(_0) if _0 > 20))
.collect();
assert_eq!(filtered, [42]);
```
### `Iterator::map` + Fallible `Iterator::collect`
```rust
let array = [Var1(42), Var0, Var1(10)];
let filtered: Result<Vec<_>, _> = array
.iter()
.map(try_match!(, &Var1(_0) if _0 > 20))
.collect();
// `Var0` is the first value that doesn't match
assert_eq!(filtered, Err(&Var0));
```
### Extract Variants
```rust
impl Enum {
fn var1(&self) -> Option<&i32> {
match_ok!(self, Var1(_0))
}
fn is_var2(&self) -> bool {
matches!(self, Var0)
}
}
let enums = [Var1(42), Var0];
assert_eq!(enums[0].var1(), Some(&42));
assert_eq!(enums[1].var1(), None);
assert!(!enums[0].is_var2());
assert!(enums[1].is_var2());
```
### Expect Certain Variants
```rust
fn this_fn_expects_var2(foo: &Enum) {
let i = unwrap_match!(foo, &Var2(42, _0));
// Alternatively, you could use let-else (stabilized in Rust 1.65.0):
// let &Var2(42, i) = foo else { panic!("{foo:?}") };
assert_eq!(i, 84);
}
this_fn_expects_var2(&Var2(42, 84));
```
## Related Works
[`matcher::matches!`][] (now incorporated into the standard library as
[`core::matches!`][]) is similar but only returns `bool` indicating whether
matching was successful or not.
```rust
let success1 = matches!(Some(42), Some(_));
let success2 = match_ok!(Some(42), Some(_)).is_some();
assert_eq!(success1, success2);
```
[`bind_match::bind_match!`][] and [`extract::extract!`][] behave in the same way
as `match_ok!` except for the lack of implicit mapping and partial application.
[`variant::get_variant!`][] from the `extract_variant` crate offers a similar
functionality to `match_ok!`. It supports implicit mapping but uses different
rules to handle multiple bindings.
[`core::matches!`]: https://doc.rust-lang.org/1.56.0/core/macro.matches.html
[`matcher::matches!`]: https://crates.io/crates/matches
[`bind_match::bind_match!`]: https://crates.io/crates/bind_match
[`extract::extract!`]: https://crates.io/crates/extract_macro
[`variant::get_variant!`]: https://crates.io/crates/extract-variant/1.0.0
## License
MIT/Apache-2.0
|
