Refutability: Whether a Pattern Might Fail to Match - The Rust Programming Language

## Refutability: Whether a Pattern Might Fail to Match

Patterns come in two forms: refutable and irrefutable. Patterns which cannot fail to match for any possible value are said to be irrefutable, and patterns which can fail to match for some possible value are said to be refutable. `let` statements, function parameters, and `for` loops are restricted to only accept irrefutable patterns, since there’s nothing correct the program could do if the pattern fails to match. `if let`, and `while let` expressions are restricted to only accept refutable patterns, since they’re made to handle possible failure and we wouldn’t need their functionality if the pattern could never fail.

In general, you shouldn’t have to worry about the distinction between refutable and irrefutable patterns; just be familiar with the concept of refutability when you see it mentioned in an error message. When you get an error message involving refutability, you’ll need to change either the pattern or the construct you’re using the pattern with, depending on your intentions for the behavior of the code.

Let’s look at some examples. Earlier in this chapter, we had `let x = 5;`. `x` is indeed an irrefutable pattern we’re allowed to use: since it matches anything, it can’t fail to match. In contrast, consider trying to match one variant of an enum with `let`, such as matching only a `Some<T>` value from the `Option<T>` enum as shown in Listing 18-7:

    let Some(x) = some_option_value;

Listing 18-7: Attempting to use a refutable pattern with `let`

If `some_option_value` was a `None` value, `some_option_value` would not match the pattern `Some(x)`. The pattern `Some(x)` is refutable since there exists a case in which it would fail to match a value. There’s nothing valid that our code could do with this `let` statement if `some_option_value` was the `None` value. Therefore, Rust will complain at compile time that we’ve tried to use a refutable pattern where an irrefutable pattern is required:

    error[E0005]: refutable pattern in local binding: `None` not covered
     --> <anon>:3:5
      |
    3 | let Some(x) = some_option_value;
      |     ^^^^^^^ pattern `None` not covered

We didn’t cover (and couldn’t cover!) every valid value with the pattern `Some(x)`, so Rust will rightfully complain.

If we have a refutable pattern, instead of using `let`, we can use `if let`. That way, if the pattern doesn’t match, the code inside the curly braces won’t execute. That code will only make sense and run if the value matches the pattern. Listing 18-8 shows how to fix the code in Listing 18-7 with `Some(x)` matching `some_option_value`. Using the refutable pattern `Some(x)` is allowed, since this example uses `if let`:

    # #![allow(unused_variables)]
    #fn main() {
    # let some_option_value: Option<i32> = None;
    if let Some(x) = some_option_value {
        println!("{}", x);
    }

    #}

Listing 18-8: Using `if let` and a block with refutable patterns instead of `let`

Consequently, if we give `if let` an irrefutable pattern that will always match, such as `x` as shown in Listing 18-9:

    if let x = 5 {
        println!("{}", x);
    };

Listing 18-9: Attempting to use an irrefutable pattern with `if let`

Rust will complain that it doesn’t make sense to use `if let` with an irrefutable pattern:

    error[E0162]: irrefutable if-let pattern
     --> <anon>:2:8
      |
    2 | if let x = 5 {
      |        ^ irrefutable pattern

Generally, match arms use refutable patterns, except for the last arm that might match any remaining values with an irrefutable pattern. A `match` with only one arm whose pattern is irrefutable is allowed, but it’s not particularly useful and could be replaced with a simpler `let` statement. Both the expressions associated with a `let` statement and a single arm irrefutable match will unconditionally be run, so the end result is the same if their expressions are.

Now that we’ve discussed all the places that patterns can be used and the difference between refutable and irrefutable patterns, let’s go over all the syntax we can use to create patterns.