From 7d92a1a414bf3d30bcf6493fd86fdc26ac731187 Mon Sep 17 00:00:00 2001 From: Rex Jaeschke Date: Mon, 2 Mar 2026 14:00:41 -0500 Subject: [PATCH 1/9] support list and slice patterns Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21570b74-c6f5-4fc5-ab6d-7546918d6ddb Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/patterns.md | 132 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) diff --git a/standard/patterns.md b/standard/patterns.md index a84e96f2d..965b1a618 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -40,6 +40,8 @@ primary_pattern | discard_pattern | type_pattern | relational_pattern + | list_pattern + | slice_pattern ; parenthesized_pattern @@ -802,3 +804,133 @@ When a *pattern* appears on the right-hand-side of `is`, the extent of the patte > ``` > > *end example* + + +### §list-pattern-new-clause List pattern + +A *list_pattern* matches a sequence of elements in a list or an array. + +```ANTLR +list_pattern + : list_pattern_clause simple_designation? + ; + +list_pattern_clause + : '[' (pattern (',' pattern)* ','?)? ']' + ; +``` + +A *list_pattern* is compatible with any type that is *countable* ([§14.7.1](classes.md#1471-general[rcj1.1])) as well as *indexable* ([§xxx](classes.md#xxx))[rcj2.1]—it has an accessible indexer that takes an `Index` as an argument, or an accessible indexer with a single `int` parameter. If both indexers are present, the former is preferred. (See ([§xxx](classes.md#xxx-implicit-index-support))[rcj3.1] for details of implicit index support.) + +A pattern of the form `expr is [1, 2, 3]` is equivalent to the following code: + +```csharp +expr.Length is 3 +&& expr[new Index(0, fromEnd: false)] is 1 +&& expr[new Index(1, fromEnd: false)] is 2 +&& expr[new Index(2, fromEnd: false)] is 3 +``` + +> *Example*: +> +> +> ```csharp +> int[] numbers = { 1, 2, 3 }; +> +> Console.WriteLine(numbers is [1, 2, 3]); // True +> Console.WriteLine(numbers is [1, 2, 4]); // False +> Console.WriteLine(numbers is [1, 2, 3, 4]); // False +> Console.WriteLine(numbers is [0 or 1, <= 2, >= 3 and not 7]); // True +> ``` +> +> *end example* + +The discard pattern ([§11.2.7](patterns.md#1127-discard-pattern)) matches any single element. + +> *Example*: +> +> +> ```csharp +> List numbers = new() { 1, 2, 3 }; +> +> if (numbers is [_, var second, _]) +> { +> Console.WriteLine($"The second element is {second}."); +> } +> ``` +> +> *end example* + +### §slice-pattern-new-clause Slice pattern + +A *slice_pattern* discards zero or more elements. It shall only be used directly in a *list_pattern_clause*, and then only once at most in that clause. + +```ANTLR +slice_pattern + : '..' pattern? + ; +``` + +A *slice_pattern* without a subpattern is compatible with any type that is compatible with a *list_pattern*. A *slice_pattern* with a subpattern is compatible with any type that is *countable* ([§14.7.1](classes.md#1471-general[rcj4.1])) as well as *sliceable* ([§xxx](classes.md#xxx))[rcj5.1]—it has an accessible indexer that takes a `Range` as an argument, or an accessible `Slice` method with two `int` parameters. If both are present, the former is preferred. (See ([§xxx](classes.md#xxx-implicit-index-support))[rcj6.1] for details of implicit index support.) + +A *slice_pattern* acts like a proper discard; that is, no tests shall be made for such pattern. Rather, it only affects other nodes, namely the length and indexer. For instance, a pattern of the form `expr is [1, .. var s, 3]` is equivalent to the following code (if compatible via explicit `Index` and `Range` support): + +```csharp +expr.Length is >= 2 +&& expr[new Index(0, fromEnd: false)] is 1 +&& expr[new Range(new Index(1, fromEnd: false), new Index(1, fromEnd: true))] is var s +&& expr[new Index(1, fromEnd: true)] is 3 +``` + +The input type for a *slice_pattern* is the return type of the underlying `this[Range]` or `Slice` method with two exceptions: For `string`s and arrays, `string.Substring` and `RuntimeHelpers.GetSubArray`, respectively, shall be used. + +> *Example*: A slice pattern can be used to match elements only at the start or/and the end of an input sequence. +> +> +> ```csharp +> Console.WriteLine(new[] { 1, 2, 3, 4, 5 } is [> 0, > 0, ..]); // True +> Console.WriteLine(new[] { 1, 1 } is [_, _, ..]); // True +> Console.WriteLine(new[] { 0, 1, 2, 3, 4 } is [> 0, > 0, ..]); // False +> Console.WriteLine(new[] { 1 } is [1, 2, ..]); // False +> +> Console.WriteLine(new[] { 1, 2, 3, 4 } is [.., > 0, > 0]); // True +> Console.WriteLine(new[] { 2, 4 } is [.., > 0, 2, 4]); // False +> Console.WriteLine(new[] { 2, 4 } is [.., 2, 4]); // True +> +> Console.WriteLine(new[] { 1, 2, 3, 4 } is [>= 0, .., 2 or 4]); // True +> Console.WriteLine(new[] { 1, 0, 0, 1 } is [1, 0, .., 0, 1]); // True +> Console.WriteLine(new[] { 1, 0, 1 } is [1, 0, .., 0, 1]); // False +> ``` +> +> *end example* + + + +> *Example*: A subpattern can be nested within a slice pattern: +> +> +> ```csharp +> MatchMessage("aBBA"); // output: Message aBBA matches; inner part is BB. +> MatchMessage("apron"); // output: Message apron doesn't match. +> +> void MatchMessage(string message) +> { +> var result = message is ['a' or 'A', .. var s, 'a' or 'A'] +> ? $"Message {message} matches; inner part is {s}." +> : $"Message {message} doesn't match."; +> Console.WriteLine(result); +> } +> +> Validate(new[] { -1, 0, 1 }); // output: not valid +> Validate(new[] { -1, 0, 0, 1 }); // output: valid +> +> void Validate(int[] numbers) +> { +> var result = numbers is [< 0, .. { Length: 2 or 4 }, > 0] +> ? "valid" : "not valid"; +> Console.WriteLine(result); +> } +> ``` +> +> *end example* + From 359d4b066719b4aab8dd61278ab38911a6b05085 Mon Sep 17 00:00:00 2001 From: Rex Jaeschke Date: Mon, 2 Mar 2026 16:51:33 -0500 Subject: [PATCH 2/9] support list and slice patterns Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21570b74-c6f5-4fc5-ab6d-7546918d6ddb Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/portability-issues.md | 1 + 1 file changed, 1 insertion(+) diff --git a/standard/portability-issues.md b/standard/portability-issues.md index 5dd7b3869..bd67737c5 100644 --- a/standard/portability-issues.md +++ b/standard/portability-issues.md @@ -10,6 +10,7 @@ This annex collects some information about portability that appears in this spec The behavior is undefined in the following circumstances: +1. If certain assumptions re pattern subsumption do not hold ([§11.3](patterns.md#113-pattern-assumptions)). 1. The behavior of the enclosing async function when an awaiter’s implementation of the interface methods `INotifyCompletion.OnCompleted` and `ICriticalNotifyCompletion.UnsafeOnCompleted` does not cause the resumption delegate to be invoked at most once ([§12.9.9.4](expressions.md#12994-run-time-evaluation-of-await-expressions)). 1. Passing pointers as `ref` or `out` parameters ([§24.3.2](unsafe-code.md#2432-data-pointers)). 1. When dereferencing the result of converting one pointer type to another and the resulting pointer is not correctly aligned for the pointed-to type. ([§24.5.1](unsafe-code.md#2451-general)). From 6d68e32177abf088fb725619069c6e287cbd10f5 Mon Sep 17 00:00:00 2001 From: Rex Jaeschke Date: Mon, 2 Mar 2026 17:18:25 -0500 Subject: [PATCH 3/9] support list and slice patterns Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21570b74-c6f5-4fc5-ab6d-7546918d6ddb Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/patterns.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/standard/patterns.md b/standard/patterns.md index 965b1a618..367fa91d8 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -820,7 +820,7 @@ list_pattern_clause ; ``` -A *list_pattern* is compatible with any type that is *countable* ([§14.7.1](classes.md#1471-general[rcj1.1])) as well as *indexable* ([§xxx](classes.md#xxx))[rcj2.1]—it has an accessible indexer that takes an `Index` as an argument, or an accessible indexer with a single `int` parameter. If both indexers are present, the former is preferred. (See ([§xxx](classes.md#xxx-implicit-index-support))[rcj3.1] for details of implicit index support.) +A *list_pattern* is compatible with any type that is *countable* ([§18.1](ranges.md#181-general)) as well as *indexable* ([§18.1](ranges.md#181-general))—it has an accessible indexer that takes an `Index` as an argument, or an accessible indexer with a single `int` parameter. If both indexers are present, the former is preferred. (See [§18.4.2](ranges.md#1842-implicit-index-support) for details of implicit index support.) A pattern of the form `expr is [1, 2, 3]` is equivalent to the following code: @@ -871,7 +871,7 @@ slice_pattern ; ``` -A *slice_pattern* without a subpattern is compatible with any type that is compatible with a *list_pattern*. A *slice_pattern* with a subpattern is compatible with any type that is *countable* ([§14.7.1](classes.md#1471-general[rcj4.1])) as well as *sliceable* ([§xxx](classes.md#xxx))[rcj5.1]—it has an accessible indexer that takes a `Range` as an argument, or an accessible `Slice` method with two `int` parameters. If both are present, the former is preferred. (See ([§xxx](classes.md#xxx-implicit-index-support))[rcj6.1] for details of implicit index support.) +A *slice_pattern* without a subpattern is compatible with any type that is compatible with a *list_pattern*. A *slice_pattern* with a subpattern is compatible with any type that is *countable* ([§18.1](ranges.md#181-general)) as well as *sliceable* ([§18.1](ranges.md#181-general))—it has an accessible indexer that takes a `Range` as an argument, or an accessible `Slice` method with two `int` parameters. If both are present, the former is preferred. (See [§18.4.2](ranges.md#1842-implicit-index-support) for details of implicit index support.) A *slice_pattern* acts like a proper discard; that is, no tests shall be made for such pattern. Rather, it only affects other nodes, namely the length and indexer. For instance, a pattern of the form `expr is [1, .. var s, 3]` is equivalent to the following code (if compatible via explicit `Index` and `Range` support): From f352e07a76ab6ea500ab002e33e5894bac832b4f Mon Sep 17 00:00:00 2001 From: Rex Jaeschke Date: Mon, 2 Mar 2026 17:34:06 -0500 Subject: [PATCH 4/9] fix link Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21570b74-c6f5-4fc5-ab6d-7546918d6ddb Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/portability-issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/portability-issues.md b/standard/portability-issues.md index bd67737c5..aad3c57ee 100644 --- a/standard/portability-issues.md +++ b/standard/portability-issues.md @@ -10,7 +10,7 @@ This annex collects some information about portability that appears in this spec The behavior is undefined in the following circumstances: -1. If certain assumptions re pattern subsumption do not hold ([§11.3](patterns.md#113-pattern-assumptions)). +1. If certain assumptions re pattern subsumption do not hold ([§11.3](patterns.md#113-pattern-subsumption)). 1. The behavior of the enclosing async function when an awaiter’s implementation of the interface methods `INotifyCompletion.OnCompleted` and `ICriticalNotifyCompletion.UnsafeOnCompleted` does not cause the resumption delegate to be invoked at most once ([§12.9.9.4](expressions.md#12994-run-time-evaluation-of-await-expressions)). 1. Passing pointers as `ref` or `out` parameters ([§24.3.2](unsafe-code.md#2432-data-pointers)). 1. When dereferencing the result of converting one pointer type to another and the resulting pointer is not correctly aligned for the pointed-to type. ([§24.5.1](unsafe-code.md#2451-general)). From 4a3288115d623654971485e227ac42bcf6124de3 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Mon, 4 May 2026 11:18:07 -0400 Subject: [PATCH 5/9] review and minor fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix four issues in patterns.md: Remove the stray [ at end of the subsumption "assumptions" block (line ~748: …doesn't hold.[). Remove the leading space in the SlicePattern2 example annotation: name:" SlicePattern2" → name:"SlicePattern2" (would otherwise break ExampleExtractor lookups). Collapse three double-spaces in the new sections: …1842-implicit-index-support) for details, A slice pattern can be used, expr is [1, .. var s, 3] is equivalent. Fix one issue in portability-issues.md: Reword "re pattern subsumption" → "regarding pattern subsumption" to match the rest of that file's prose. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21570b74-c6f5-4fc5-ab6d-7546918d6ddb Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/portability-issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/portability-issues.md b/standard/portability-issues.md index aad3c57ee..ef5f3a786 100644 --- a/standard/portability-issues.md +++ b/standard/portability-issues.md @@ -10,7 +10,7 @@ This annex collects some information about portability that appears in this spec The behavior is undefined in the following circumstances: -1. If certain assumptions re pattern subsumption do not hold ([§11.3](patterns.md#113-pattern-subsumption)). +1. If certain assumptions regarding pattern subsumption do not hold ([§11.3](patterns.md#113-pattern-subsumption)). 1. The behavior of the enclosing async function when an awaiter’s implementation of the interface methods `INotifyCompletion.OnCompleted` and `ICriticalNotifyCompletion.UnsafeOnCompleted` does not cause the resumption delegate to be invoked at most once ([§12.9.9.4](expressions.md#12994-run-time-evaluation-of-await-expressions)). 1. Passing pointers as `ref` or `out` parameters ([§24.3.2](unsafe-code.md#2432-data-pointers)). 1. When dereferencing the result of converting one pointer type to another and the resulting pointer is not correctly aligned for the pointed-to type. ([§24.5.1](unsafe-code.md#2451-general)). From c456dce071ed8bfce15ac508b191455c5e709023 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 18 Sep 2026 16:58:07 -0400 Subject: [PATCH 6/9] Remove retired pattern subsumption reference Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21570b74-c6f5-4fc5-ab6d-7546918d6ddb Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/portability-issues.md | 1 - 1 file changed, 1 deletion(-) diff --git a/standard/portability-issues.md b/standard/portability-issues.md index ef5f3a786..5dd7b3869 100644 --- a/standard/portability-issues.md +++ b/standard/portability-issues.md @@ -10,7 +10,6 @@ This annex collects some information about portability that appears in this spec The behavior is undefined in the following circumstances: -1. If certain assumptions regarding pattern subsumption do not hold ([§11.3](patterns.md#113-pattern-subsumption)). 1. The behavior of the enclosing async function when an awaiter’s implementation of the interface methods `INotifyCompletion.OnCompleted` and `ICriticalNotifyCompletion.UnsafeOnCompleted` does not cause the resumption delegate to be invoked at most once ([§12.9.9.4](expressions.md#12994-run-time-evaluation-of-await-expressions)). 1. Passing pointers as `ref` or `out` parameters ([§24.3.2](unsafe-code.md#2432-data-pointers)). 1. When dereferencing the result of converting one pointer type to another and the resulting pointer is not correctly aligned for the pointed-to type. ([§24.5.1](unsafe-code.md#2451-general)). From 56cdfcdf5f08b3858b9004376d9c9e29727db929 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 18 Sep 2026 17:13:24 -0400 Subject: [PATCH 7/9] Remove extra list-pattern blank lines Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21570b74-c6f5-4fc5-ab6d-7546918d6ddb Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/patterns.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/standard/patterns.md b/standard/patterns.md index 367fa91d8..c8ac9ea55 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -805,7 +805,6 @@ When a *pattern* appears on the right-hand-side of `is`, the extent of the patte > > *end example* - ### §list-pattern-new-clause List pattern A *list_pattern* matches a sequence of elements in a list or an array. @@ -933,4 +932,3 @@ The input type for a *slice_pattern* is the return type of the underlying `this[ > ``` > > *end example* - From eb8e1b035170c4cacd574da18304b0a35e12a8b8 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Mon, 21 Sep 2026 14:59:52 -0400 Subject: [PATCH 8/9] Fix slice pattern example project name Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: bce5e82a-89fd-4655-bc08-6d6ba97f0cc6 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 21570b74-c6f5-4fc5-ab6d-7546918d6ddb Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 361b9a77-2b4c-45e6-969f-e6785c47f27e --- standard/patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/patterns.md b/standard/patterns.md index c8ac9ea55..7942817d3 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -907,7 +907,7 @@ The input type for a *slice_pattern* is the return type of the underlying `this[ > *Example*: A subpattern can be nested within a slice pattern: > -> +> > ```csharp > MatchMessage("aBBA"); // output: Message aBBA matches; inner part is BB. > MatchMessage("apron"); // output: Message apron doesn't match. From e662f0d6c378d8a49a6e8fafd11db993f38390f7 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 17 Nov 2026 18:11:47 -0500 Subject: [PATCH 9/9] Add additional pattern details. --- standard/patterns.md | 63 +++++++++++++++++++++++++++++++------------- 1 file changed, 44 insertions(+), 19 deletions(-) diff --git a/standard/patterns.md b/standard/patterns.md index 7942817d3..b82b01dda 100644 --- a/standard/patterns.md +++ b/standard/patterns.md @@ -15,6 +15,8 @@ The value against which a pattern is tested is called the ***pattern input value A pattern `P` is *subsumed* by set of unguarded patterns `Q` if any input value matched by `P` is matched by one of the members of `Q`. +The length and element-position constraints and shape assumptions for list and slice patterns are specified in §list-pattern-new-clause. + In a switch statement ([§13.8.3](statements.md#1383-the-switch-statement)), it is an error if a case’s pattern is *subsumed* by the preceding set of *unguarded* ([§13.8.3](statements.md#1383-the-switch-statement)) cases. In a switch expression ([§12.12](expressions.md#1212-switch-expression)), it is an error if a *switch_expression_arm*’s pattern is *subsumed* by the preceding set of *unguarded* *switch_expression_arm*s’ patterns. A set of patterns is exhaustive if, for every possible input value, some pattern in the set is applicable. When an implementation detects that a set of patterns is not exhaustive, it shall issue a warning. @@ -85,7 +87,7 @@ Each pattern form defines the set of types for input values that the pattern may Each pattern form defines the set of values for which the pattern *matches* the value at runtime. -The order of evaluation of operations and side effects during pattern-matching (calls to `Deconstruct`, property accesses, and invocations of members of `System.Runtime.CompilerServices.ITuple`) is not specified. +The order of evaluation of operations and side effects during pattern-matching (calls to `Deconstruct`, property accesses, indexer accesses, slicing operations, and invocations of members of `System.Runtime.CompilerServices.ITuple`) is not specified. ### 11.2.2 Declaration pattern @@ -690,6 +692,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 a list pattern whose *input type* is a nullable value type, the *narrowed type* is the underlying type of the *input type*. - Otherwise, if `P` is matched via the rules for `ITuple` in a *positional_pattern* ([§11.2.5](patterns.md#1125-positional-pattern)), 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. @@ -819,17 +822,33 @@ list_pattern_clause ; ``` -A *list_pattern* is compatible with any type that is *countable* ([§18.1](ranges.md#181-general)) as well as *indexable* ([§18.1](ranges.md#181-general))—it has an accessible indexer that takes an `Index` as an argument, or an accessible indexer with a single `int` parameter. If both indexers are present, the former is preferred. (See [§18.4.2](ranges.md#1842-implicit-index-support) for details of implicit index support.) +Let `T` be the input type, or its underlying type if it is a nullable value type. A *list_pattern* is applicable to its input type if `T` is *countable* ([§18.1](ranges.md#181-general)) as well as *indexable* ([§18.1](ranges.md#181-general))—it has an accessible indexer that takes an `Index` as an argument, or an accessible indexer with a single `int` parameter. If both indexers are present, the former is preferred. (See [§18.4.2](ranges.md#1842-implicit-index-support) for details of implicit index support.) The countable property and indexer selected by these rules are used for matching. -A pattern of the form `expr is [1, 2, 3]` is equivalent to the following code: +The expression supplying the input value is evaluated only once. A *list_pattern* matches a non-null input value when all of the following conditions are satisfied: -```csharp -expr.Length is 3 -&& expr[new Index(0, fromEnd: false)] is 1 -&& expr[new Index(1, fromEnd: false)] is 2 -&& expr[new Index(2, fromEnd: false)] is 3 -``` +- The length represented by the selected countable property is equal to the number of patterns in the *list_pattern_clause* if there is no *slice_pattern*, or at least the number of patterns other than the *slice_pattern* otherwise. +- Each element pattern matches its corresponding element. Elements before a *slice_pattern*, or in a list pattern without one, are indexed from the start, beginning at zero. Elements after a *slice_pattern* are indexed from the end, with the last element at from-end index one. The element input value and type are those provided by the selected indexer at that position. +- The *slice_pattern*, if present, matches as specified in §slice-pattern-new-clause. + +For a nullable value type input, matching uses its underlying value. If the *simple_designation* is a *single_variable_designation*, it declares a local variable of type `T` that is assigned the matched input value when the pattern matches. Scope and definite assignment follow the rules for pattern variables ([§7.6](basic-concepts.md#76-scopes), [§9.4](variables.md#94-definite-assignment)). +For pattern matching on a countable, indexable type, the selected countable property is assumed to return a non-negative value. The selected slicing member is assumed to return a non-null slice containing exactly the elements in the requested range, in their original order. The behavior of a pattern-matching operation is undefined if these assumptions do not hold. + +Subsumption checking ([§11.1](patterns.md#111-general)) may rely on these assumptions and the constraints on length and element positions. Positions indexed from the start and from the end refer to the same element when the length makes their offsets equal. When a slice subpattern is a list pattern, its length and element constraints apply to the corresponding range of the containing input. A constraint on the selected countable property of a slice constrains the length of that range. + +> *Note*: For a non-null input stored in `expr`, with selected `Length` and `Index` members, the following illustrates the tests for `expr is [1, 2, 3]`. The displayed order of tests is illustrative; the order of pattern-matching operations is unspecified ([§11.2.1](patterns.md#1121-general)). +> +> ```csharp +> expr.Length is 3 +> && expr[new Index(0, fromEnd: false)] is 1 +> && expr[new Index(1, fromEnd: false)] is 2 +> && expr[new Index(2, fromEnd: false)] is 3 +> ``` +> +> *end note* + + + > *Example*: > > @@ -844,7 +863,7 @@ expr.Length is 3 > > *end example* -The discard pattern ([§11.2.7](patterns.md#1127-discard-pattern)) matches any single element. +The discard pattern ([§11.2.7](patterns.md#1127-discard-pattern)) matches any single element without accessing it. > *Example*: > @@ -870,19 +889,25 @@ slice_pattern ; ``` -A *slice_pattern* without a subpattern is compatible with any type that is compatible with a *list_pattern*. A *slice_pattern* with a subpattern is compatible with any type that is *countable* ([§18.1](ranges.md#181-general)) as well as *sliceable* ([§18.1](ranges.md#181-general))—it has an accessible indexer that takes a `Range` as an argument, or an accessible `Slice` method with two `int` parameters. If both are present, the former is preferred. (See [§18.4.2](ranges.md#1842-implicit-index-support) for details of implicit index support.) +A *slice_pattern* without a subpattern is applicable to any type to which a *list_pattern* is applicable. With a subpattern, the containing list pattern's type `T` shall also be *sliceable* ([§18.1](ranges.md#181-general)). It has an accessible indexer that takes a `Range` as an argument, or an accessible instance `Slice` method with two required `int` parameters. If both are present, the former is preferred. (See [§18.4.3](ranges.md#1843-implicit-range-support) for details of implicit range support.) -A *slice_pattern* acts like a proper discard; that is, no tests shall be made for such pattern. Rather, it only affects other nodes, namely the length and indexer. For instance, a pattern of the form `expr is [1, .. var s, 3]` is equivalent to the following code (if compatible via explicit `Index` and `Range` support): +A *slice_pattern* without a subpattern, or with a discard subpattern, matches without accessing a slice. When it is the only pattern in the containing *list_pattern_clause*, the countable property is not accessed. -```csharp -expr.Length is >= 2 -&& expr[new Index(0, fromEnd: false)] is 1 -&& expr[new Range(new Index(1, fromEnd: false), new Index(1, fromEnd: true))] is var s -&& expr[new Index(1, fromEnd: true)] is 3 -``` +Otherwise, let `p` and `q` be the numbers of element patterns before and after the slice pattern, respectively, and let `n` be the input length. The slice subpattern is tested against the value returned by the selected slicing member for the range starting at from-start index `p` and ending at from-end index `q`. For an `int`-based `Slice` method, the arguments are `p` and `n - p - q`. The slice pattern matches when its subpattern matches that value. The input type of the subpattern is the return type of the selected member. For strings and arrays, the slice subpattern is tested against the corresponding substring or subarray, with input types `string` and the input array type, respectively. -The input type for a *slice_pattern* is the return type of the underlying `this[Range]` or `Slice` method with two exceptions: For `string`s and arrays, `string.Substring` and `RuntimeHelpers.GetSubArray`, respectively, shall be used. +> *Note*: With the same illustrative conventions as in §list-pattern-new-clause, and selected `Length`, `Index`, and `Range` members, the tests for `expr is [1, .. var s, 3]` can be illustrated as follows: +> +> ```csharp +> expr.Length is >= 2 +> && expr[new Index(0, fromEnd: false)] is 1 +> && expr[new Range(new Index(1, fromEnd: false), new Index(1, fromEnd: true))] is var s +> && expr[new Index(1, fromEnd: true)] is 3 +> ``` +> +> *end note* + + > *Example*: A slice pattern can be used to match elements only at the start or/and the end of an input sequence. > >