if let guards documentation

src/expressions/match-expr.md

@@ -9,15 +9,25 @@ MatchExpression ->
         MatchArms?
     `}`
 
-Scrutinee -> Expression _except [StructExpression]_
+Scrutinee ->
+    Expression _except_ [StructExpression]
 
 MatchArms ->
     ( MatchArm `=>` ( ExpressionWithoutBlock `,` | ExpressionWithBlock `,`? ) )*
     MatchArm `=>` Expression `,`?
 
-MatchArm -> OuterAttribute* Pattern MatchArmGuard?
+MatchArm ->
+    OuterAttribute* Pattern MatchArmGuard?
 
-MatchArmGuard -> `if` Expression
+MatchArmGuard ->
+    `if` MatchConditions
+
+MatchConditions ->
+    MatchCondition ( `&&` MatchCondition )*
+
+MatchCondition ->
+      OuterAttribute* `let` Pattern `=` Scrutinee
+    | Expression
 ```
 <!-- TODO: The exception above isn't accurate, see https://github.com/rust-lang/reference/issues/569 -->
 
@@ -150,6 +160,93 @@ This allows shared borrows to be used inside guards without moving out of the sc
 r[expr.match.guard.no-mutation]
 Moreover, by holding a shared reference while evaluating the guard, mutation inside guards is also prevented.
 
+r[expr.match.if.let.guard]
+## If Let Guards
+Match arms can include `if let` guards to allow conditional pattern matching within the guard clause.
+
+r[expr.match.if.let.guard.syntax]
+```rust,ignore
+match expression {
+    pattern if let subpattern = guard_expr => arm_body,
+    ...
+}
+```
+Here, `guard_expr` is evaluated and matched against `subpattern`. If the `if let` expression in the guard matches successfully, the arm's body is executed. Otherwise, pattern matching continues to the next arm.
+
+r[expr.match.if.let.guard.behavior]
+When the pattern matches successfully, the `if let` expression in the guard is evaluated:
+  * The guard proceeds if the inner pattern (`subpattern`) matches the result of `guard_expr`.
+  * Otherwise, the next arm is tested.
+
+```rust,ignore
+let value = Some(10);
+
+let msg = match value {
+    Some(x) if let Some(y) = Some(x - 1) => format!("Matched inner value: {}", y),
+    _ => "No match".to_string(),
+};
+```
+
+r[expr.match.if.let.guard.scope]
+* The `if let` guard may refer to variables bound by the outer match pattern.
+* New variables bound inside the `if let` guard (e.g., `y` in the example above) are available within the body of the match arm where the guard evaluates to `true`, but are not accessible in other arms or outside the match expression.
+
+```rust,ignore
+let opt = Some(42);
+
+match opt {
+    Some(x) if let Some(y) = Some(x + 1) => {
+        // Both `x` and `y` are available in this arm,
+        // since the pattern matched and the guard evaluated to true.
+        println!("x = {}, y = {}", x, y);
+    }
+    _ => {
+        // `y` is not available here --- it was only bound inside the guard above.
+        // Uncommenting the line below will cause a compile-time error:
+        // println!("{}", y); // error: cannot find value `y` in this scope
+    }
+}
+
+// Outside the match expression, neither `x` nor `y` are in scope.
+```
+
+* The outer pattern variables (`x`) follow the same borrowing behavior as in standard match guards (see below).
+
+r[expr.match.if.let.guard.drop]
+
+* Variables bound inside `if let` guards are dropped before evaluating subsequent match arms.
+
+* Temporaries created during guard evaluation follow standard drop semantics and are cleaned up appropriately.
+
+r[expr.match.if.let.guard.borrowing]
+Variables bound by the outer pattern follow the same borrowing rules as standard match guards:
+* A shared reference is taken to pattern variables before guard evaluation
+* Values are moved or copied only when the guard succeeds
+* Moving from outer pattern variables within the guard is restricted
+
+```rust,ignore
+fn take<T>(value: T) -> Option<T> { Some(value) }
+
+let val = Some(vec![1, 2, 3]);
+match val {
+    Some(v) if let Some(_) = take(v) => "moved", // ERROR: cannot move `v`
+    Some(v) if let Some(_) = take(v.clone()) => "cloned", // OK
+    _ => "none",
+}
+```
+> [!NOTE]
+> Multiple matches using the `|` operator can cause the pattern guard and the side effects it has to execute multiple times. For example:
+> ```rust,ignore
+> use std::cell::Cell;
+>
+> let i: Cell<i32> = Cell::new(0);
+> match 1 {
+>     1 | _ if let Some(_) = { i.set(i.get() + 1); Some(1) } => {}
+>     _ => {}
+> }
+> assert_eq!(i.get(), 2); // Guard is executed twice
+> ```
+
 r[expr.match.attributes]
 ## Attributes on match arms