Wolfram: Pattern Syntax

By Xah Lee. Date: 2022-06-30. Last updated: 2025-01-11.

Here's a list of all pattern syntax. 〔see Pattern Matching〕

Literal Expression

Literal expression matches itself. In other words, any expression without a pattern in it, match itself.

examples:

symbol a match itself.
number 3 match itself.
string "abc" match itself.
f[a,{3,4},c] match itself.

Cases[ {3, 4, {5, 4}}, 4]
(* {4} *)

Cases[ {a, f[3], f[9]}, f[9]]
(* {f[9]} *)

Cases[ {2/3, {4, 8}, {c}}, 2/3]
(* {2/3} *)

Any Expression

Blank[]

🔸 SHORT SYNTAX: _

match any Expression

Blank

Cases[ {3,4}, _]
(* {3, 4} *)

Cases[ {a, f[3], f[9]}, f[_] ]
(* {f[3], f[9]} *)

Cases[ {a, f[3], g[4], f[5]}, _[_]]
(* {f[3], g[4], f[5]} *)

Cases[ {{2}, {4, 8}, {c}}, {_ , 8}]
(* {{4, 8}} *)

ReplaceAll[ {3,4}, _ -> x]
(* x *)

ReplaceAll[ {a, f[3], f[9]}, f[_] -> x ]
(* {a, x, x} *)

ReplaceAll[ {a, f[3], g[4], f[5]}, _[_] -> x]
(* {a, x, x, x} *)

ReplaceAll[ {{2}, {4, 8}, {c}}, {_ , 8} -> x]
(* {{2}, x, {c}} *)

Blank[h]

🔸 SHORT SYNTAX: _h

any Expression with Head h

💡 TIP: _h is often used in the form x_h, which means the matched pattern is given a name x

Blank

(* common example of using blank pattern with head. *)

ReplaceAll[ {3, 4.5, 5/6, {7, y}}, x_Integer -> g[x] ]
(* {g[3], 4.5, 5/6, {g[7], y}} *)

ReplaceAll[ {3, 4.5, 5/6, {7, y}}, x_Rational -> g[x] ]
(* {3, 4.5, g[5/6], {7, y}} *)

ReplaceAll[ {3, 4.5, 5/6, {7, y}}, x_Real -> g[x] ]
(* {3, g[4.5], 5/6, {7, y}} *)

(* generic example of using blank pattern with head. *)

ReplaceAll[ {3, 4.5, 5/6, {7, y}}, x_List -> g[x]]
(* g[{3, 4.5, 5/6, {7, y}}] *)

ReplaceAll[ {h[3], f[a], f[b]} , x_f -> g[x] ]
(* {h[3], g[f[a]], g[f[b]]} *)

(* empty args also match *)

ReplaceAll[ m[{}, {7, y}], x_List -> g[x]]
(* m[g[{}], g[{7, y}]] *)

ReplaceAll[ {f[], f[b]} , x_f -> g[x] ]
(* {g[f[]], g[f[b]]} *)

Name a Pattern

Naming a pattern is important because you can refer to the matched expression in replacement.

Pattern[name, p]

🔸 SHORT SYNTAX: name:p
🔸 SHORT SYNTAX: name_ for name:_
🔸 SHORT SYNTAX: name__ for name:__
🔸 SHORT SYNTAX: name___ for name:___
🔸 SHORT SYNTAX: name_h for name:_h
🔸 SHORT SYNTAX: name__h for name:__h
🔸 SHORT SYNTAX: name___h for name:___h

Name a pattern p by name so it can be referenced for the matched expression.

Pattern

ReplaceAll[ {3,4}, Pattern[ x, Blank[] ] -> g[x] ]
(* g[{3, 4}] *)

(* can be written as *)
ReplaceAll[ {3,4}, Pattern[ x, _ ] -> g[x] ]
(* g[{3, 4}] *)

(* can be written as *)
ReplaceAll[ {3,4}, x:_ -> g[x] ]
(* g[{3, 4}] *)

(* can be written as *)
ReplaceAll[ {3,4}, x_ -> g[x] ]
(* g[{3, 4}] *)

(* swap list of pairs, pass it to g[] *)
ReplaceAll[ {3, {3}, {3, 4}, {3, 4, 5}, {a, 3}}, {x_, y_} -> g[y, x] ]
(* {3, {3}, g[4, 3], {3, 4, 5}, g[3, a]} *)

Sequence of One or More Expression

BlankSequence[]

🔸 SHORT SYNTAX: __

sequence of one or more Expression.

BlankSequence

ReplaceAll[ m[3, {}, {5, 6}, {7, f, 9}], {x__} -> g[x] ]

(* m[3, {}, g[5, 6], g[7, f, 9]] *)

BlankSequence[h]

🔸 SHORT SYNTAX: __h

sequence of one or more Expression, but all have Head h

