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/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..3ed71b599 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: @@ -21,15 +21,28 @@ A pattern may have one of the following forms: ```ANTLR pattern - : declaration_pattern + : logical_pattern + ; + +primary_pattern + : parenthesized_pattern + | declaration_pattern | constant_pattern | var_pattern | positional_pattern | property_pattern | discard_pattern + | type_pattern + | relational_pattern + ; + +parenthesized_pattern + : '(' 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`. @@ -406,19 +419,247 @@ 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 + ; +``` + +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 + +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 + : '<' relational_expression + | '<=' relational_expression + | '>' relational_expression + | '>=' relational_expression + ; +``` + +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. + +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. + +> *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 the result of a pattern match, or to combine the results of multiple pattern matches using conjunction (`and`) or disjunction (`or`). + +```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 + | primary_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. + +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. +- 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.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* 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*: +> +> +> ```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* + + + +> *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}"); +> +> // 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}"); +> +> 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}"); +> +> // 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}"); +> ``` +> +> The output produced is +> +> ```console +> 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 +> ``` +> +> +> *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)). 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 @@ -428,8 +669,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*: >