Show if-case and for-case in the guide (#361)

This syntax was previously shown only in the reference, under Optional
Patterns.  Added a new section to the Control Flow chapter to discuss
this, pattern-matching against tuples because that's the only suitable
data type available at that point in the book.  Added forward and
backward cross-references to the section about enumerations that have
associated values, because this syntax is the way you extract that
associated value.

Fixes: rdar://145579866

Author: amartini51

TSPL.docc/LanguageGuide/ControlFlow.md

@@ -1440,6 +1440,97 @@ and `distance` is an integer in both patterns ---
 which means that the code in the body of the `case`
 can always access a value for `distance`.
 
+## Patterns
+
+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 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,
+then the condition for the `if` is considered to be true,
+and so 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.
+
+In a `for`-`in` loop,
+you can give names to parts of the value using a value binding pattern,
+even without writing `case` in your code:
+
+```swift
+let points = [(10, 0), (30, -30), (-20, 0)]
+
+for (x, y) in points {
+    if 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"
+```
+
+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,
+such as the `if` statement that checks whether the point lies on the x-axis.
+A more concise way to write this code
+is to combine the value bindings and condition
+using a `for`-`case`-`in` loop.
+The code below has the same behavior as the `for`-`in` loop above:
+
+```swift
+for case (let x, 0) in points {
+    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.
+
+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:
+
+```swift
+for case let (x, y) in points where x == y || x == -y  {
+    print("Found (\(x), \(y)) along a line through the origin")
+}
+// Prints "Found (30, -30) along a line through the origin"
+```
+
+This code binds the first and second elements of the tuple
+to `x` and `y` as constants,
+and then checks their values in the `where` clause.
+If the `where` clause is `true`,
+then the code in the body of the `for` loop runs;
+otherwise, iteration continues with the next element.
+
+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,

TSPL.docc/LanguageGuide/Enumerations.md

@@ -479,6 +479,27 @@ case let .qrCode(productCode):
   ```
 -->
 
+When you're matching just one case of an enumeration ---
+for example,
+to extract its associated value ---
+you can use an `if`-`case` statement
+instead of writing a full switch statement.
+Here's what it looks like:
+
+```swift
+if case .qrCode(let productCode) = productBarcode {
+    print("QR code: \(productCode).")
+}
+```
+
+Just like in the switch statement earlier,
+the `productBarcode` variable is matched against
+the pattern `.qrCode(let productCode)` here.
+And as in the switch case,
+writing `let` extracts the associated value as a constant.
+For more information about `if`-`case` statements,
+see <doc:ControlFlow#Patterns>.
+
 ## Raw Values
 
 The barcode example in <doc:Enumerations#Associated-Values>
@@ -520,14 +541,17 @@ Raw values can be
 strings, characters, or any of the integer or floating-point number types.
 Each raw value must be unique within its enumeration declaration.
 
-> Note: Raw values are *not* the same as associated values.
-> Raw values are set to prepopulated values
-> when you first define the enumeration in your code,
-> like the three ASCII codes above.
-> The raw value for a particular enumeration case is always the same.
-> Associated values are set when you create a new constant or variable
-> based on one of the enumeration's cases,
-> and can be different each time you do so.
+Although you can use both raw values and associated values
+to give an enumeration an additional value,
+it's important to understand the difference between them.
+You pick the raw value for an enumeration case
+when you define that enumeration case in your code,
+such as the three ASCII codes above.
+The raw value for a particular enumeration case is always the same.
+In contrast,
+you pick associated values when you create a new constant or variable
+using one of the enumeration's cases,
+and you can pick a different value each time you do so.
 
 ### Implicitly Assigned Raw Values