C# List Patterns

Summary: in this tutorial, you’ll learn how to use the C# list patterns to match an array or a list with a sequence of patterns.

Introduction to the C# list patterns

C#11 introduced a new feature called list patterns. The list patterns allow you to match an array or a list with a sequence of elements.

C# provides three different ways for list pattern matching:

• Discard pattern
• Range pattern
• var pattern

Discard pattern

The discard pattern assumes that you know the length of the sequence and match one or more elements from the sequence.

For example:

var scores = new[] { 1, 2, 3, 4 , 5};
if (scores is [1, 2, 3, 4, 5])
{
    Console.WriteLine("Matched");
}Code language: C# (cs)

Output:

MatchedCode language: plaintext (plaintext)

In this example, we match the array of five integers with the same array of five integers.

To check if an array has 5 elements regardless of their values, you can use _ variable like this:

var scores = new[] { 1, 2, 3, 4 , 5};
if (scores is [_, _, _, _, _])
{
    Console.WriteLine("Matched");
}Code language: C# (cs)

Output:

MatchedCode language: plaintext (plaintext)

You can check if the sequence has five elements and start with the number 1:

var scores = new[] { 1, 2, 3, 4 , 5};
if (scores is [1, _, _, _, _])
{
    Console.WriteLine("Matched");
}Code language: C# (cs)

Output:

MatchedCode language: plaintext (plaintext)

Range pattern

If you don’t know the length of the sequence, you can use the range pattern. In the range pattern, you can use the two dots .. to specify any number of elements. Note that you can use the two dots once in the sequence.

The following example matches a sequence that starts with the number 1:

var scores = new[] { 1, 2, 3, 4, 5 };

if (scores is [1, ..])
{
    Console.WriteLine("Matched");
}Code language: C# (cs)

But the following example doesn’t match because it requires the first element in the sequence is 6:

var scores = new[] { 1, 2, 3, 4, 5 };

if (scores is [6, ..])
{
    Console.WriteLine("Matched");
}
else
{
    Console.WriteLine("Not matched");
}Code language: C# (cs)

Output:

Not matchedCode language: plaintext (plaintext)

You can combine the .. with the _ to form a discard pattern. For example:

var scores = new[] { 1, 5, 3, 4, 2 };

if (scores is [1, _, 3, ..])
{
    Console.WriteLine("Matched");
}Code language: C# (cs)

Output:

MatchedCode language: plaintext (plaintext)

In this example, we match with a sequence that starts with 1, followed by any number, and 3, and followed by zero or more numbers.

So far, you have seen constant patterns. In other words, we use the constant numbers directly in the sequence.

To make the pattern more flexible, you can use a relational pattern like this:

var scores = new[] { 1, 2 };

if (scores is [>= 1, .., <= 3])
{
    Console.WriteLine("Matched");
}Code language: C# (cs)

Output:

MatchedCode language: plaintext (plaintext)

In this example, we match the array with a sequence that:

• has the first element greater than or equal to one.
• is followed by any number of elements.
• has the final element less than or equal to three.

Var pattern

The var pattern allows you to declare a variable and assign it the value of the matched element. This variable will be available in the same scope where it was declared.

For example:

var scores = new[] { 1, 2, 3, 4, 5 };

if (scores is [var first, var second, ..])
{
    Console.WriteLine($"{first}, {second}");
}Code language: C# (cs)

In this example, we use the var keyword to declare two variables first and second. It assigns the first and second element of the array to these variables respectively.

Summary

• Use the list pattern to match an array or a list with a sequence of elements.
• Use the discard pattern when you know the length of the sequence.
• Use the range pattern with two dots .. to indicate any number of elements.
• Use the var pattern to assign matched elements to variables.