C# Pattern Matching in Depth: List, Slice and Positional

You've matched types, properties, and ranges. Now match the shape of a whole list, tear a record apart positionally, and understand why the compiler doesn't just run your patterns top to bottom.

You already know is Circle { Radius: > 10 } and the and/or/not combinators from Foundations. Those cover "what type is this, and what do its properties look like." But a lot of real data doesn't live in named properties — it lives in sequences. Given int[] scores, how do you express "the first score is 100, and I want everything after it" without slicing and indexing by hand? And given a record Point(int X, int Y), is there a way to match and destructure it in a single expression, without naming X and Y as property patterns at all?

There's also a question worth answering properly now that you've seen a few dozen switch expressions: does a switch with ten pattern arms really check each one sequentially, like an if/else chain in disguise? The honest answer is "usually not," and understanding why matters for writing pattern-based code you trust at scale.

In this lesson: list patterns, positional patterns via Deconstruct, nested/recursive property patterns, richer combinator usage, and a clear, correct picture of how the compiler actually executes a pattern-matching switch.

What Is It?

Three Pattern Kinds This Lesson Adds

The Technical Definition

A list pattern (C# 11) matches a value implementing an indexer and a countable Length/Count (arrays, List<T>, and similar) against a sequence shape, optionally using a slice pattern (..) to match a variable-length gap. A positional pattern matches a value against a parenthesized list of sub-patterns by calling the value's Deconstruct method (or, for a tuple, its built-in deconstruction) and matching each sub-pattern against the corresponding output. These compose with everything from the previous pattern-matching lesson — type patterns, property patterns, relational patterns, and and/or/not — inside is expressions and switch.

Why Does It Exist?

The Problem

Before list patterns, expressing "this array starts with a specific value and has at least one more element" meant manual length checks and indexing — easy to get off-by-one wrong, and it obscures the actual rule being expressed:

bool StartsWithZeroAndHasMore(int[] scores) =>
    scores.Length >= 2 && scores[0] == 0;

And before positional patterns, matching a record's data meant repeating property names even when the record's whole reason for existing is that its shape (its constructor parameter order) already tells you what each value means:

// Verbose — repeats property names that the record's shape already implies
if (point is Point { X: 0, Y: 0 }) { /* origin */ }

The Solution

bool StartsWithZeroAndHasMore(int[] scores) => scores is [0, ..];

if (point is (0, 0)) { /* origin — positional, matches via Deconstruct */ }

Both read as a direct description of the shape being tested, exactly the same win the previous lesson's patterns already gave you for types and properties — now extended to sequences and to a record's positional shape.

Big Picture

How It Works

int[] scores = [95, 88, 72, 100];

if (scores is [var first, .. var rest])
{
    // first == 95, rest == [88, 72, 100] (a new array)
}

if (scores is [_, _, _, 100]) { /* exactly 4 elements, ending in 100 */ }

public record Point(int X, int Y);

Point p = new(3, 0);

if (p is (var x, 0)) { /* Y is exactly 0; x captures X */ }
if (p is (0, 0))     { /* the origin, tested positionally */ }

public record Address(string Country);
public record Customer(string Name, Address Address);
public record Order(Customer Customer, decimal Total);

bool isBigUsOrder = order is
{
    Total: > 1000,
    Customer.Address.Country: "US"   // reaches THREE levels deep in one pattern
};

bool matches = order is
    { Customer.Address.Country: "US" or "CA", Total: > 0 and <= 5000 }
    and not { Status: "Cancelled" };

Simple Example

string Describe(int[] numbers) => numbers switch
{
    []                    => "empty",
    [var only]            => $"single value: {only}",
    [var first, var second] => $"pair: {first}, {second}",
    [var first, .., var last] => $"starts with {first}, ends with {last}",
};

Describe([]);          // "empty"
Describe([7]);         // "single value: 7"
Describe([1, 2]);      // "pair: 1, 2"
Describe([1, 2, 3, 4]);// "starts with 1, ends with 4"

Code → Meaning → Result: Each arm describes a distinct shape of the array — empty, one element, exactly two, or "at least two, and I only care about the ends" — and the compiler picks the first arm whose shape actually matches. No manual length checks or indexing anywhere in this code.

Real-World Example

A simple command-line-argument router is a natural fit: the "shape" of the arguments genuinely determines what the command means.

string RunCommand(string[] args) => args switch
{
    ["deploy", var environment]              => $"Deploying to {environment}",
    ["deploy", var environment, "--force"]   => $"Force-deploying to {environment}",
    ["rollback", .. var targets] when targets.Length > 0
                                              => $"Rolling back: {string.Join(", ", targets)}",
    ["help"] or []                           => "Usage: deploy <env> | rollback <targets...>",
    _                                         => "Unknown command",
};

RunCommand(["deploy", "staging"]);              // "Deploying to staging"
RunCommand(["deploy", "prod", "--force"]);      // "Force-deploying to prod"
RunCommand(["rollback", "v1.2", "v1.3"]);       // "Rolling back: v1.2, v1.3"
RunCommand([]);                                 // "Usage: ..."

And a domain example tying positional patterns back to records — routing a shipping decision by an order's shape:

public record ShippingRequest(string Destination, double WeightKg, bool IsPriority);

decimal Cost(ShippingRequest r) => r switch
{
    (_, _, IsPriority: true)                    => 40m,
    ("Domestic", <= 5, _)                        => 5m,
    ("Domestic", _, _)                            => 12m,
    ("International", > 20, _)                   => 75m,
    ("International", _, _)                       => 35m,
    _                                              => 15m,
};

Mixing a positional pattern with a named property (IsPriority: true) in the same pattern is entirely legal — positional and property patterns compose freely on the same value.

Analogy

Under the Hood

Common Confusion

1. A slice pattern (..) captures an independent array, not a "view" into the original

[var first, .. var rest] allocates a genuinely new array containing the remaining elements (for an array input) — it's not a lightweight window over the same memory. For very large sequences matched frequently, that's a real allocation to be aware of, not a free slice.

2. Positional patterns need a Deconstruct — they don't work on arbitrary types

obj is (var a, var b) only compiles if obj's type has a matching two-output Deconstruct method (or is a tuple). It's not a generic "grab the first two things" syntax — it's tied directly to deconstruction, the same mechanism var (x, y) = point; already uses.

3. "The compiler reorders my arms for efficiency" doesn't mean "arm order is irrelevant"

The compiler is free to change the internal execution strategy (which tests it runs, and in what order, under the hood) as long as the observable result — which arm wins for a given input — matches what sequential evaluation would produce. It will never silently pick a later arm over an earlier one that also matches. Order still fully controls correctness when arms overlap; it just doesn't dictate the literal mechanics of how each arm gets checked.

Common Mistakes

Mistake 1 — Using two .. in one list pattern

//  compile error — a list pattern allows at most ONE slice (..)
if (scores is [.., var middle, ..]) { }

A slice pattern can appear at most once per list pattern — it's meant to soak up "everything else in the middle," and two of them would be ambiguous about where each slice's boundary is.

Mistake 2 — Forgetting that [] only matches exactly zero elements

Expecting [] to be a catch-all "anything" pattern. It specifically means "a sequence with zero elements" — the opposite of a wildcard.

Use _ for "match anything, don't care what," and reserve [] specifically for the empty-sequence case, as shown in the Simple Example above.

Mistake 3 — Assuming positional and property patterns are mutually exclusive

Believing you have to choose one style per match. As shown in the shipping example, r is (_, _, IsPriority: true) freely mixes positional matching with a named property pattern in the same expression — use whichever reads more clearly for each piece of the match.

When Should I Use It?

• Use list patterns when a sequence's shape (length, specific ends) is genuinely the thing you're testing — command parsing, validating a fixed-format array, recognizing edge/base cases (empty, single element) in recursive algorithms.
• Use positional patterns for records and tuples where the position already carries clear meaning — coordinates, RGB triples, small DTOs — especially inside a switch where several shapes are being routed at once.
• Use nested property patterns instead of a chain of ?. checks whenever you're testing a value several levels down a null-safe object graph.
• Don't reach for list patterns on large, frequently-matched sequences without being aware of the slice-allocation cost mentioned above — plain indexing may be more appropriate in a genuine hot path.

Mental Model

Key Takeaway

Check Your Understanding

You've seen list patterns, positional patterns, nested property patterns, and how the compiler actually executes a pattern switch. Let's check your understanding.

You can now express shape-based checks over sequences and records directly, and you understand what the compiler is really doing with a pattern-matching switch under the hood.