ReplaceAll[ m[3, {}, {5, 6}, {7, f, 9}], {x__Integer} -> g[x] ]
(* m[3, {}, g[5, 6], {7, f, 9}] *)

Sequence of Zero or More Expression

BlankNullSequence[]

🔸 SHORT SYNTAX: ___

sequence of zero or more Expression.

BlankNullSequence

ReplaceAll[ m[3, {}, {5, 6}], {x___} -> g[x] ]

(* m[3, g[], g[5, 6]] *)

(* replace lists that start with 3 *)
ReplaceAll[ m[3, {}, {3, 6}, {3}, {7, f, 9}], x:{3,___} -> g[x] ]
(* m[3, {}, g[{3, 6}], g[{3}], {7, f, 9}] *)

BlankNullSequence[h]

🔸 SHORT SYNTAX: ___h

sequence of zero or more Expression, but all have Head h

ReplaceAll[ {3, {}, {5, 6}, {7, f, 9}}, {x___Integer} -> g[x] ]
(* {3, g[], g[5, 6], {7, f, 9}} *)

Repeat a Pattern, One or More Times

Repeated[p]

🔸 SHORT SYNTAX: p..

a pattern repeated one or more times

Repeated

ReplaceAll[ {2,{3},{3,6},{3,3},{f,f},{3,3,3}}, x:{Repeated[3]} -> g[x] ]

{2, g[{3}], {3, 6}, g[{3, 3}], {f, f}, g[{3, 3, 3}]}

ReplaceAll[ {2,{3},{3,6},{3,3},{f,f},{3,3,3}}, x:{Repeated[3|f]} -> g[x] ]

{2, g[{3}], {3, 6}, g[{3, 3}], g[{f, f}], g[{3, 3, 3}]}

ReplaceAll[ {{3},{5,5},{3,3},{4,4},{3,3,3}}, x:{Repeated[ PatternTest[ _, OddQ ] ]} -> g[x] ]

{g[{3}], g[{5, 5}], g[{3, 3}], {4, 4}, g[{3, 3, 3}]}

Repeated[p, max]

a pattern repeated one to max times

ReplaceAll[ {{3}, {5, 6}, {f, f}, {g, g}, {4,4,4}}, x:{Repeated[_, 2]} -> g[x] ]

{g[{3}], g[{5, 6}], g[{f, f}], g[{g, g}], {4, 4, 4}}

Repeated[p, {min, max}]

a pattern repeated min to max times

ReplaceAll[ {{3}, {5, 6}, {f, f}, {g, g}, {4,4,4}}, x:{Repeated[_, {2,3}]} -> g[x] ]

{{3}, g[{5, 6}], g[{f, f}], g[{g, g}], g[{4, 4, 4}]}

Repeated[p, {n}]

a pattern repeated n times

ReplaceAll[ {{3}, {5, 6}, {f, f}, {g, g}, {4,4,4}}, x:{Repeated[_, {2}]} -> g[x] ]

{{3}, g[{5, 6}], g[{f, f}], g[{g, g}], {4, 4, 4}}

Repeat a Pattern Zero or More Times

RepeatedNull[p]

🔸 SHORT SYNTAX: p...

pattern p repeated zero or more times

RepeatedNull

RepeatedNull[p, max]

pattern p repeated zero to max times

RepeatedNull[p, {min, max}]

pattern p repeated min to max times

RepeatedNull[p, n]

pattern p repeated n times

Pattern with Conditional Test

PatternTest[p, f]

🔸 SHORT SYNTAX: p?f

a pattern that would match if pattern p match and f[p] is true.

PatternTest

Cases[ {9, -3, 0, 4.5, 5/6, x, f[3]}, PatternTest[_, NumberQ]  ]

(* {9, -3, 0, 4.5, 5/6} *)

ReplaceAll[ {9, -3, 0, 4.5, 5/6}, x:PatternTest[_Integer, Positive] -> g[x] ]

{g[9], -3, 0, 4.5, 5/6}

ReplaceAll[ {9, 13, 4.5, 5/6}, x:PatternTest[_Integer, PrimeQ] -> g[x] ]

{9, g[13], 4.5, 5/6}

ReplaceAll[ {9, 13, 4.5, 6/5, 7/6}, x:PatternTest[_Rational, Function[{x}, PrimeQ @ Numerator @ x ]] -> g[x] ]

{9, 13, 4.5, 6/5, g[7/6]}

ReplaceAll[ {9, 13, 4.5, 5/6}, x:_Integer?PrimeQ -> g[x] ]

{9, g[13], 4.5, 5/6}

ReplaceAll[ {9, 13, 4.5, 6/5, 7/6}, x:_Rational?(Function[{x}, PrimeQ @ Numerator @ x ]) -> g[x] ]

{9, 13, 4.5, 6/5, g[7/6]}

Condition[ p, testExpr]

🔸 SHORT SYNTAX: p/;testExpr

match if pattern p match and testExpr evaluates to True.

