Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Classes and Object-Oriented Concepts

Pattern matching

Reference for C# pattern matching: type, constant, relational, logical, property, positional, var, discard and list patterns with is, switch and when.

A pattern tests a value against a shape and, if it matches, can also extract parts of it into new variables. You use patterns with the is operator, in switch statements, and in switch expressions. Pattern matching grew over many versions, and today it replaces most chains of if + cast + comparison.

This page is a map of every pattern kind. The detailed pages cover property and positional patterns and list patterns.

C#
if (shape is Circle { Radius: > 0 } c)
{
    Console.WriteLine(c.Radius);
}

Try it

C# The pattern kinds, one by one

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# is expressions: not, or, and parentheses

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

Pattern Example Matches
Constant 0, "x", null, Color.Red A value equal to the constant.
Type / declaration int, string s, Circle c A value of that type; optionally binds a variable.
Discard _ Anything (in a switch, the default branch).
var var x Anything, including null; just names the value.
Relational < 0, >= 18, <= 'z' Numbers, chars, enums compared to a constant.
Logical p1 and p2, p1 or p2, not p Combinations of other patterns.
Parenthesized (p) Groups for precedence. not binds tighter than and, then or.
Property { Age: > 18 } An object whose members match nested patterns.
Positional (0, var y) A tuple or a type with a Deconstruct method.
List [1, .., 9] An array or a countable, indexable type.
Slice .., .. var rest Zero or more elements inside a list pattern.

Where patterns are allowed: expr is pattern, case pattern [when condition]:, pattern => result in a switch expression, and expr is not pattern.

Usage notes

  • is null / is not null is the idiomatic null check. It ignores overloaded == operators, which is why it is also safer.
  • Declared variables have limited scope. A variable from if (x is T t) is definitely assigned only where the match succeeded. With is not T t followed by a return, it is assigned after the if.
  • Type patterns do not match null. null is string and null is string s are both false; only null, var and _ accept null.
  • Order matters in switches. The compiler reports an error if an earlier pattern already covers a later one (the later one is "subsumed"), so put specific patterns first.
  • Relational patterns need constants on the right. Use when for anything computed: case int n when n > limit:.
  • and / or are pattern combinators, not && / ||. They combine patterns on one value; when takes a boolean expression.
  • Positional patterns work on tuples and records. Any type with a Deconstruct method qualifies; see Deconstruct methods.
  • Switch expressions report an unmatched input at run time with SwitchExpressionException and warn at compile time if not exhaustive.
  • Version history: type and constant patterns C# 7, property patterns C# 8, relational and logical patterns C# 9, extended property patterns C# 10, list patterns C# 11.