<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.00">
<link rel="stylesheet" type="text/css" href="manual.css">
<title>Patterns</title>
</head>
<body>
<a href="const.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="language.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="expr.html"><img src="next_motif.gif" alt="Next"></a>
<hr>
<h2 class="section" id="sec103">6.6  Patterns</h2>
<p>
<a id="hevea_manual.kwd5"></a>
</p><table class="display dcenter"><tr class="c026"><td class="dcell"><table class="c002 cellpading0"><tr><td class="c025">
<a class="syntax" id="pattern"><span class="c014">pattern</span></a></td><td class="c022">::=</td><td class="c024">
<a class="syntax" href="names.html#value-name"><span class="c014">value-name</span></a>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <span class="c008">_</span>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <a class="syntax" href="const.html#constant"><span class="c014">constant</span></a>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a> <span class="c008">as</span>  <a class="syntax" href="names.html#value-name"><span class="c014">value-name</span></a>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <span class="c008">(</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a> <span class="c008">)</span>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <span class="c008">(</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a> <span class="c008">:</span>  <a class="syntax" href="types.html#typexpr"><span class="c014">typexpr</span></a> <span class="c008">)</span>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a> <span class="c008">|</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <a class="syntax" href="names.html#constr"><span class="c014">constr</span></a>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <span class="c008">`</span><a class="syntax" href="names.html#tag-name"><span class="c014">tag-name</span></a>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <span class="c008">#</span><a class="syntax" href="names.html#typeconstr"><span class="c014">typeconstr</span></a>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a>  { <span class="c008">,</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a> }<sup>+</sup>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <span class="c008">{</span> <a class="syntax" href="names.html#field"><span class="c014">field</span></a> <span class="c008">=</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a>  { <span class="c008">;</span> <a class="syntax" href="names.html#field"><span class="c014">field</span></a> <span class="c008">=</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a> }  [ <span class="c008">;</span> ] <span class="c008">}</span>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <span class="c008">[</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a>  { <span class="c008">;</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a> }  [ <span class="c008">;</span> ] <span class="c008">]</span>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a> <span class="c008">::</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a>
 </td></tr>
<tr><td class="c025"> </td><td class="c022">∣</td><td class="c024"> <span class="c008">[|</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a>  { <span class="c008">;</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a> }  [ <span class="c008">;</span> ] <span class="c008">|]</span>
</td></tr>
</table></td></tr>
</table><p>The table below shows the relative precedences and associativity of
operators and non-closed pattern constructions. The constructions with
higher precedences come first.
<a id="hevea_manual.kwd6"></a>
</p><div class="center"><table class="c001 cellpadding1" border=1><tr><td class="c021"><span class="c019">Operator</span></td><td class="c021"><span class="c019">Associativity</span> </td></tr>
<tr><td class="c023">
<span class="c007">..</span> (see section <a href="extn.html#s%3Arange-patterns">7.4</a>)</td><td class="c023">– </td></tr>
<tr><td class="c023"><span class="c007">lazy</span> (see section <a href="extn.html#s%3Alazy">7.6</a>)</td><td class="c023">– </td></tr>
<tr><td class="c023">Constructor application, Tag application</td><td class="c023">right </td></tr>
<tr><td class="c023"><span class="c007">::</span></td><td class="c023">right </td></tr>
<tr><td class="c023"><span class="c007">,</span></td><td class="c023">– </td></tr>
<tr><td class="c023"><span class="c007">|</span></td><td class="c023">left </td></tr>
<tr><td class="c023"><span class="c007">as</span></td><td class="c023">– </td></tr>
</table></div><p>Patterns are templates that allow selecting data structures of a
given shape, and binding identifiers to components of the data
structure. This selection operation is called pattern matching; its
outcome is either “this value does not match this pattern”, or
“this value matches this pattern, resulting in the following bindings
of names to values”.</p><h4 class="subsubsection" id="sec104">Variable patterns</h4>
<p>A pattern that consists in a value name matches any value,
binding the name to the value. The pattern <span class="c008">_</span> also matches
any value, but does not bind any name.</p><p>Patterns are <em>linear</em>: a variable cannot be bound several times by
a given pattern. In particular, there is no way to test for equality
between two parts of a data structure using only a pattern (but
<span class="c008">when</span> guards can be used for this purpose).</p><h4 class="subsubsection" id="sec105">Constant patterns</h4>
<p>A pattern consisting in a constant matches the values that
are equal to this constant.</p><h4 class="subsubsection" id="sec106">Alias patterns</h4>
<p>
<a id="hevea_manual.kwd7"></a></p><p>The pattern <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">as</span>  <a class="syntax" href="names.html#value-name"><span class="c014">value-name</span></a> matches the same values as
<a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub>. If the matching against <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> is successful,
the name <a class="syntax" href="names.html#value-name"><span class="c014">value-name</span></a> is bound to the matched value, in addition to the
bindings performed by the matching against <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub>.</p><h4 class="subsubsection" id="sec107">Parenthesized patterns</h4>
<p>The pattern <span class="c008">(</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">)</span> matches the same values as
<a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub>. A type constraint can appear in a
parenthesized pattern, as in <span class="c008">(</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">:</span>  <a class="syntax" href="types.html#typexpr"><span class="c014">typexpr</span></a> <span class="c008">)</span>. This
constraint forces the type of <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> to be compatible with
<a class="syntax" href="types.html#typexpr"><span class="c014">typexpr</span></a>.</p><h4 class="subsubsection" id="sec108">“Or” patterns</h4>
<p>The pattern <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">|</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>2</sub> represents the logical “or” of
the two patterns <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> and <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>2</sub>. A value matches
<a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">|</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>2</sub> if it matches <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> or
<a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>2</sub>. The two sub-patterns <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> and <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>2</sub>
must bind exactly the same identifiers to values having the same types.
Matching is performed from left to right.
More precisely,
in case some value <span class="c013">v</span> matches <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">|</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>2</sub>, the bindings
performed are those of <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> when <span class="c013">v</span> matches <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub>.
Otherwise, value <span class="c013">v</span> matches <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>2</sub> whose bindings are performed.</p><h4 class="subsubsection" id="sec109">Variant patterns</h4>
<p>The pattern <a class="syntax" href="names.html#constr"><span class="c014">constr</span></a> <span class="c008">(</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">,</span> … <span class="c008">,</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">n</span></sub> <span class="c008">)</span> matches
all variants whose
constructor is equal to <a class="syntax" href="names.html#constr"><span class="c014">constr</span></a>, and whose arguments match
<a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> …  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">n</span></sub>. It is a type error if <span class="c013">n</span> is not the
number of arguments expected by the constructor.</p><p>The pattern <a class="syntax" href="names.html#constr"><span class="c014">constr</span></a> <span class="c008">_</span> matches all variants whose constructor is
<a class="syntax" href="names.html#constr"><span class="c014">constr</span></a>.</p><p>The pattern <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">::</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>2</sub> matches non-empty lists whose
heads match <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub>, and whose tails match <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>2</sub>.</p><p>The pattern <span class="c008">[</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">;</span> … <span class="c008">;</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">n</span></sub> <span class="c008">]</span> matches lists
of length <span class="c013">n</span> whose elements match <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> …<a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">n</span></sub>,
respectively. This pattern behaves like
<a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">::</span> … <span class="c008">::</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">n</span></sub> <span class="c005"><span class="c007">::</span> <span class="c007">[]</span></span>.</p><h4 class="subsubsection" id="sec110">Polymorphic variant patterns</h4>
<p>The pattern <span class="c008">`</span><a class="syntax" href="names.html#tag-name"><span class="c014">tag-name</span></a>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> matches all polymorphic variants
whose tag is equal to <a class="syntax" href="names.html#tag-name"><span class="c014">tag-name</span></a>, and whose argument matches
<a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub>.</p><h4 class="subsubsection" id="sec111">Polymorphic variant abbreviation patterns</h4>
<p>If the type [<span class="c008">('a,'b,</span>…<span class="c008">)</span>] <a class="syntax" href="names.html#typeconstr"><span class="c014">typeconstr</span></a> = <span class="c005"><span class="c007">[</span> <span class="c007">`</span></span> <a class="syntax" href="names.html#tag-name"><span class="c014">tag-name</span></a><sub>1</sub>  <a class="syntax" href="types.html#typexpr"><span class="c014">typexpr</span></a><sub>1</sub> <span class="c008">|</span>
… <span class="c005"><span class="c007">|</span> <span class="c007">`</span></span> <a class="syntax" href="names.html#tag-name"><span class="c014">tag-name</span></a><sub><span class="c013">n</span></sub>  <a class="syntax" href="types.html#typexpr"><span class="c014">typexpr</span></a><sub><span class="c013">n</span></sub><span class="c008">]</span> is defined, then the pattern <span class="c008">#</span><a class="syntax" href="names.html#typeconstr"><span class="c014">typeconstr</span></a>
is a shorthand for the following or-pattern:
<span class="c005"><span class="c007">(</span> <span class="c007">`</span></span><a class="syntax" href="names.html#tag-name"><span class="c014">tag-name</span></a><sub>1</sub><span class="c005"><span class="c007">(_</span> <span class="c007">:</span></span>  <a class="syntax" href="types.html#typexpr"><span class="c014">typexpr</span></a><sub>1</sub><span class="c005"><span class="c007">)</span> <span class="c007">|</span></span> … <span class="c005"><span class="c007">|</span> <span class="c007">`</span></span> <a class="syntax" href="names.html#tag-name"><span class="c014">tag-name</span></a><sub><span class="c013">n</span></sub><span class="c005"><span class="c007">(_</span>
<span class="c007">:</span></span>  <a class="syntax" href="types.html#typexpr"><span class="c014">typexpr</span></a><sub><span class="c013">n</span></sub><span class="c008">))</span>. It matches all values of type <span class="c008">[<</span> <a class="syntax" href="names.html#typeconstr"><span class="c014">typeconstr</span></a> <span class="c008">]</span>.</p><h4 class="subsubsection" id="sec112">Tuple patterns</h4>
<p>The pattern <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">,</span> … <span class="c008">,</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">n</span></sub> matches <span class="c013">n</span>-tuples
whose components match the patterns <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> through <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">n</span></sub>. That
is, the pattern matches the tuple values (<span class="c013">v</span><sub>1</sub>, …, <span class="c013">v</span><sub><span class="c013">n</span></sub>) such that
<a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">i</span></sub> matches <span class="c013">v</span><sub><span class="c013">i</span></sub> for <span class="c013">i</span> = 1,… , <span class="c013">n</span>.</p><h4 class="subsubsection" id="sec113">Record patterns</h4>
<p>The pattern <span class="c008">{</span> <a class="syntax" href="names.html#field"><span class="c014">field</span></a><sub>1</sub> <span class="c008">=</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">;</span> … <span class="c008">;</span>  <a class="syntax" href="names.html#field"><span class="c014">field</span></a><sub><span class="c013">n</span></sub> <span class="c008">=</span>
 <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">n</span></sub> <span class="c008">}</span> matches records that define at least the fields
<a class="syntax" href="names.html#field"><span class="c014">field</span></a><sub>1</sub> through <a class="syntax" href="names.html#field"><span class="c014">field</span></a><sub><span class="c013">n</span></sub>, and such that the value associated to
<a class="syntax" href="names.html#field"><span class="c014">field</span></a><sub><span class="c013">i</span></sub> matches the pattern <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">i</span></sub>, for <span class="c013">i</span> = 1,… , <span class="c013">n</span>.
The record value can define more fields than <a class="syntax" href="names.html#field"><span class="c014">field</span></a><sub>1</sub> …<a class="syntax" href="names.html#field"><span class="c014">field</span></a><sub><span class="c013">n</span></sub>; the values associated to these extra fields are not taken
into account for matching.</p><h4 class="subsubsection" id="sec114">Array patterns</h4>
<p>The pattern <span class="c008">[|</span> <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub>1</sub> <span class="c008">;</span> … <span class="c008">;</span>  <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">n</span></sub> <span class="c008">|]</span>
matches arrays of length <span class="c013">n</span> such that the <span class="c013">i</span>-th array element
matches the pattern <a class="syntax" href="#pattern"><span class="c014">pattern</span></a><sub><span class="c013">i</span></sub>, for <span class="c013">i</span> = 1,… , <span class="c013">n</span>.</p>
<hr>
<a href="const.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="language.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="expr.html"><img src="next_motif.gif" alt="Next"></a>
</body>
</html>
