RFC 2294: if-let-guard

lang (syntax | expressions | control-flow)

Summary

Allow if let guards in match expressions.

Motivation

This feature would greatly simplify some logic where we must match a pattern iff some value computed from the match-bound values has a certain form, where said value may be costly or impossible (due to affine semantics) to recompute in the match arm.

For further motivation, see the example in the guide-level explanation. Absent this feature, we might rather write the following:

match ui.wait_event() {
    KeyPress(mod_, key, datum) =>
        if let Some(action) = intercept(mod_, key) { act(action, datum) }
        else { accept!(KeyPress(mod_, key, datum)) /* can't re-use event verbatim if `datum` is non-`Copy` */ }
    ev => accept!(ev),
}

accept may in general be lengthy and inconvenient to move into another function, for example if it refers to many locals.

Here is an (incomplete) example taken from a real codebase, to respond to ANSI CSI escape sequences:

#[inline]
fn csi_dispatch(&mut self, parms: &[i64], ims: &[u8], ignore: bool, x: char) {
    match x {
        'C' => if let &[n] = parms { self.screen.move_x( n as _) }
               else { log_debug!("Unknown CSI sequence: {:?}, {:?}, {:?}, {:?}",
                                 parms, ims, ignore, x) },
        'D' => if let &[n] = parms { self.screen.move_x(-n as _) }
               else { log_debug!("Unknown CSI sequence: {:?}, {:?}, {:?}, {:?}",
                                 parms, ims, ignore, x) },
        'J' => self.screen.erase(match parms {
            &[] |
            &[0] => Erasure::ScreenFromCursor,
            &[1] => Erasure::ScreenToCursor,
            &[2] => Erasure::Screen,
            _ => { log_debug!("Unknown CSI sequence: {:?}, {:?}, {:?}, {:?}",
                              parms, ims, ignore, x); return },
        }, false),
        'K' => self.screen.erase(match parms {
            &[] |
            &[0] => Erasure::LineFromCursor,
            &[1] => Erasure::LineToCursor,
            &[2] => Erasure::Line,
            _ => { log_debug!("Unknown CSI sequence: {:?}, {:?}, {:?}, {:?}",
                              parms, ims, ignore, x); return },
        }, false),
        'm' => match parms {
            &[] |
            &[0] => *self.screen.def_attr_mut() = Attr { fg_code: 0, fg_rgb: [0xFF; 3],
                                                         bg_code: 0, bg_rgb: [0x00; 3],
                                                         flags: AttrFlags::empty() },
            &[n] => if let (3, Some(rgb)) = (n / 10, color_for_code(n % 10, 0xFF)) {
                self.screen.def_attr_mut().fg_rgb = rgb;
            } else {
                log_debug!("Unknown CSI sequence: {:?}, {:?}, {:?}, {:?}",
                           parms, ims, ignore, x);
            },
            _ => log_debug!("Unknown CSI sequence: {:?}, {:?}, {:?}, {:?}",
                            parms, ims, ignore, x),
        },
        _ => log_debug!("Unknown CSI sequence: {:?}, {:?}, {:?}, {:?}",
                        parms, ims, ignore, x),
    }
}

These examples are both clearer with if let guards as follows. Particularly in the latter example, in the author's opinion, the control flow is easier to follow.

Guide-level explanation

(Adapted from Rust book)

A match guard is an if let condition specified after the pattern in a match arm that also must match if the pattern matches in order for that arm to be chosen. Match guards are useful for expressing more complex ideas than a pattern alone allows.

The condition can use variables created in the pattern, and the match arm can use any variables bound in the if let pattern (as well as any bound in the match pattern, unless the if let expression moves out of them).

Let us consider an example which accepts a user-interface event (e.g. key press, pointer motion) and follows 1 of 2 paths: either we intercept it and take some action or deal with it normally (whatever that might mean here):

match ui.wait_event() {
    KeyPress(mod_, key, datum) if let Some(action) = intercept(mod_, key) => act(action, datum),
    ev => accept!(ev),
}

Here is another example, to respond to ANSI CSI escape sequences:

#[inline]
fn csi_dispatch(&mut self, parms: &[i64], ims: &[u8], ignore: bool, x: char) {
    match x {
        'C' if let &[n] = parms => self.screen.move_x( n as _),
        'D' if let &[n] = parms => self.screen.move_x(-n as _),
        _ if let Some(e) = erasure(x, parms) => self.screen.erase(e, false),
        'm' => match parms {
            &[] |
            &[0] => *self.screen.def_attr_mut() = Attr { fg_code: 0, fg_rgb: [0xFF; 3],
                                                         bg_code: 0, bg_rgb: [0x00; 3],
                                                         flags: AttrFlags::empty() },
            &[n] if let (3, Some(rgb)) = (n / 10, color_for_code(n % 10, 0xFF)) =>
                self.screen.def_attr_mut().fg_rgb = rgb,
            _ => log_debug!("Unknown CSI sequence: {:?}, {:?}, {:?}, {:?}",
                            parms, ims, ignore, x),
        },
        _ => log_debug!("Unknown CSI sequence: {:?}, {:?}, {:?}, {:?}",
                        parms, ims, ignore, x),
    }
}

#[inline]
fn erasure(x: char, parms: &[i64]) -> Option<Erasure> {
    match x {
        'J' => match parms {
            &[] |
            &[0] => Some(Erasure::ScreenFromCursor),
            &[1] => Some(Erasure::ScreenToCursor),
            &[2] => Some(Erasure::Screen),
            _ => None,
        },
        'K' => match parms {
            &[] |
            &[0] => Some(Erasure::LineFromCursor),
            &[1] => Some(Erasure::LineToCursor),
            &[2] => Some(Erasure::Line),
            _ => None,
        },
        _ => None,
    }
}

Reference-level explanation

This proposal would introduce syntax for a match arm: pat if let guard_pat = guard_expr => body_expr with semantics so the arm is chosen iff the argument of match matches pat and guard_expr matches guard_pat. The variables of pat are bound in guard_expr, and the variables of pat and guard_pat are bound in body_expr. The syntax is otherwise the same as for if guards. (Indeed, if guards become effectively syntactic sugar for if let guards.)

An arm may not have both an if and an if let guard.

Drawbacks

Rationale and alternatives

Unresolved questions

Questions in scope of this proposal: none yet known

Questions out of scope: