Lets you to match an enumerable with a sequence of patterns e.g. enumerable is { 1, 2, 3 } will match a sequence of the length three with 1, 2, 3 as its elements.
The pattern syntax is unchanged:
primary_pattern
: list_pattern
| length_pattern
| slice_pattern
| // all of the pattern forms previously defined
;A length_pattern is now also compatible with any type that is not countable but is enumerable — it can be used in foreach.
A list_pattern is now also compatible with any type that is not indexable but is enumerable.
A slice_pattern without a subpattern is compatible with any type that is compatible with a list_pattern.
enumerable is { 1, 2, .. } // okay
enumerable is { 1, 2, ..var x } // error
If the input type is enumerable but not countable, then the length_pattern is checked on the number of elements obtained from enumerating the collection.
If the input type is enumerable but not indexable, then the list_pattern enumerates elements from the collection and checks them against the listed patterns:
Patterns at the start of the list_pattern — that are before the .. slice_pattern if one is present, or all otherwise — are matched against the elements produced at the start of the enumeration.
If the collection does not produce enough elements to get a value corresponding to a starting pattern, the match fails. So the constant_pattern 3 in { 1, 2, 3, .. } doesn't match when the collection has fewer than 3 elements.
Patterns at the end of the list_pattern (that are following the .. slice_pattern if one is present) are matched against the elements produced at the end of the enumeration.
If the collection does not produce enough elements to get values corresponding to the ending patterns, the slice_pattern does not match. So the slice_pattern in { 1, .., 3 } doesn't match when the collection has fewer than 2 elements.
A list_pattern without a slice_pattern only matches if the number of elements produced by complete enumeration and the number of patterns are equals. So { _, _, _ } only matches when the collection produces exactly 3 elements.
Note that those implicit checks for number of elements in the collection are unaffected by the collection type being countable. So { _, _, _ } will not make use of Length or Count even if one is available.
When multiple list_patterns are applied to one input value the collection will be enumerated once at most:
_ = collection switch
{
{ 1 } => ...,
{ 2 } => ...,
{ .., 3 } => ...,
};
_ = collectionContainer switch
{
{ Collection: { 1 } } => ...,
{ Collection: { 2 } } => ...,
{ Collection: { .., 3 } } => ...,
};
It is possible that the collection will not be completely enumerated. For example, if one of the patterns in the list_pattern doesn't match or when there are no ending patterns in a list_pattern (e.g. collection is { 1, 2, .. }).
If an enumerator is produced when a list_pattern is applied to an enumerable type and that enumerator is disposable it will be disposed when a top-level pattern containing the list_pattern successfully matches, or when none of the patterns match (in the case of a switch statement or expression). It is possible for an enumerator to be disposed more than once and the enumerator must ignore all calls to Dispose after the first one.
// any enumerator used to evaluate this switch statement is disposed at the indicated locations
_ = collection switch
{
{ 1 } => /* here */ ...,
_ => /* here */ ...,
};
/* here too, with a spilled try/finally around the switch expression */
Open question: Need to investigate how to reduce allocation for the end circular buffer.
stackallocis bad in loops. Maybe we'll just have to fall back to locals and aswitch. (seeparamsfeature discussion also)
Although a helper type is not necessary, it helps simplify and illustrate the logic.
class ListPatternHelper
{
// Notes:
// We could inline this logic to avoid creating a new type and to handle the pattern-based enumeration scenarios.
// We may only need one element in start buffer, or maybe none at all, if we can control the order of checks in the patterns DAG.
// We could emit a count check for a non-terminal `..` and economize on count checks a bit.
private EnumeratorType enumerator;
private int count;
private ElementType[] startBuffer;
private ElementType[] endCircularBuffer;
public ListPatternHelper(EnumerableType enumerable, int startPatternsCount, int endPatternsCount)
{
count = 0;
enumerator = enumerable.GetEnumerator();
startBuffer = startPatternsCount == 0 ? null : new ElementType[startPatternsCount];
endCircularBuffer = endPatternsCount == 0 ? null : new ElementType[endPatternsCount];
}
// targetIndex = -1 means we want to enumerate completely
private int MoveNextIfNeeded(int targetIndex)
{
int startSize = startBuffer?.Length ?? 0;
int endSize = endCircularBuffer?.Length ?? 0;
Debug.Assert(targetIndex == -1 || (targetIndex >= 0 && targetIndex < startSize));
while ((targetIndex == -1 || count <= targetIndex) && enumerator.MoveNext())
{
if (count < startSize)
startBuffer[count] = enumerator.Current;
if (endSize > 0)
endCircularBuffer[count % endSize] = enumerator.Current;
count++;
}
return count;
}
public bool Last()
{
return !enumerator.MoveNext();
}
public int Count()
{
return MoveNextIfNeeded(-1);
}
// fulfills the role of `[index]` for start elements when enough elements are available
public bool TryGetStartElement(int index, out ElementType value)
{
Debug.Assert(startBuffer is not null && index >= 0 && index < startBuffer.Length);
MoveNextIfNeeded(index);
if (count > index)
{
value = startBuffer[index];
return true;
}
value = default;
return false;
}
// fulfills the role of `[^hatIndex]` for end elements when enough elements are available
public ElementType GetEndElement(int hatIndex)
{
Debug.Assert(endCircularBuffer is not null && hatIndex > 0 && hatIndex <= endCircularBuffer.Length);
int endSize = endCircularBuffer.Length;
Debug.Assert(endSize > 0);
return endCircularBuffer[(count - hatIndex) % endSize];
}
}
collection is [3] is lowered to
@{
var helper = new ListPatternHelper(collection, 0, 0);
helper.Count() == 3
}
collection is { 0, 1 } is lowered to
@{
var helper = new ListPatternHelper(collection, 2, 0);
helper.TryGetStartElement(index: 0, out var element0) && element0 is 0 &&
helper.TryGetStartElement(1, out var element1) && element1 is 1 &&
helper.Last()
}
collection is { 0, 1, .. } is lowered to
@{
var helper = new ListPatternHelper(collection, 2, 0);
helper.TryGetStartElement(index: 0, out var element0) && element0 is 0 &&
helper.TryGetStartElement(1, out var element1) && element1 is 1
}
collection is { .., 3, 4 } is lowered to
@{
var helper = new ListPatternHelper(collection, 0, 2);
helper.Count() >= 2 && // `..` with 2 ending patterns
helper.GetEndElement(hatIndex: 2) is 3 && // [^2] is 3
helper.GetEndElement(1) is 4 // [^1] is 4
}
collection is { 1, 2, .., 3, 4 } is lowered to
@{
var helper = new ListPatternHelper(collection, 2, 2);
helper.TryGetStartElement(index: 0, out var element0) && element0 is 1 &&
helper.TryGetStartElement(1, out var element1) && element1 is 2 &&
helper.Count() >= 4 && // `..` with 2 starting patterns and 2 ending patterns
helper.GetEndElement(hatIndex: 2) is 3 &&
helper.GetEndElement(1) is 4
}
The same way that a Type { name: pattern } property_pattern checks that the input has the expected type and isn't null before using that as receiver for the property checks, so can we have the { ..., ... } list_pattern initialize a helper and use that as the pseudo-receiver for element accesses.
This should allow merging branches of the patterns DAG, thus avoiding creating multiple enumerators.
Note: async enumerables are out-of-scope for C# 10. (Confirmed in LDM 4/12/2021)
Note: sub-patterns are disallowed in slice-patterns on enumerables for now despite some desirable uses: e is { 1, 2, ..[var count] } (LDM 4/12/2021)
- Should we limit the list-pattern to
IEnumerabletypes? Then we could allow{ 1, 2, ..var x }(xwould be anIEnumerablewe would cook up) (answer [LDM 4/12/2021]: no, we'll disallow sub-pattern in slice pattern on enumerable for now) - Should we try and optimize list-patterns like
{ 1, _, _ }on a countable enumerable type? We could just check the first enumerated element then checkLength/Count. Can we assume thatCountagrees with enumerated count? - Should we try to cut the enumeration short for length-patterns on enumerables in some cases? (computing min/max acceptable count and checking partial count against that)
What if the enumerable type has some sort of
TryGetNonEnumeratedCountAPI? - Can we detect at runtime that the input type is sliceable, so as to avoid enumeration? .NET 6 may be adding some LINQ methods/extensions that would help.