Discuss if-case and for-case in Control Flow

Using a pattern with these constructs isn't specific to enums, even
though that's a place where it's nearly indispensable.  It makes more
sense to introduce the 'case' version alongside each of the plain
versions -- folks are also more likely to look in that chapter than in
the Enumerations chapter if they're trying to look this up.

Author: amartini51

TSPL.docc/LanguageGuide/ControlFlow.md

@@ -1442,33 +1442,76 @@ can always access a value for `distance`.
 
 ## Patterns
 
-XXX OUTLINE:
-
-- Each switch case takes a *pattern*
-  that describes what values that case handles
-- You can also use patterns with if and for
-- The for-case syntax is useful when you want to iterate
-  over only certain elements in a collection
-- Because patterns can bind values,
-  they're also useful for working with enumerations that have associated values
-  XREF <doc:Enumerations#Associated-Values>
+In the previous examples, each switch case includes a pattern
+that indicates what values match that case.
+You can also use a pattern as the condition for an `if` statement.
+Here's what that looks like:
 
 ```swift
 let somePoint = (12, 100)
 if case (let x, 100) = somePoint {
-    print("Found a point with x of \(x)")
+    print("Found a point on the y=100 line, at \(x)")
 }
+// Prints "Found a point on the y=100 line, at 12"
+```
+
+In this code,
+the condition for the `if` statement starts with `case`,
+indicating that the condition is a pattern instead of a Boolean value.
+If the pattern matches,
+the condition for the `if` is considered to be true,
+and the code in the body of the `if` statement runs.
+The patterns you can write after `if case`
+are the same as the patterns you can write in a switch case.
 
+You can also use a pattern in a `for`-`in` loop,
+to give names to parts of the value using a value binding:
+
+```swift
 let points = [(10, 0), (30, 100), (-20, 0)]
-for case (let x, let y) in points {
-    guard y == 0 else { continue }
-    print("Found a point on the x-axis at \(x)")
+
+for case let (x, y) in points {
+    if y == 0 {
+        print("Found a point on the x-axis at \(x)")
+    }
 }
-for case (let x, let y) in points where y == 0  {
+// Prints "Found a point on the x-axis at 10"
+// Prints "Found a point on the x-axis at -20"
+```
+
+The `for`-`in` loop above iterates over an array of tuples,
+binding the first and second elements of the tuples
+to the `x` and `y` constants.
+The statements inside the loop can use those constants,
+like the `if` statement that checks whether the point lies on the x-axis.
+
+A `for`-`case`-`in` loop can also include a `where` clause,
+to check for an additional condition.
+The statements inside the loop run
+only when `where` clause matches the current element.
+For example,
+the `for`-`case`-`in` loop below is the same as the `for`-`in` loop above.
+
+```swift
+for case let (x, y) in points where y == 0  {
     print("Found a point on the x-axis at \(x)")
 }
+// Prints "Found a point on the x-axis at 10"
+// Prints "Found a point on the x-axis at -20"
 ```
 
+In this code,
+the condition is integrated into the `for`-`case`-`in` loop as part of the pattern.
+The statements in the `for`-`case`-`in` loop run only for points on the x-axis.
+This code produces the same result as the `for`-`in` loop above,
+but is a more compact way to iterate
+over only certain elements in a collection.
+
+Because patterns can bind values,
+`if`-`case` statements and `for`-`case`-`in` loops
+are useful for working with enumerations that have associated values,
+as described in <doc:Enumerations#Associated-Values>.
+
 ## Control Transfer Statements
 
 *Control transfer statements* change the order in which your code is executed,
@@ -2012,6 +2055,8 @@ without wrapping it in an `else` block,
 and it lets you keep the code that handles a violated requirement
 next to the requirement.
 
+<!-- XXX show guard-case syntax for completeness? -->
+
 ## Deferred Actions
 
 Unlike control-flow constructs like `if` and `while`,

TSPL.docc/LanguageGuide/Enumerations.md

@@ -482,7 +482,7 @@ case let .qrCode(productCode):
 When you're matching just one case of an enumeration ---
 for example,
 to extract its associated value ---
-there's a shorter syntax you can use
+you can use an `if`-`case` statement
 instead of writing a full switch statement.
 Here's what it looks like:
 
@@ -492,21 +492,13 @@ if case .qrCode(let productCode) = productBarcode {
 }
 ```
 
-In this code,
-the condition for the `if` statement starts with `case`,
-indicating that the condition is a pattern instead of a Boolean value.
-If the pattern matches,
-the condition for the `if` is considered to be true,
-and the code in the body of the `if` statement runs.
-The patterns you can write after `if case`
-are the same as the patterns you can write in a switch case.
 Just like in the switch statement earlier,
 the `productBarcode` variable is matched against
 the pattern `.qrCode(let productCode)` here.
 And like in the switch case,
 writing `let` extracts the associated value as a constant.
-
-<!-- XXX mention guards, and maybe for loops -->
+For more information about `if`-`case` statements,
+see <doc:ControlFlow#Patterns>.
 
 ## Raw Values