On this page:
match
8.1 Additional Matching Forms
match*
match-lambda
match-lambda*
match-let
match-let*
match-letrec
match-define
exn: misc: match?
8.2 Extending match
define-match-expander
match-equality-test
8.3 Library Extensions
struct*

8 Pattern Matching

+Pattern Matching in Guide: Racket introduces pattern matching.

The match form and related forms support general pattern matching on Racket values. See also Regular Expressions for information on regular-expression matching on strings, bytes, and streams.

The bindings documented in this section are provided by the racket/match and racket libraries, but not racket/base.

(match val-expr clause ...)
 
clause = [pat body ...+]
  | [pat (=> id) body ...+]
Finds the first pat that matches the result of val-expr, and evaluates the corresponding bodys with bindings introduced by pat (if any). The last body in the matching clause is evaluated in tail position with respect to the match expression.

The clauses are tried in order to find a match. If no clause matches, then the exn:misc:match? exception is raised.

An optional (=> id) between a pat and the bodys is bound to a failure procedure of zero arguments. If this procedure is invoked, it escapes back to the pattern matching expression, and resumes the matching process as if the pattern had failed to match. The bodys must not mutate the object being matched before calling the failure procedure, otherwise the behavior of matching is unpredictable.

The grammar of pat is as follows, where non-italicized identifiers are recognized symbolically (i.e., not by binding).

pat

 

::=

 

id

 

match anything, bind identifier

 

 

 |

 

_

 

match anything

 

 

 |

 

literal

 

match literal

 

 

 |

 

(quote datum)

 

match equal? value

 

 

 |

 

(list lvp ...)

 

match sequence of lvps

 

 

 |

 

(list-rest lvp ... pat)

 

match lvps consed onto a pat

 

 

 |

 

(list-no-order pat ...)

 

match pats in any order

 

 

 |

 

(list-no-order pat ... lvp)

 

match pats in any order

 

 

 |

 

(vector lvp ...)

 

match vector of pats

 

 

 |

 

(hash-table (pat pat) ...)

 

match hash table

 

 

 |

 

(hash-table (pat pat) ...+ ooo)

 

match hash table

 

 

 |

 

(cons pat pat)

 

match pair of pats

 

 

 |

 

(mcons pat pat)

 

match mutable pair of pats

 

 

 |

 

(box pat)

 

match boxed pat

 

 

 |

 

(struct-id pat ...)

 

match struct-id instance

 

 

 |

 

(struct struct-id (pat ...))

 

match struct-id instance

 

 

 |

 

(regexp rx-expr)

 

match string

 

 

 |

 

(regexp rx-expr pat)

 

match string, result with pat

 

 

 |

 

(pregexp px-expr)

 

match string

 

 

 |

 

(pregexp px-expr pat)

 

match string, result with pat

 

 

 |

 

(and pat ...)

 

match when all pats match

 

 

 |

 

(or pat ...)

 

match when any pat match

 

 

 |

 

(not pat ...)

 

match when no pat matches

 

 

 |

 

(app expr pat)

 

match (expr value) to pat

 

 

 |

 

(? expr pat ...)

 

match if (expr value) and pats

 

 

 |

 

(quasiquote qp)

 

match a quasipattern

 

 

 |

 

derived-pattern

 

match using extension

literal

 

::=

 

#t

 

match true

 

 

 |

 

#f

 

match false

 

 

 |

 

string

 

match equal? string

 

 

 |

 

bytes

 

match equal? byte string

 

 

 |

 

number

 

match equal? number

 

 

 |

 

char

 

match equal? character

 

 

 |

 

keyword

 

match equal? keyword

 

 

 |

 

regexp

 

match equal? regexp literal

 

 

 |

 

pregexp

 

match equal? pregexp literal

lvp

 

::=

 

pat ooo

 

greedily match pat instances

 

 

 |

 

pat

 

match pat

qp

 

::=

 

literal

 

