Wolfram: Pattern Syntax

By Xah Lee. Date: . Last updated: .

Here's a list of all pattern syntax. [see Pattern Matching]

Literal Expression

Literal expression matches itself.

example:

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

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

(* 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.

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.

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.

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

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[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.

🟢 TIP: if f is not just a function name, you should wrap paren around it, e.g. (f)

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.

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.

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

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.

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

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.

Patterns Related to Function Optional Arguments

Optional[p, defaultVal]

🔸 SHORT SYNTAX: p:defaultVal

an expression with default value v

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

(* 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} *)

(* s------------------------------ *)

(* 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

Literal Pattern

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

HoldPattern[pattern]

a pattern not evaluated

Verbatim[expr]

an expression to be matched verbatim

Which Function is Best for Learning Patterns

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

Reference

PatternsAndTransformationRules

Wolfram. Pattern Matching