Pattern Matching in C#
![Pattern Matching in C#](https://res.cloudinary.com/endjin/image/upload/f_auto/q_80/assets/images/blog/2022/02/pattern-matching-in-c-sharp.png)
Pattern matching is a relatively new feature in C#. It was first introduced to the C# language in C# 7.0 and has since seen additional improvements in each succeeding version of C#. This blog post will explore the various use cases for pattern matching as well as how pattern matching has evolved over each version of C#.
What is pattern matching?
So what is pattern matching? Pattern matching is the process of taking an expression and testing whether it matches certain criteria, such as ‘being a specified type’ or ‘matching a specified constant value’. C# supports various different patterns which will be explored within this blog post.
Common to all patterns is the Boolean match/no-match characteristic, so, the specified expression either matches the pattern or it does not. Pattern matching is a check and so can be used when branching code. The is
expression, switch
statement and the switch
expression (introduced in C# 8.0) all support pattern matching.
Why is pattern matching useful?
Pattern matching provides a more concise way of testing expressions. The different operations pattern matching allows can be done using traditional approaches. However, pattern matching can simplify these operations from lengthy if-else
statements into a more compact and readable block of code.
What are the different patterns?
There are a number of different ways to define a pattern which reflect the various operations pattern matching supports.
These are the classes which we will be using in the examples in this blog post:
public class Rectangle
{
public double Length { get; init; }
public double Height {get; init; }
}
public class Triangle
{
public double Base { get; init; }
public double Height { get; init; }
}
public class Circle
{
public double Radius { get; init; }
}
public class Square
{
public double Length { get; init; }
}
Patterns introduced in C# 7.0
Constant pattern
The constant pattern can be used to test whether an expression is equal to a specified constant. A popular use-case for the constant pattern is null checking. This checks whether an object is null
. The method in the following example uses the constant pattern to determine whether a Rectangle
object is null
.
Rectangle rectangle = new Rectangle { Height = 7, Length = 3 };
public void IsShapeNull(Rectangle rectangle)
{
if (rectangle is null)
{
throw new ArgumentNullException(nameof(rectangle));
}
}
Declaration pattern
The declaration pattern can be used to determine at run-time whether an expression is of a certain type. A variable declaration can optionally be included in the declaration pattern. If the test expression matches the specified type, then the expression will be cast to this type and then assigned to the variable.
The method in the following example tests whether shape
is of type Square
. If shape
is a Square
it will be downcast from object
to Square
and then will be assigned to a variable named square
. One expression contains the combination of both type checking and the cast. The else
block of the if-else
statement will be executed if shape
is not of type Square
. If there is not a type match, the square
variable is not created.
object shape = new Square { Length = 5 };
public void IsShapeSquare(object shape)
{
if (shape is Square square)
{
Console.WriteLine($"Shape is a square with a side of length {square.Length}");
}
else
{
Console.WriteLine($"{shape} is not a square");
}
}
Patterns introduced in C# 8.0
Property pattern
Pattern matching was further improved in C# 8.0 and one new addition was the property pattern. The property pattern can be used for checking and comparing values of properties. The property pattern tests whether an expression’s properties/fields match the values of specified properties/fields. Each corresponding property or field must match and the expression must not be null.
The example below shows a property pattern that inspects the Base
and Height
properties of a Triangle
object. The property pattern begins with checking whether the input is a specified type. Here, the property pattern adopts the same behaviour as the type pattern. Once the property pattern asserts the input is a Triangle
it will inspect the Base
property and the Height
property of the input. The pattern will match the expression if the input is a Triangle
with a Base
of 4 and a Height
of 6.
Triangle triangle = new Triangle { Base = 4, Height = 6 };
public void IsSpecificTriangle(Triangle triangle)
{
if (triangle is Triangle { Base: 4, Height: 6 } specificTriangle)
{
Console.WriteLine($"Shape is a triangle wih a base of {specificTriangle.Base} and a height of {specificTriangle.Height}");
}
}
var pattern
The var pattern can be used to match any expression and then assign it to a new declared variable. It is different to other patterns in that it always matches. So the purpose of a var pattern is to assign an expression to a variable, rather than testing an expression for a pattern. The var pattern is useful if you want to store property values in a variable if other patterns are matching, or if you want to store intermediate values in a temporary variable during calculations.
The method in the example below tests whether the input shape
is a Rectangle
and its Length
property is a multiple of 3. Here, we assign the value of the Length
property to a length
variable, then we test this variable in a Boolean expression.
object shape = new Rectangle { Length = 9, Height = 4};
public void IsLengthMultipleOfThree(object shape)
{
if (shape is Rectangle { Length: var length } rect && length % 3 == 0)
{
Console.WriteLine("This shape is a rectangle with a length which is a multiple of 3");
}
}
Positional pattern
The positional pattern is useful when testing a type that can be deconstructed. Deconstruction is a process of unpacking types into parts and storing them into new variables (object deconstruction). For example, a class can be split into its properties or a tuple can be split into its individual items.
The positional pattern can deconstruct an input expression and then test if the resulting variables match against a pattern specified in parentheses. C# offers built in support for deconstructing the record
and tuple
types. However, for other types, the compiler requires a Deconstruct
method to be implemented. For example, we can change the Rectangle
type to include a custom Deconstruct
method. Each value to be deconstructed is referred to by an out
parameter. The Deconstruct
method splits the Rectangle
type and returns a length
variable and a height
variable.
public struct Rectangle
{
public double Length { get; init; }
public double Height {get; init; }
public void Deconstruct(out double length, out double height)
{
length = Length;
height = Height;
}
}
Then, you can deconstruct an instance of the Rectangle
class named rectangle
with an assignment, such as follows:
Rectangle rectangle = new Rectangle { Length = 20, Height = 40 };
var (l, h) = rectangle;
In the example below, the rectangle
is deconstructed and length
is tested against the 20
pattern (a constant pattern) and height
is tested against _
(the discard pattern). The pattern reflects the position each variable has within the Deconstruct
method. So the first value coming out of the Deconstruct
method, is the first value we are going to match on and so forth. Discards (_
) can be used where any value is accepted at that position. So, the pattern will match if rectangle
has a length
of 20 and a height
of any value.
if (rectangle is (20, _) rect)
{
Console.WriteLine("The rectangle has a length of 20");
}
Tuple pattern
The tuple pattern can be used to pattern match multiple input values. The tuple pattern is a particular way of using the positional pattern, but the object we match on is not deconstructed as it is already a tuple.
The switch
expression (covered later in this blog post) in the example below uses the tuple pattern to select a shape description based on the values of the input tuple.
public string ReturnDescriptionOfShape(string shape, int length, int height)
{
return (shape, length, height) switch
{
("Rectangle", 2, 1) => "This is a small rectangle",
("Circle", 4, 2) => "This is a medium circle",
("Square", 8, 4) => "This is a large square",
(_,_,_) => "This not a valid input"
};
}
Patterns introduced in C# 9.0
Relational pattern
The relational pattern can be used for comparisons by testing how a value compares to a constant using comparison operators (>, <, >=, <=). The example below shows a relational pattern that inspects the Radius
property of a Circle
object. The pattern will match the expression if the input is a Circle
with a Radius
greater than or equal to 100.
object shape = new Circle {Radius = 110};
public void IsBigCircle(object shape)
{
if (shape is Circle { Radius: >= 100 })
{
Console.WriteLine($"This is a big circle");
}
}
Type pattern
Like the declaration pattern, you can use a type pattern to determine at run-time whether an expression is of a certain type. With the type pattern, a variable is not specified. The method in the following example tests whether shape
is of type Square
.
object shape = new Square { Length = 5 };
public void IsShapeSquare(object shape)
{
if (shape is Square)
{
Console.WriteLine($"{shape} is a square");
}
else
{
Console.WriteLine($"{shape} is not a square");
}
}
Logical patterns
C# 9.0 also introduced logical patterns, which is the ability to use and
, or
and not
pattern combinators to create the following logical patterns:
Negation or the not
pattern can be used for null checks. Before C# 9.0, the following code would be used to check if an object is not null
:
if (shape != null)
Checking if an object is not null
using the not
logical pattern in C# 9.0 can be done as follows:
if (shape is not null)
The syntax in the above example allows our code to express intent more clearly.
Conjuctive or the and
pattern can be used to check if the input expression matches more than one pattern. The method in the example below shows how you can combine two relational patterns to check that the Radius
property of a Circle
object is within a certain range. The pattern will match the expression if the input is a Circle
with a Radius
greater than or equal to 100 and less than or equal to 200. The expression must match both patterns for there to be a match.
object shape = new Circle {Radius = 110};
public void IsBigCircleRange(object shape)
{
if (shape is Circle { Radius: >= 100 and <= 200 })
{
Console.WriteLine($"This is a big circle");
}
}
Disjunctive or the or
pattern can be used to check if the input expression matches either one of the patterns specified. In the following example, the pattern will match the expression if the input is a Circle
with a Radius
that is equal to 100 or 200. Only one of these patterns needs to match the expression for there to be a match.
object shape = new Circle {Radius = 100};
public void IsBigCircleValue(object shape)
{
if (shape is Circle { Radius: 100 or 200 })
{
Console.WriteLine($"This is a big circle");
}
}
What are the different ways to do pattern matching?
The is
expression, switch
statement and the switch
expression (introduced in C# 8.0) all support pattern matching. The previous examples focused on how to pattern match with the is
expression, with the switch
expression being touched upon in the tuple pattern matching example. We will explore how the switch
statement and switch
expression can be used with the various different patterns in the next part of this blog post.
switch statement
The switch
statement has been empowered to support pattern matching. The switch
statement can be used when branching code by testing an expression against a set of patterns. As of C# 7.0, the switch
statement was improved to facilitate pattern matching. The switch
statement can now support any type, whereas only integral types and string constants were supported previously. Each case
is now an pattern and not a constant value. Finally, support of the when
keyword was included to further express and specify the condition for pattern matching.
The method in the example below calculates the area of a shape using the switch
statement to pattern match in order to select the correct formula for this calculation.
public double CalculateAreaSwitchStatement(T shape)
{
switch (shape)
{
case null:
throw new ArgumentNullException(nameof(shape));
case Square { Length: var l }:
return l * l;
case Circle { Radius: var r }:
return r * r * Math.PI;
case Rectangle { Length: var l, Height: var h }:
return l * h;
case Triangle { Base: var b, Height: var h}:
return b * h / 2;
default:
throw new NotSupportedException();
}
}
switch expression
C# 8.0 introduced the switch
expression to evaluate an expression against a set of patterns. The switch
expression provides a more concise syntax for pattern matching. There are several syntax improvements to the switch
expression as compared to the switch
statement. Firstly, the input variable is before the switch
keyword. The case
keyword and the colon (:) are replaced with arrows (=>) making the code more readable and concise. The default
case is now replaced with a discard (_
). Finally, the body is an expression, not a series of statements.
One of the big practical differences between a switch
expression and a switch
statement is that a switch
expression will tell you if you have not covered all possibilites. With a switch
statement, behaviour is specified for only some of the cases, with the default being to 'do nothing'. However, a switch
expression has to produce some sort of result when evaluated. This is useful as the compiler will tell you if you have forgotten something. For example, if you code a switch
for an enum
, and later a new value is added to the enum
, it is useful to be told when a switch
expression based on that enum is no longer complete as a result.
The method in the example below is the same as the previous example but using the switch
expression with the improvements described above. In this example, the discard pattern (_
) is used to match any expression, including null
. The discard pattern guarantees that the switch expression handles all possible input values. If the discard pattern is not used, and the input value does not match any of the patterns in the expression, then the runtime will throw an exception.
public double CalculateAreaSwitchExpression(T shape)
{
return shape switch
{
null => throw new ArgumentNullException(nameof(shape)),
Square { Length: var l } => l * l,
Circle { Radius: var r } => r * r * Math.PI,
Rectangle { Height: var h, Length: var l } => h * l,
Triangle { Base: var b, Height: var h } => b * h / 2,
_ => throw new NotSupportedException()
};
}
Conclusion
In this blog post we seen how pattern matching has evolved over each version of the C# language. We have explored the various different patterns that C# supports. We have also seen how the is
expression, switch
statement and the switch
expression all support pattern matching. Overall, pattern matching is a very powerful new feature in C# which can be utilised to make your code more concise and readable.