match literal

 

 

 |

 

id

 

match symbol

 

 

 |

 

(qp ...)

 

match sequences of qps

 

 

 |

 

(qp ... . qp)

 

match qps ending qp

 

 

 |

 

(qp ooo . qp)

 

match qps beginning with repeated qp

 

 

 |

 

#(qp ...)

 

match vector of qps

 

 

 |

 

#&qp

 

match boxed qp

 

 

 |

 

,pat

 

match pat

 

 

 |

 

,@(list lvp ...)

 

match lvps, spliced

 

 

 |

 

,@(list-rest lvp ... pat)

 

match lvps plus pat, spliced

 

 

 |

 

,@'qp

 

match list-matching qp, spliced

ooo

 

::=

 

...

 

zero or more; ... is literal

 

 

 |

 

___

 

zero or more

 

 

 |

 

..k

 

k or more

 

 

 |

 

__k

 

k or more

In more detail, patterns match as follows:

8.1 Additional Matching Forms

(match* (val-expr ...+) clause* ...)
 
clause* = [(pat ...+) body ...+]
  | [(pat ...+) (=> id) body ...+]
Matches a sequence of values against each clause in order, matching only when all patterns in a clause match. Each clause must have the same number of patterns as the number of val-exprs.

Example:

  > (match* (1 2 3)
     [(_ (? number?) x) (add1 x)])

  4

(match-lambda clause ...)
Equivalent to (lambda (id) (match id clause ...)).

(match-lambda* clause ...)
Equivalent to (lambda lst (match lst clause ...)).

(match-let ([pat expr] ...) body ...+)
Generalizes let to support pattern bindings. Each expr is matched against its corresponding pat (the match must succeed), and the bindings that pat introduces are visible in the bodys.

Example:

  > (match-let ([(list a b) '(1 2)]
                [(vector x ...) #(1 2 3 4)])
      (list b a x))

  '(2 1 (1 2 3 4))

(match-let* ([pat expr] ...) body ...+)
Like match-let, but generalizes let*, so that the bindings of each pat are available in each subsequent expr.

Example:

  > (match-let* ([(list a b) '(#(1 2 3 4) 2)]
                 [(vector x ...) a])
      x)

  '(1 2 3 4)

(match-letrec ([pat expr] ...) body ...+)
Like match-let, but generalizes letrec.

(match-define pat expr)
Defines the names bound by pat to the values produced by matching against the result of expr.

Examples:

  > (match-define (list a b) '(1 2))
  > b

  2

(exn:misc:match? v)  boolean?
  v : any/c
A predicate for the exception raised in the case of a match failure.

8.2 Extending match

(define-match-expander id proc-expr)
(define-match-expander id proc-expr proc-expr)
Binds id to a match expander.

The first proc-expr subexpression must evaluate to a transformer that produces a pat for match. Whenever id appears as the beginning of a pattern, this transformer is given, at expansion time, a syntax object corresponding to the entire pattern (including id). The pattern is replaced with the result of the transformer.

A transformer produced by a second proc-expr subexpression is used when id is used in an expression context. Using the second proc-expr, id can be given meaning both inside and outside patterns.

(match-equality-test)  (any/c any/c . -> . any)
(match-equality-test comp-proc)  void?
  comp-proc : (any/c any/c . -> . any)
A parameter that determines the comparison procedure used to check whether multiple uses of an identifier match the “same” value. The default is equal?.

8.3 Library Extensions

(struct* struct-id ([field pat] ...))
A match pattern form that matches an instance of a structure type named struct-id, where the field field in the instance matches the corresponding pat.

Any field of struct-id may be omitted, and such fields can occur in any order.

Examples:

  (define-struct tree (val left right))
  > (match (make-tree 0 (make-tree 1 #f #f) #f)
      [(struct* tree ([val a]
                      [left (struct* tree ([right #f] [val b]))]))
       (list a b)])

  '(0 1)