Skip to content
18 changes: 9 additions & 9 deletions doc/modules/language-guide/pages/pattern-matching.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,13 @@ switch ("Adrienne", #female) {
}
....

will match the first `case` clause (because binding to the identifier `name` cannot fail and the shorthand variant literal `#Female` compares as equal), and evaluate to `"It's a girl! Adrienne"`. The second clause showcases the _wildcard_ pattern `_`. It cannot fail, but won't bind any identifier.
... will match the first `case` clause (because binding to the identifier `name` cannot fail and the shorthand variant literal `#Female` compares as equal), and evaluate to `"It's a girl! Adrienne"`. The second clause showcases the _wildcard_ pattern `_`. It cannot fail, but won't bind any identifier.

The last kind of pattern is the `or`-pattern. As their name suggests, these are two or more patterns that are separated by the keyword `or`. Each of the sub-patterns must bind to the same set of identifiers, and is matched from left-to-right. An `or`-pattern fails when its rightmost sub-pattern fails.
The last kind of pattern is the `or` pattern. As their name suggests, these are two or more patterns that are separated by the keyword `or`. Each of the sub-patterns must bind to the same set of identifiers, and is matched from left-to-right. An `or` pattern fails when its rightmost sub-pattern fails.
Comment thread
crusso marked this conversation as resolved.
Outdated

.The following table summarises the different ways of pattern matching.
|===
|pattern kind |examples |appears in |can fail |remarks
|pattern type |example(s) |context |can fail |remarks
Comment thread
crusso marked this conversation as resolved.
Outdated

|literal
|`null`, `42`, `()`, `"Hi"`
Expand All @@ -62,7 +62,7 @@ The last kind of pattern is the `or`-pattern. As their name suggests, these are
|typed
|`age : Nat`
|everywhere
|depends
|conditional
|

|option
Expand All @@ -74,19 +74,19 @@ The last kind of pattern is the `or`-pattern. As their name suggests, these are
| tuple
|`( component~0~, component~1~, ... )`
|everywhere
|depends
|conditional
|must have at least two components

| object
|`{ field~A~; field~B~; ... }`
|everywhere
|depends
|conditional
|allowed to mention a subset of fields

| field
|`age`, `count = 0`
|object
|depends
|conditional
|`age` is short for `age = age`

|variant
Expand Down Expand Up @@ -123,9 +123,9 @@ Other programming languages—for example C, but not {proglang}—often use a ke
Error handling can be considered a use-case for pattern matching. When a function returns a value that has an alternative for success and one for failure (for example, an option value or a variant), pattern matching can be used to distinguish between the two as discussed in xref:errors{outfilesuffix}[Error handling].

- non-failable matching
Some types admit only a single value and we call these _singleton types_. Examples of these are the unit type (also known as an empty tuple) or tuples that only contain singleton types. Variants with only one alternative and no payload (or singleton-typed payload) are singleton types too. Pattern matching on singleton types is particularly straightforward, as it only has one possible alternative, which can never fail.
Some types admit only a single value and we call these _singleton types_. Examples of these are the unit type (also known as an empty tuple) or tuples that only contain singleton types. Variants with only one scrutineer (no alternatives) and no payload (or singleton-typed payload) are singleton types too. Pattern matching on singleton types is particularly straightforward, as it only has one possible scrutineer, which can never fail.
Comment thread
crusso marked this conversation as resolved.
Outdated

- exhaustiveness (coverage) checking
When a pattern check alternative has the potential to fail, then it becomes important to find out whether the whole `switch` expression can fail. If this can happen the execution of the program can trap for certain inputs, posing an operational threat. To this end, the compiler checks for the exhaustiveness of pattern matching by keeping track of the covered shape of the scrutinee. The compiler issues a warning for any non-covered scrutinees ({proglang} even tries to come up with an example of a scrutinee that is not patched). As by-product of the exhaustiveness check, warnings are also issued for dead alternatives.
When a pattern check alternative has the potential to fail, then it becomes important to find out whether the whole `switch` expression can fail. If this can happen the execution of the program can trap for certain inputs, posing an operational threat. To this end, the compiler checks for the exhaustiveness of pattern matching by keeping track of the covered shape of the scrutinee. The compiler issues a warning for any non-covered scrutinees ({proglang} even constructs a helpful example of a scrutinee that is not matched). As by-product of the exhaustiveness check, warnings are also issued for dead alternatives.

In summary, pattern checking is a great tool for several use-cases and enables active assistance from the compiler to the programmer by pointing out which inputs are not exhaustively taken care of. The static compile-time nature of coverage checking reliably rules out runtime failures.
Comment thread
crusso marked this conversation as resolved.
Outdated