From 9c7988e7abafcc594134f30634eb5f13119fea71 Mon Sep 17 00:00:00 2001 From: Rex Jaeschke Date: Thu, 7 Dec 2023 07:28:52 -0500 Subject: [PATCH 01/13] Add support for pattern additions Add support for pattern additions fix md and example update headings fix link warnings --- standard/lexical-structure.md | 16 ++-- standard/patterns.md | 161 +++++++++++++++++++++++++++++++++- 2 files changed, 167 insertions(+), 10 deletions(-) diff --git a/standard/lexical-structure.md b/standard/lexical-structure.md index a86d23aed..6010849bd 100644 --- a/standard/lexical-structure.md +++ b/standard/lexical-structure.md @@ -78,9 +78,10 @@ These productions occur in contexts where a value can occur in an expression, an If a sequence of tokens can be parsed, in context, as one of the disambiguated productions including an optional *type_argument_list* ([§8.4.2](types.md#842-type-arguments)), then the token immediately following the closing `>` token shall be examined and if it is: -- one of `( ) ] } : ; , . ? == != | ^ && || & [`; or +- one of `( ) ] } : ; , . ? == != | ^ && || & [ =>`; or - one of the relational operators `< <= >= is as`; or - a contextual query keyword appearing inside a query expression. +- In certain contexts, *identifier* is treated as a disambiguating token. Those contexts are where the sequence of tokens being disambiguated is immediately preceded by one of the keywords `is`, `case` or `out`, or arises while parsing the first element of a tuple literal (in which case the tokens are preceded by `(` or `:` and the identifier is followed by a `,`) or a subsequent element of a tuple literal. then the *type_argument_list* shall be retained as part of the disambiguated production and any other possible parse of the sequence of tokens discarded. Otherwise, the tokens parsed as a *type_argument_list* shall not be considered to be part of the disambiguated production, even if there is no other possible parse of those tokens. @@ -606,12 +607,13 @@ A ***contextual keyword*** is an identifier-like sequence of characters that has ```ANTLR contextual_keyword - : 'add' | 'alias' | 'ascending' | 'async' | 'await' - | 'by' | 'descending' | 'dynamic' | 'equals' | 'from' - | 'get' | 'global' | 'group' | 'into' | 'join' - | 'let' | 'nameof' | 'notnull' | 'on' | 'orderby' - | 'partial' | 'remove' | 'select' | 'set' | 'unmanaged' - | 'value' | 'var' | 'when' | 'where' | 'yield' + : 'add' | 'alias' | 'and' | 'ascending' | 'async' + | 'await' | 'by' | 'descending' | 'dynamic' | 'equals' + | 'from' | 'get' | 'global' | 'group' | 'into' + | 'join' | 'let' | 'nameof' | 'not' | 'notnull' + | 'on' | 'or' | 'orderby' | 'partial' | 'remove' + | 'select' | 'set' | 'unmanaged' | 'value' | 'var' + | 'when' | 'where' | 'yield' ; ``` diff --git a/standard/patterns.md b/standard/patterns.md index e224a6caf..c495108bd 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -2,7 +2,7 @@ ## 11.1 General -A ***pattern*** is a syntactic form that can be used with the `is` operator ([§12.14.12](expressions.md#121412-the-is-operator)), in a *switch_statement* ([§13.8.3](statements.md#1383-the-switch-statement)), and in a *switch_expression* ([§12.11](expressions.md#1211-switch-expression)) to express the shape of data against which incoming data is to be compared. Patterns may be recursive, so that parts of the data may be matched against ***sub-patterns***. +A ***pattern*** is a syntactic form that can be used with the `is` operator ([§12.14.12](expressions.md#121412-the-is-operator)), in a *switch_statement* ([§13.8.3](statements.md#1383-the-switch-statement)), and in a *switch_expression* ([§12.11](expressions.md#1211-switch-expression)) to express the shape of data against which incoming data is to be compared. Patterns may be recursive, so that parts of the data may be matched against ***sub-patterns***. A pattern is tested against a value in a number of contexts: @@ -11,7 +11,7 @@ A pattern is tested against a value in a number of contexts: - In a switch expression, the *pattern* of a *switch_expression_arm* is tested against the expression on the switch-expression’s left-hand-side. - In nested contexts, the *sub-pattern* is tested against values retrieved from properties, fields, or indexed from other input values, depending on the pattern form. -The value against which a pattern is tested is called the ***pattern input value***. +The value against which a pattern is tested is called the ***pattern input value***. Patterns may be combined using Boolean logic. ## 11.2 Pattern forms @@ -21,12 +21,16 @@ A pattern may have one of the following forms: ```ANTLR pattern - : declaration_pattern + : '(' pattern ')' + | declaration_pattern | constant_pattern | var_pattern | positional_pattern | property_pattern | discard_pattern + | type_pattern + | relational_pattern + | logical_pattern ; ``` @@ -406,6 +410,157 @@ It is a compile-time error to use a discard pattern in a *relational_expression* > Here, a discard pattern is used to handle `null` and any integer value that doesn’t have the corresponding member of the `DayOfWeek` enumeration. That guarantees that the `switch` expression handles all possible input values. > *end example* +### §type-pattern-new-clause Type pattern + +A *type_pattern* is used to test that the pattern input value ([§11.1](patterns.md#111-general)) has a given type. + +```ANTLR +type_pattern + : type + ; +``` + +The runtime type of the value is tested against *type* using the same rules specified in the is-type operator ([§12.14.12.1](expressions.md#1214121-the-is-type-operator)). If the test succeeds, the pattern matches that value. It is a compile-time error if the *type* is a nullable type. This pattern form never matches a `null` value. + +### §relational-pattern-new-clause Relational pattern + +A *relational_pattern* is used to relationally test the pattern input value ([§11.1](patterns.md#111-general)) against a constant value. + +```ANTLR +relational_pattern + : '<' constant_expression + | '<=' constant_expression + | '>' constant_expression + | '>=' constant_expression + ; +``` + +Relational patterns support the relational operators `<`, `<=`, `>`, and `>=` on all of the built-in types that support such binary relational operators with both operands having the same type: `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `char`, `float`, `double`, `decimal`, `nint`, `nuint`, and enums. + +It is a compile-time error if `constant_expression`is `double.NaN`, `float.NaN`, or `null_literal`. + +When the input value has a type for which a suitable built-in binary relational operator is defined, the evaluation of that operator is taken as the meaning of the relational pattern. Otherwise, the input value is converted to the type of `constant_expression` using an explicit nullable or unboxing conversion. It is a compile-time error if no such conversion exists. The pattern is considered to not match if the conversion fails. If the conversion succeeds, the result of the pattern-matching operation is the result of evaluating the expression `e «op» v` where `e` is the converted input, «op» is the relational operator, and `v` is the `constant_expression`. + +> *Example*: +> +> +> ```csharp +> Console.WriteLine(Classify(13)); +> Console.WriteLine(Classify(double.NaN)); +> Console.WriteLine(Classify(2.4)); +> +> static string Classify(double measurement) => measurement switch +> { +> < -4.0 => "Too low", +> > 10.0 => "Too high", +> double.NaN => "Unknown", +> _ => "Acceptable", +> }; +> ``` +> +> The output produced is +> +> ```console +> Too high +> Unknown +> Acceptable +> ``` +> +> *end example* + +### §logical-pattern-new-clause Logical pattern + +A *logical_pattern* is used to negate a pattern input value ([§11.1](patterns.md#111-general)) or to combine that value with a pattern using a Boolean operator. + +```ANTLR +logical_pattern + : disjunctive_pattern + ; + +disjunctive_pattern + : disjunctive_pattern 'or' conjunctive_pattern + | conjunctive_pattern + ; + +conjunctive_pattern + : conjunctive_pattern 'and' negated_pattern + | negated_pattern + ; + +negated_pattern + : 'not' negated_pattern + | pattern + ; +``` + +`not`, `and`, and `or` are collectively called ***pattern operators***. + +A *negated_pattern* matches if the pattern being negated does not match, and vice versa. A *conjunctive_pattern* requires both patterns to match. A *disjunctive_pattern* requires either pattern to match. Unlike their language operator counterparts, `&&` and `||`, `and` and `or` are *not* short-circuiting operators. + +> *Note*: As indicated by the grammar, `not` has precedence over `and`, which has precedence over `or`. This can be explicitly indicated or overridden by using parentheses. *end note* + +When a *pattern* is used with `is`, any pattern operators in that *pattern* have higher precedence than their logical operator counterparts. Otherwise, those pattern operators have lower precedence. + +> *Example*: +> +> +> ```csharp +> Console.WriteLine(Classify(13)); +> Console.WriteLine(Classify(-100)); +> Console.WriteLine(Classify(5.7)); +> +> static string Classify(double measurement) => measurement switch +> { +> < -40.0 => "Too low", +> >= -40.0 and < 0 => "Low", +> >= 0 and < 10.0 => "Acceptable", +> >= 10.0 and < 20.0 => "High", +> >= 20.0 => "Too high", +> double.NaN => "Unknown", +> }; +> ``` +> +> The output produced is +> +> ```console +> High +> Too low +> Acceptable +> ``` +> +> *end example* + + + +> *Example*: +> +> +> ```csharp +> Console.WriteLine(GetCalendarSeason(new DateTime(2021, 1, 19))); +> Console.WriteLine(GetCalendarSeason(new DateTime(2021, 10, 9))); +> Console.WriteLine(GetCalendarSeason(new DateTime(2021, 5, 11))); +> +> static string GetCalendarSeason(DateTime date) => date.Month switch +> { +> 3 or 4 or 5 => "spring", +> 6 or 7 or 8 => "summer", +> 9 or 10 or 11 => "autumn", +> 12 or 1 or 2 => "winter", +> _ => throw new ArgumentOutOfRangeException(nameof(date), +> $"Date with unexpected month: {date.Month}."), +> }; +> ``` +> +> The output produced is +> +> ```console +> winter +> autumn +> spring +> ``` +> +> *end example* + ## 11.3 Pattern subsumption In a switch statement, it is an error if a case’s pattern is *subsumed* by the preceding set of unguarded cases ([§13.8.3](statements.md#1383-the-switch-statement)). From e6d573a1010be560d203127834e815981476419e Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 19 Feb 2026 12:47:21 -0500 Subject: [PATCH 02/13] Address lined comments Address the comments on specific lines in #1026. --- standard/patterns.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/standard/patterns.md b/standard/patterns.md index c495108bd..5f818ff5e 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -11,7 +11,7 @@ A pattern is tested against a value in a number of contexts: - In a switch expression, the *pattern* of a *switch_expression_arm* is tested against the expression on the switch-expression’s left-hand-side. - In nested contexts, the *sub-pattern* is tested against values retrieved from properties, fields, or indexed from other input values, depending on the pattern form. -The value against which a pattern is tested is called the ***pattern input value***. Patterns may be combined using Boolean logic. +The value against which a pattern is tested is called the ***pattern input value***. ## 11.2 Pattern forms @@ -34,6 +34,8 @@ pattern ; ``` +The `'(' pattern ')'` production allows a pattern to be enclosed in parentheses to enforce the order of evaluation among patterns combined using one of the *logical_pattern*s. + Some *pattern*s can result in the declaration of a local variable. Each pattern form defines the set of types for input values that the pattern may be applied to. A pattern `P` is *applicable to* a type `T` if `T` is among the types whose values the pattern may match. It is a compile-time error if a pattern `P` appears in a program to match a pattern input value ([§11.1](patterns.md#111-general)) of type `T` if `P` is not applicable to `T`. @@ -437,7 +439,7 @@ relational_pattern Relational patterns support the relational operators `<`, `<=`, `>`, and `>=` on all of the built-in types that support such binary relational operators with both operands having the same type: `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `char`, `float`, `double`, `decimal`, `nint`, `nuint`, and enums. -It is a compile-time error if `constant_expression`is `double.NaN`, `float.NaN`, or `null_literal`. +It is a compile-time error if `constant_expression` evaluates to one of `double.NaN`, `float.NaN`, or `null_literal`. When the input value has a type for which a suitable built-in binary relational operator is defined, the evaluation of that operator is taken as the meaning of the relational pattern. Otherwise, the input value is converted to the type of `constant_expression` using an explicit nullable or unboxing conversion. It is a compile-time error if no such conversion exists. The pattern is considered to not match if the conversion fails. If the conversion succeeds, the result of the pattern-matching operation is the result of evaluating the expression `e «op» v` where `e` is the converted input, «op» is the relational operator, and `v` is the `constant_expression`. @@ -470,7 +472,7 @@ When the input value has a type for which a suitable built-in binary relational ### §logical-pattern-new-clause Logical pattern -A *logical_pattern* is used to negate a pattern input value ([§11.1](patterns.md#111-general)) or to combine that value with a pattern using a Boolean operator. +A *logical_pattern* is used to negate the result of matching a pattern input value ([§11.1](patterns.md#111-general)) or to combine that match result with a pattern using a Boolean operator. ```ANTLR logical_pattern @@ -560,6 +562,33 @@ When a *pattern* is used with `is`, any pattern operators in that *pattern* have > ``` > > *end example* + + + +> *Example*: +> +> +> ```csharp +> object obj = 5; +> bool flag = true; +> +> // This is parsed as: (obj is (int or string)) && flag +> bool result = obj is int or string && flag; +> Console.WriteLine($"obj (5), flag (true): obj is int or string && flag: {result}"); // True +> +> // This is parsed as: (obj is int) || ((obj is string) && flag) +> result = obj is int || obj is string && flag; +> Console.WriteLine($"obj (5), flag (true): obj is int || obj is string && flag: {result}"); // True +> +> flag = false; +> // This is parsed as: (obj is (int or string)) && flag +> result = obj is int or string && flag; +> Console.WriteLine($"obj (5), flag (false): obj is int or string && flag: {result}"); // False +> +> // This is parsed as: (obj is int) || ((obj is string) && flag) +> result = obj is int || obj is string && flag; +> Console.WriteLine($"obj (5), flag (false): obj is int || obj is string && flag: {result}"); // True +> ``` ## 11.3 Pattern subsumption From bc879d5e206abb83b84ebcd67a014edb2740e798 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 19 Feb 2026 14:38:02 -0500 Subject: [PATCH 03/13] Address general comment Address the comments in the general review comment on #1026: - I did continue to use the *logical_pattern* production. We use that term in the text, and it's a good shorthand so readers don't need to snake through the grammar of *disjunctive_pattern*, *conjunctive_pattern* and *negated_pattern*. - I haven't addressed or created issues for the open questions in the proposal yet. --- standard/patterns.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/standard/patterns.md b/standard/patterns.md index 5f818ff5e..e18c28cda 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -21,16 +21,24 @@ A pattern may have one of the following forms: ```ANTLR pattern - : '(' pattern ')' + : logical_pattern + ; + +primary_pattern + : parenthesized_pattern | declaration_pattern | constant_pattern | var_pattern | positional_pattern | property_pattern | discard_pattern + | parenthesized_pattern | type_pattern | relational_pattern - | logical_pattern + ; + +parenthesized_pattern + : '(' pattern ')' ; ``` @@ -430,10 +438,10 @@ A *relational_pattern* is used to relationally test the pattern input value ([§ ```ANTLR relational_pattern - : '<' constant_expression - | '<=' constant_expression - | '>' constant_expression - | '>=' constant_expression + : '<' relational_expression + | '<=' relational_expression + | '>' relational_expression + | '>=' relational_expression ; ``` @@ -491,7 +499,7 @@ conjunctive_pattern negated_pattern : 'not' negated_pattern - | pattern + | primary_pattern ; ``` From 96045c42ff604a15b120269759c4314ebe93a710 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 19 Feb 2026 15:42:36 -0500 Subject: [PATCH 04/13] Fix build issue --- standard/patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/patterns.md b/standard/patterns.md index e18c28cda..c58571daf 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -575,7 +575,7 @@ When a *pattern* is used with `is`, any pattern operators in that *pattern* have > *Example*: > -> +> > ```csharp > object obj = 5; > bool flag = true; From 23a7dd9e2aee3b954013cc3f8ff44d725da911e7 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 19 Feb 2026 16:04:11 -0500 Subject: [PATCH 05/13] Add closing tag --- standard/patterns.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/standard/patterns.md b/standard/patterns.md index c58571daf..cd7d814cd 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -597,6 +597,8 @@ When a *pattern* is used with `is`, any pattern operators in that *pattern* have > result = obj is int || obj is string && flag; > Console.WriteLine($"obj (5), flag (false): obj is int || obj is string && flag: {result}"); // True > ``` +> +> *end example* ## 11.3 Pattern subsumption From b6ee64b6cc17f7e32c64ce7d91a2921c5859294e Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 19 Feb 2026 16:07:12 -0500 Subject: [PATCH 06/13] fix output --- standard/patterns.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/standard/patterns.md b/standard/patterns.md index cd7d814cd..d7db229ac 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -582,22 +582,32 @@ When a *pattern* is used with `is`, any pattern operators in that *pattern* have > > // This is parsed as: (obj is (int or string)) && flag > bool result = obj is int or string && flag; -> Console.WriteLine($"obj (5), flag (true): obj is int or string && flag: {result}"); // True +> Console.WriteLine($"obj (5), flag (true): obj is int or string && flag: {result}"); > > // This is parsed as: (obj is int) || ((obj is string) && flag) > result = obj is int || obj is string && flag; -> Console.WriteLine($"obj (5), flag (true): obj is int || obj is string && flag: {result}"); // True +> Console.WriteLine($"obj (5), flag (true): obj is int || obj is string && flag: {result}"); > > flag = false; > // This is parsed as: (obj is (int or string)) && flag > result = obj is int or string && flag; -> Console.WriteLine($"obj (5), flag (false): obj is int or string && flag: {result}"); // False +> Console.WriteLine($"obj (5), flag (false): obj is int or string && flag: {result}"); > > // This is parsed as: (obj is int) || ((obj is string) && flag) > result = obj is int || obj is string && flag; -> Console.WriteLine($"obj (5), flag (false): obj is int || obj is string && flag: {result}"); // True +> Console.WriteLine($"obj (5), flag (false): obj is int || obj is string && flag: {result}"); > ``` > +> The output produced is +> +> ```console +> True +> True +> False +> True +> ``` +> +> > *end example* ## 11.3 Pattern subsumption From 4339e87cf66a234f910f0364c8818ce4c112a3ec Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 19 Feb 2026 16:10:36 -0500 Subject: [PATCH 07/13] more fixing the output --- standard/patterns.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/standard/patterns.md b/standard/patterns.md index d7db229ac..b3d6df247 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -601,10 +601,10 @@ When a *pattern* is used with `is`, any pattern operators in that *pattern* have > The output produced is > > ```console -> True -> True -> False -> True +> obj (5), flag (true): obj is int or string && flag: True +> obj (5), flag (true): obj is int || obj is string && flag: True +> obj (5), flag (false): obj is int or string && flag: False +> obj (5), flag (false): obj is int || obj is string && flag: True > ``` > > From cc0d4b968f504c0cb0ca6cd3a038fe0eb3ab1229 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 19 Feb 2026 17:28:32 -0500 Subject: [PATCH 08/13] Add LDM decisions --- standard/patterns.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/standard/patterns.md b/standard/patterns.md index b3d6df247..d5ae64152 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -507,6 +507,18 @@ negated_pattern A *negated_pattern* matches if the pattern being negated does not match, and vice versa. A *conjunctive_pattern* requires both patterns to match. A *disjunctive_pattern* requires either pattern to match. Unlike their language operator counterparts, `&&` and `||`, `and` and `or` are *not* short-circuiting operators. +In a *conjunctive_pattern*, the *input type* of the second pattern is narrowed by the *type narrowing* requirements of first pattern of the `and`. The *narrowed type* of a pattern `P` is defined as follows: + +- If `P` is a type pattern, the *narrowed type* is the type of the type pattern's type. +- Otherwise, if `P` is a declaration pattern, the *narrowed type* is the type of the declaration pattern's type. +- Otherwise, if `P` is a recursive pattern that gives an explicit type, the *narrowed type* is that type. +- Otherwise, if `P` is matched via the rules for `ITuple` in a *positional_pattern* (§11.2.5), the *narrowed type* is the type `System.Runtime.CompilerServices.ITuple`. +- Otherwise, if `P` is a constant pattern where the constant is not the null constant and where the expression has no *constant expression conversion* to the *input type*, the *narrowed type* is the type of the constant. +- Otherwise, if `P` is a relational pattern where the constant expression has no *constant expression conversion* to the *input type*, the *narrowed type* is the type of the constant. +- Otherwise, if `P` is an `or` pattern, the *narrowed type* is the common type of the *narrowed type* of the subpatterns if such a common type exists. For this purpose, the common type algorithm considers only identity, boxing, and implicit reference conversions, and it considers all subpatterns of a sequence of `or` patterns (ignoring parenthesized patterns). +- Otherwise, if `P` is an `and` pattern, the *narrowed type* is the *narrowed type* of the right pattern. Moreover, the *narrowed type* of the left pattern is the *input type* of the right pattern. +- Otherwise the *narrowed type* of `P` is `P`'s input type. + > *Note*: As indicated by the grammar, `not` has precedence over `and`, which has precedence over `or`. This can be explicitly indicated or overridden by using parentheses. *end note* When a *pattern* is used with `is`, any pattern operators in that *pattern* have higher precedence than their logical operator counterparts. Otherwise, those pattern operators have lower precedence. From 7d0185a74f216d8dab1b4ae826e4dde10acf9916 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Mon, 23 Feb 2026 16:20:47 -0500 Subject: [PATCH 09/13] Add subsumption and exhaustiveness Add the subsumption and exhaustiveness rules for the new patterns in V9. The subsumption/exhaustiveness rules in the Roslyn compiler use a BDD (binary decision diagram)-based algorithm that is more powerful than can be expressed with simple prose rules. These rules attempt to capture the *observable behavior* (what the compiler accepts/rejects) rather than the implementation algorithm. Where the compiler's algorithm is too complex to fully express (e.g., relational range analysis), the spec describes the intent and give examples. --- standard/expressions.md | 6 +++--- standard/patterns.md | 36 ++++++++++++++++++++++++++++++++---- 2 files changed, 35 insertions(+), 7 deletions(-) diff --git a/standard/expressions.md b/standard/expressions.md index ce868655b..79f403b79 100644 --- a/standard/expressions.md +++ b/standard/expressions.md @@ -3909,10 +3909,10 @@ If a switch expression is not subject to a *switch expression conversion*, then - The type of the *switch_expression* is the best common type [§12.6.3.16](expressions.md#126316-finding-the-best-common-type-of-a-set-of-expressions)) of the *switch_expression_arm_expression*s of the *switch_expression_arm*s, if such a type exists, and each *switch_expression_arm_expression* can be implicitly converted to that type. - It is an error if no such type exists. -It is an error if some *switch_expression_arm*’s pattern cannot affect the result because some previous pattern and guard will always match. +It is an error if some *switch_expression_arm*’s pattern is *subsumed* by ([§11.3](patterns.md#113-pattern-subsumption)) the set of patterns of preceding *switch_expression_arm*s of the switch expression that do not have a *case_guard* or whose *case_guard* is a constant expression with the value `true`. -A switch expression is said to be *exhaustive* if every value of its input is handled by at least one arm of the switch expression. The compiler shall produce a warning if a switch expression is not exhaustive. -At runtime, the result of the *switch_expression* is the value of the *expression* of the first *switch_expression_arm* for which the expression on the left-hand-side of the *switch_expression* matches the *switch_expression_arm*’s pattern, and for which the *case_guard* of the *switch_expression_arm*, if present, evaluates to `true`. If there is no such *switch_expression_arm*, the *switch_expression* throws an instance of the exception `System.InvalidOperationException` (or a class derived from that). +A switch expression is said to be *exhaustive* if the set of patterns of its *switch_expression_arm*s is *exhaustive* ([§11.4](patterns.md#114-pattern-exhaustiveness)) for the type of the switch expression's input. The compiler shall produce a warning if a switch expression is not exhaustive. +At runtime, the result of the *switch_expression* is the value of the *expression* of the first *switch_expression_arm* for which the expression on the left-hand-side of the *switch_expression* matches the *switch_expression_arm*’s pattern, and for which the *case_guard* of the *switch_expression_arm*, if present, evaluates to `true`. If there is no such *switch_expression_arm*, the *switch_expression* throws an instance of the exception `System.Runtime.CompilerServices.SwitchExpressionException`. > *Example*: The following converts values of an enum representing visual directions on an online map to the corresponding cardinal directions: > diff --git a/standard/patterns.md b/standard/patterns.md index d5ae64152..2aead9113 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -507,6 +507,10 @@ negated_pattern A *negated_pattern* matches if the pattern being negated does not match, and vice versa. A *conjunctive_pattern* requires both patterns to match. A *disjunctive_pattern* requires either pattern to match. Unlike their language operator counterparts, `&&` and `||`, `and` and `or` are *not* short-circuiting operators. +It is a compile-time error for a pattern variable to be declared beneath a `not` or `or` pattern operator. + +> *Note*: Because neither `not` nor `or` can produce a definite assignment for a pattern variable, it is an error to declare one in those positions. *end note* + In a *conjunctive_pattern*, the *input type* of the second pattern is narrowed by the *type narrowing* requirements of first pattern of the `and`. The *narrowed type* of a pattern `P` is defined as follows: - If `P` is a type pattern, the *narrowed type* is the type of the type pattern's type. @@ -628,13 +632,29 @@ In a switch statement, it is an error if a case’s pattern is *subsumed* by the Informally, this means that any input value would have been matched by one of the previous cases. The following rules define when a set of patterns subsumes a given pattern: -A pattern `P` *would match* a constant `K` if the specification for that pattern’s runtime behavior is that `P` matches `K`. +A pattern `P` *would match* a constant `K` if any of the following conditions hold: + +- the specification for that pattern's runtime behavior is that `P` matches `K`. +- `P` is a *type_pattern* for type `T` and `K` is not `null` and the runtime type of `K` is `T` or a type derived from `T` or a type that implements `T`. +- `P` is a *relational_pattern* with operator «op» and constant `v`, and the expression `K` «op» `v` would evaluate to `true`. +- `P` is a *negated_pattern* `not P₁` and `P₁` would not match `K`. +- `P` is a *conjunctive_pattern* `P₁ and P₂` and both `P₁` would match `K` and `P₂` would match `K`. +- `P` is a *disjunctive_pattern* `P₁ or P₂` and either `P₁` would match `K` or `P₂` would match `K`. +- `P` is a *discard_pattern*. A set of patterns `Q` *subsumes* a pattern `P` if any of the following conditions hold: -- `P` is a constant pattern and any of the patterns in the set `Q` would match `P`’s *converted value* +- `P` is a constant pattern and any of the patterns in the set `Q` would match `P`'s *converted value* - `P` is a var pattern and the set of patterns `Q` is *exhaustive* ([§11.4](patterns.md#114-pattern-exhaustiveness)) for the type of the pattern input value ([§11.1](patterns.md#111-general)), and either the pattern input value is not of a nullable type or some pattern in `Q` would match `null`. - `P` is a declaration pattern with type `T` and the set of patterns `Q` is *exhaustive* for the type `T` ([§11.4](patterns.md#114-pattern-exhaustiveness)). +- `P` is a *type_pattern* for type `T` and the set of patterns `Q` is *exhaustive* for the type `T`. +- `P` is a *relational_pattern* with operator «op» and constant value `v`, and for every value of the input type satisfying the relation «op» `v`, some pattern in the set `Q` would match that value. +- `P` is a *disjunctive_pattern* `P₁ or P₂` and the set of patterns `Q` subsumes `P₁` and `Q` subsumes `P₂`. +- `P` is a *conjunctive_pattern* `P₁ and P₂` and at least one of the following holds: `Q` subsumes `P₁`, or `Q` subsumes `P₂`. +- `P` is a *negated_pattern* `not P₁` and `Q` is *exhaustive* for the input type considering only the values not matched by `P₁`. +- `P` is a *discard_pattern* and the set of patterns `Q` is *exhaustive* for the type of the pattern input value, and either the pattern input value is not of a nullable type or some pattern in `Q` would match `null`. +- Some pattern in `Q` is a *disjunctive_pattern* `Q₁ or Q₂` and replacing that pattern with `Q₁` in `Q` would yield a set that subsumes `P`, or replacing it with `Q₂` would yield a set that subsumes `P`. +- Some pattern in `Q` is a *negated_pattern* `not Q₁` and `P` would not match any value that `Q₁` would match. ## 11.4 Pattern exhaustiveness @@ -644,8 +664,16 @@ The following rules define when a set of patterns is *exhaustive* for a type: A set of patterns `Q` is *exhaustive* for a type `T` if any of the following conditions hold: 1. `T` is an integral or enum type, or a nullable version of one of those, and for every possible value of `T`’s non-nullable underlying type, some pattern in `Q` would match that value; or -2. Some pattern in `Q` is a *var pattern*; or -3. Some pattern in `Q` is a *declaration pattern* for type `D`, and there is an identity conversion, an implicit reference conversion, or a boxing conversion from `T` to `D`. +1. Some pattern in `Q` is a *var pattern*; or +1. Some pattern in `Q` is a *declaration pattern* for type `D`, and there is an identity conversion, an implicit reference conversion, or a boxing conversion from `T` to `D`; or +1. Some pattern in `Q` is a *type_pattern* for type `D`, and there is an identity conversion, an implicit reference conversion, or a boxing conversion from `T` to `D`; or +1. Some pattern in `Q` is a *discard_pattern*; or +1. The patterns in `Q` include a combination of *relational_pattern*s and *constant_pattern*s whose ranges collectively cover every possible value of `T`'s non-nullable underlying type. For `float` and `double` types, this includes `System.Double.NaN` or `System.Single.NaN` respectively, since `NaN` is not matched by any relational pattern; or +1. Some pattern in `Q` is a *disjunctive_pattern* `P₁ or P₂`, and replacing that pattern with both `P₁` and `P₂` in `Q` yields a set that is *exhaustive* for `T`; or +1. Some pattern in `Q` is a *negated_pattern* `not P₁`, and the patterns in `Q` together with the values not matched by `P₁` cover every possible value of `T`. A *negated_pattern* `not P₁` is exhaustive by itself when `P₁` matches no possible value of `T`; or +1. Some pattern in `Q` is a *conjunctive_pattern* `P₁ and P₂`, and the set containing only `P₁` is *exhaustive* for `T` and the set containing only `P₂` is *exhaustive* for `T`. + +> *Note*: For floating-point types, the combination of patterns `< 0` and `>= 0` is *not* exhaustive because neither relational pattern matches `NaN`. A correct exhaustive set would be `< 0`, `>= 0`, and `double.NaN` (or `float.NaN`). *end note* > *Example*: > From c112a3690e3dbba616e408aa5d46e501e9ad29c3 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 27 Feb 2026 15:36:38 -0500 Subject: [PATCH 10/13] Editorial pass - Removed duplicate parenthesized_pattern from the primary_pattern production - Fixed relational pattern prose Added a sentence after the grammar: "The relational_expression in a relational_pattern is required to evaluate to a constant value." Replaced backtick-formatted `constant_expression` references with plain prose ("the expression", "the constant expression"). Changed `null_literal` to "a null constant" (it's a semantic constraint, not a syntactic one). --- standard/patterns.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/standard/patterns.md b/standard/patterns.md index 2aead9113..c6c5e9ec9 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -32,7 +32,6 @@ primary_pattern | positional_pattern | property_pattern | discard_pattern - | parenthesized_pattern | type_pattern | relational_pattern ; @@ -445,11 +444,13 @@ relational_pattern ; ``` +The *relational_expression* in a *relational_pattern* is required to evaluate to a constant value. + Relational patterns support the relational operators `<`, `<=`, `>`, and `>=` on all of the built-in types that support such binary relational operators with both operands having the same type: `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `char`, `float`, `double`, `decimal`, `nint`, `nuint`, and enums. -It is a compile-time error if `constant_expression` evaluates to one of `double.NaN`, `float.NaN`, or `null_literal`. +It is a compile-time error if the expression evaluates to `double.NaN`, `float.NaN`, or a null constant. -When the input value has a type for which a suitable built-in binary relational operator is defined, the evaluation of that operator is taken as the meaning of the relational pattern. Otherwise, the input value is converted to the type of `constant_expression` using an explicit nullable or unboxing conversion. It is a compile-time error if no such conversion exists. The pattern is considered to not match if the conversion fails. If the conversion succeeds, the result of the pattern-matching operation is the result of evaluating the expression `e «op» v` where `e` is the converted input, «op» is the relational operator, and `v` is the `constant_expression`. +When the input value has a type for which a suitable built-in binary relational operator is defined, the evaluation of that operator is taken as the meaning of the relational pattern. Otherwise, the input value is converted to the type of the constant expression using an explicit nullable or unboxing conversion. It is a compile-time error if no such conversion exists. The pattern is considered to not match if the conversion fails. If the conversion succeeds, the result of the pattern-matching operation is the result of evaluating the expression `e «op» v` where `e` is the converted input, «op» is the relational operator, and `v` is the constant expression. > *Example*: > From 38cd74a310e2d55a7dcac153ed87a185d1f6eb99 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 27 Feb 2026 15:41:53 -0500 Subject: [PATCH 11/13] Use consistent `ITuple` This was in the incorrect namespace --- standard/patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/patterns.md b/standard/patterns.md index c6c5e9ec9..7590ee339 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -517,7 +517,7 @@ In a *conjunctive_pattern*, the *input type* of the second pattern is narrowed b - If `P` is a type pattern, the *narrowed type* is the type of the type pattern's type. - Otherwise, if `P` is a declaration pattern, the *narrowed type* is the type of the declaration pattern's type. - Otherwise, if `P` is a recursive pattern that gives an explicit type, the *narrowed type* is that type. -- Otherwise, if `P` is matched via the rules for `ITuple` in a *positional_pattern* (§11.2.5), the *narrowed type* is the type `System.Runtime.CompilerServices.ITuple`. +- Otherwise, if `P` is matched via the rules for `ITuple` in a *positional_pattern* (§11.2.5), the *narrowed type* is the type `System.ITuple`. - Otherwise, if `P` is a constant pattern where the constant is not the null constant and where the expression has no *constant expression conversion* to the *input type*, the *narrowed type* is the type of the constant. - Otherwise, if `P` is a relational pattern where the constant expression has no *constant expression conversion* to the *input type*, the *narrowed type* is the type of the constant. - Otherwise, if `P` is an `or` pattern, the *narrowed type* is the common type of the *narrowed type* of the subpatterns if such a common type exists. For this purpose, the common type algorithm considers only identity, boxing, and implicit reference conversions, and it considers all subpatterns of a sequence of `or` patterns (ignoring parenthesized patterns). From 700f48c75ef9cbb9a879c9ab406e07103657132e Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 27 Feb 2026 15:44:05 -0500 Subject: [PATCH 12/13] Add consistent "Is applicable to" language MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applicability rule for type pattern: "A type pattern naming a type T is applicable to every type E for which E is pattern compatible with T (§11.2.2)." Applicability rule for relational pattern: "A relational_pattern is applicable to a type T if a suitable built-in binary relational operator is defined with both operands of type T, or if an explicit nullable or unboxing conversion exists from T to the type of the constant expression." --- standard/patterns.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/standard/patterns.md b/standard/patterns.md index 7590ee339..bd897ee4a 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -429,6 +429,8 @@ type_pattern ; ``` +A type pattern naming a type `T` is *applicable to* every type `E` for which `E` is *pattern compatible* with `T` (§11.2.2). + The runtime type of the value is tested against *type* using the same rules specified in the is-type operator ([§12.14.12.1](expressions.md#1214121-the-is-type-operator)). If the test succeeds, the pattern matches that value. It is a compile-time error if the *type* is a nullable type. This pattern form never matches a `null` value. ### §relational-pattern-new-clause Relational pattern @@ -448,6 +450,8 @@ The *relational_expression* in a *relational_pattern* is required to evaluate to Relational patterns support the relational operators `<`, `<=`, `>`, and `>=` on all of the built-in types that support such binary relational operators with both operands having the same type: `sbyte`, `byte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `char`, `float`, `double`, `decimal`, `nint`, `nuint`, and enums. +A *relational_pattern* is *applicable to* a type `T` if a suitable built-in binary relational operator is defined with both operands of type `T`, or if an explicit nullable or unboxing conversion exists from `T` to the type of the constant expression. + It is a compile-time error if the expression evaluates to `double.NaN`, `float.NaN`, or a null constant. When the input value has a type for which a suitable built-in binary relational operator is defined, the evaluation of that operator is taken as the meaning of the relational pattern. Otherwise, the input value is converted to the type of the constant expression using an explicit nullable or unboxing conversion. It is a compile-time error if no such conversion exists. The pattern is considered to not match if the conversion fails. If the conversion succeeds, the result of the pattern-matching operation is the result of evaluating the expression `e «op» v` where `e` is the converted input, «op» is the relational operator, and `v` is the constant expression. From 63eff4277ef941f237d0162a7145ea6f6149ff93 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 27 Feb 2026 15:49:27 -0500 Subject: [PATCH 13/13] binding vs. precedence in the `is` statement. --- standard/patterns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/standard/patterns.md b/standard/patterns.md index bd897ee4a..3ed71b599 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -485,7 +485,7 @@ When the input value has a type for which a suitable built-in binary relational ### §logical-pattern-new-clause Logical pattern -A *logical_pattern* is used to negate the result of matching a pattern input value ([§11.1](patterns.md#111-general)) or to combine that match result with a pattern using a Boolean operator. +A *logical_pattern* is used to negate the result of a pattern match, or to combine the results of multiple pattern matches using conjunction (`and`) or disjunction (`or`). ```ANTLR logical_pattern @@ -530,7 +530,7 @@ In a *conjunctive_pattern*, the *input type* of the second pattern is narrowed b > *Note*: As indicated by the grammar, `not` has precedence over `and`, which has precedence over `or`. This can be explicitly indicated or overridden by using parentheses. *end note* -When a *pattern* is used with `is`, any pattern operators in that *pattern* have higher precedence than their logical operator counterparts. Otherwise, those pattern operators have lower precedence. +When a *pattern* appears on the right-hand-side of `is`, the extent of the pattern is determined by the grammar; as a result, the pattern operators `and`, `or`, and `not` within the pattern bind more tightly than the logical operators `&&`, `||`, and `!` outside the pattern. > *Example*: >