7.6 Patterns

See also the following language extensions:local opens,first-class modules,attributes andextension nodes.

The table below shows the relative precedences and associativity ofoperators and non-closed pattern constructions. The constructions withhigher precedences come first.

Patterns are templates that allow selecting data structures of agiven shape, and binding identifiers to components of the datastructure. This selection operation is called pattern matching; itsoutcome is either “this value does not match this pattern”, or“this value matches this pattern, resulting in the following bindingsof names to values”.

Variable patterns

A pattern that consists in a value name matches any value,binding the name to the value. The pattern _ also matchesany value, but does not bind any name.

Patterns are linear: a variable cannot be bound several times bya given pattern. In particular, there is no way to test for equalitybetween two parts of a data structure using only a pattern (butwhen guards can be used for this purpose).

Constant patterns

A pattern consisting in a constant matches the values thatare equal to this constant.

Alias patterns

The pattern pattern₁as value-name matches the same values aspattern₁. If the matching against pattern₁ is successful,the name value-name is bound to the matched value, in addition to thebindings performed by the matching against pattern₁.

Parenthesized patterns

The pattern (pattern₁) matches the same values aspattern₁. A type constraint can appear in aparenthesized pattern, as in (pattern₁: typexpr). Thisconstraint forces the type of pattern₁ to be compatible withtypexpr.

“Or” patterns

The pattern pattern₁| pattern₂ represents the logical “or” ofthe two patterns pattern₁ and pattern₂. A value matchespattern₁| pattern₂ if it matches pattern₁ orpattern₂. The two sub-patterns pattern₁ and pattern₂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 v matches pattern₁| pattern₂, the bindingsperformed are those of pattern₁ when v matches pattern₁.Otherwise, value v matches pattern₂ whose bindings are performed.

Variant patterns

The pattern constr( pattern₁, … , pattern_n) matchesall variants whoseconstructor is equal to constr, and whose arguments matchpattern₁ … pattern_n. It is a type error if n is not thenumber of arguments expected by the constructor.

The pattern constr_ matches all variants whose constructor isconstr.

The pattern pattern₁:: pattern₂ matches non-empty lists whoseheads match pattern₁, and whose tails match pattern₂.

The pattern [pattern₁; … ; pattern_n] matches listsof length n whose elements match pattern₁ …pattern_n,respectively. This pattern behaves likepattern₁:: … :: pattern_n::[].

Polymorphic variant patterns

The pattern `tag-name pattern₁ matches all polymorphic variantswhose tag is equal to tag-name, and whose argument matchespattern₁.

Polymorphic variant abbreviation patterns

If the type [('a,'b,…)] typeconstr = [[tag-name]($49815e5ab82eadea.md#tag-name)<sub>1</sub> [typexpr]($2ecc3987e27872fa.md#typexpr)<sub>1</sub>|… | tag-name_n typexpr_n] is defined, then the pattern #typeconstris a shorthand for the following or-pattern:([tag-name]($49815e5ab82eadea.md#tag-name)<sub>1</sub>(_: [typexpr]($2ecc3987e27872fa.md#typexpr)<sub>1</sub>)| … | tag-name_n(_: typexpr_n)). It matches all values of type [<typeconstr].

Tuple patterns

The pattern pattern₁, … , pattern_n matches n-tupleswhose components match the patterns pattern₁ through pattern_n. Thatis, the pattern matches the tuple values (v₁, …, v_n) such thatpattern_i matches v_i for i = 1,… , n.

Record patterns

The pattern {field₁ [=pattern₁] ; … ; field_n [=pattern_n] } matches records that define at least the fieldsfield₁ through field_n, and such that the value associated tofield_i matches the pattern pattern_i, for i = 1,… , n.A single identifier field_k stands for field_k= field_k ,and a single qualified identifier module-path. field_k standsfor module-path. field_k= field_k .The record value can define more fields than field₁ …field_n; the values associated to these extra fields are not takeninto account for matching. Optionally, a record pattern can be terminatedby ;_ to convey the fact that not all fields of the record type arelisted in the record pattern and that it is intentional.Optional type constraints can be added field by field with{field₁: typexpr₁= pattern₁;… ; field_n: typexpr_n= pattern_n} to force the typeof field_k to be compatible with typexpr_k.

Array patterns

The pattern [|pattern₁; … ; pattern_n|]matches arrays of length n such that the i-th array elementmatches the pattern pattern_i, for i = 1,… , n.

Range patterns

The pattern'c'..'d' is a shorthand for the pattern

'c'|'c₁'|'c₂'| …|'c_n'|'d'

where c₁, c₂, …, c_n are the charactersthat occur between c and d in the ASCII character set. Forinstance, the pattern '0'..'9' matches all characters that are digits.

Lazy patterns

(Introduced in Objective Caml 3.11)

The pattern lazypattern matches a value v of type Lazy.t,provided pattern matches the result of forcing v withLazy.force. A successful match of a pattern containing lazysub-patterns forces the corresponding parts of the value being matched, eventhose that imply no test such as lazyvalue-name or lazy_.Matching a value with a pattern-matching where some patternscontain lazy sub-patterns may imply forcing parts of the value,even when the pattern selected in the end has no lazy sub-pattern.

For more information, see the description of module Lazy in thestandard library (Module Lazy).

Exception patterns

(Introduced in OCaml 4.02)

A new form of exception pattern, exceptionpattern , is allowedonly as a toplevel pattern or inside a toplevel or-pattern undera match…with pattern-matching(other occurrences are rejected by the type-checker).

Cases with such a toplevel pattern are called “exception cases”,as opposed to regular “value cases”. Exception cases are appliedwhen the evaluation of the matched expression raises an exception.The exception value is then matched against all the exception casesand re-raised if none of them accept the exception (as with atry…with block). Since the bodies of all exception and valuecases are outside the scope of the exception handler, they are allconsidered to be in tail-position: if the match…with blockitself is in tail position in the current function, any function callin tail position in one of the case bodies results in an actual tailcall.

A pattern match must contain at least one value case. It is an error ifall cases are exceptions, because there would be no code to handlethe return of a value.