the p should be named pattern, whole or partial, and testExpr tests those variables.

Condition

ReplaceAll[ {9, 13, 4.5, 5/6}, x:Condition[ y_Integer, y > 10] -> g[x] ]

{9, g[13], 4.5, 5/6}

ReplaceAll[ {9, 13, 4.5, 6/5, 7/6}, x:Condition[ y_Rational, PrimeQ @ Numerator @ y ] -> g[x] ]

{9, 13, 4.5, 6/5, g[7/6]}

Alternatives

Alternatives[p1, p2, etc]

🔸 SHORT SYNTAX: p1|p2|etc

a pattern that matches at least one of the pattern.

Alternatives

ReplaceAll[ {9, 13, 4.5, 5/6, {a,b}}, x:Alternatives[ _Integer, {_,_} ] -> g[x] ]

{g[9], g[13], 4.5, 5/6, g[{a, b}]}

Pattern Negation

Except[c]

any Expression except those matching c

Except

Cases[ {3, 4.5, 5/6, {3, b}}, x:Except[ _Integer ] -> g[x] ]

{g[4.5], g[5/6], g[{3, b}]}

Except[c, p]

any Expression matching p, except those matching c

ReplaceAll[ {0, 1, 3, 4.5, {x}, 0}, x:Except[ 3, _Integer ] -> g[x] ]

{g[0], g[1], 3, 4.5, {x}, g[0]}

(* any pair, except {0,0} *)
ReplaceAll[ {{x, y}, {0, 1}, {0, 0}, 3}, x:Except[ {0, 0}, {_,_} ] -> g[x] ]

{g[{x, y}], g[{0, 1}], {0, 0}, 3}

Advanced Patterns

PatternSequence[p1, p2, etc]

Sequence of patterns, or empty sequence.

PatternSequence must appear in a expression, not by itself as a pattern.

💡 TIP: this is useful when you want to match a sublist, if it exists.

PatternSequence

ReplaceAll[
{1, 2, 3, 8, 9, 2} ,
{x__, s:PatternSequence[ 3,8,9 ], y__} -> {x, y, g[s]}
]

(* {1, 2, 2, g[3, 8, 9]} *)

OrderlessPatternSequence[p1, p2, etc]

an orderless sequence of patterns

OrderlessPatternSequence

ReplaceAll[
{1, 2, 3, 8, 9, 2},
{x__, s:OrderlessPatternSequence[ 8,3,9 ], y__} -> {x, y, g[s]}
]
(* {1, 2, 2, g[3, 8, 9]} *)

KeyValuePattern[{p1, p2, etc}]

An orderless sequence of patterns.
This is designed to match Association (Key Value List).
Each of the p1 usually has the form keyPattern -> valuePattern, but not required.

KeyValuePattern

Patterns Related to Function Optional Arguments

Optional[p, def]

🔸 SHORT SYNTAX: p:def

an expression with default value v

Optional

typical usage:

x_h:v → an expression with Head h and default value v
x_. → an expression with a globally defined default value
Optional[x_h] → an expression that must have Head h, and has a globally defined default value

OptionsPattern[]

a sequence of options

〔see Wolfram: Define Function with Optional Parameters〕

Longest and Shortest

Longest[p]

the longest sequence consistent with pattern

Longest

(* move all 0 to the left of 1 *)
ReplaceAll[
{3, 1, 1, 0, 0, 3, 1, 1, 0, 0} ,
{head___,
Pattern[dots, Longest[ 1.. ] ],
Pattern[balls, Longest[ 0.. ] ],
tail___} -> {head , balls , dots , tail}
]

(* {3, 0, 0, 1, 1, 3, 1, 1, 0, 0} *)

(* HHHH------------------------------ *)

(* without using Longest. by default it's shortest *)
ReplaceAll[
{3, 1, 1, 0, 0, 3, 1, 1, 0, 0} ,
{head___,
Pattern[dots, 1.. ],
Pattern[balls, 0.. ],
tail___} -> {head , balls , dots , tail}
]

(* {3, 0, 1, 1, 0, 3, 1, 1, 0, 0} *)

Shortest[p]

the shortest sequence consistent with pattern

Shortest

Literal Pattern

These are when you want to match a expression that is itself a pattern.

HoldPattern[pattern]

a pattern not evaluated

HoldPattern

Verbatim[expr]

an expression to be matched verbatim

Verbatim

Which Function is Best for Learning Patterns

MatchQ → is the most simple for testing patterns. But tedious if you want to try different expressions, because you need to call for each.
Cases → can be used for testing against several expressions in one shot. But if you want to test patterns that can match nested expression, you need to specify a Level Spec.
ReplaceAll → is the most commonly used in real-world. It can demonstrate pattern replacement, and also for matching nested expressions. But it's less obvious which part of expression matched.

One thing important when learning pattern matching is the level spec. 〔see Wolfram: Pattern Matching and Level Spec〕

Reference

PatternsAndTransformationRules