7.7 Expressions

See also the following language extensions:first-class modules,overriding in open statements,syntax for Bigarray access,attributes,extension nodes andextended indexing operators.

7.7.1 Precedence and associativity

The table below shows the relative precedences and associativity ofoperators and non-closed constructions. The constructions with higherprecedence come first. For infix and prefix symbols, we write“…” to mean “any symbol starting with ”.

7.7.2 Basic expressions

Constants

An expression consisting in a constant evaluates to this constant.

Value paths

An expression consisting in an access path evaluates to the value bound tothis path in the current evaluation environment. The path canbe either a value name or an access path to a value component of a module.

Parenthesized expressions

The expressions (expr) and beginexprend have the samevalue as expr. The two constructs are semantically equivalent, but itis good style to use begin … end inside control structures:

        if … then begin … ; … end else begin … ; … end

and ( … ) for the other grouping situations.

Parenthesized expressions can contain a type constraint, as in (expr: typexpr). This constraint forces the type of expr to becompatible with typexpr.

Parenthesized expressions can also contain coercions(expr [:typexpr] :> typexpr) (seesubsection 7.7.7 below).

Function application

Function application is denoted by juxtaposition of (possibly labeled)expressions. The expression expr argument₁ … argument_nevaluates the expression expr and those appearing in argument₁to argument_n. The expression expr must evaluate to afunctional value f, which is then applied to the values ofargument₁, …, argument_n.

The order in which the expressions expr, argument₁, …, argument_n are evaluated is not specified.

Arguments and parameters are matched according to their respectivelabels. Argument order is irrelevant, except among arguments with thesame label, or no label.

If a parameter is specified as optional (label prefixed by ?) in thetype of expr, the corresponding argument will be automaticallywrapped with the constructor Some, except if the argument itself isalso prefixed by ?, in which case it is passed as is.If a non-labeled argument is passed, and its corresponding parameteris preceded by one or several optional parameters, then theseparameters are defaulted, i.e. the value None will bepassed for them.All other missing parameters (without corresponding argument), bothoptional and non-optional, will be kept, and the result of thefunction will still be a function of these missing parameters to thebody of f.

As a special case, if the function has a known arity, all thearguments are unlabeled, and their number matches the number ofnon-optional parameters, then labels are ignored and non-optionalparameters are matched in their definition order. Optional argumentsare defaulted.

In all cases but exact match of order and labels, without optionalparameters, the function type should be known at the applicationpoint. This can be ensured by adding a type constraint. Principalityof the derivation can be checked in the -principal mode.

Function definition

Two syntactic forms are provided to define functions. The first formis introduced by the keyword function:

This expression evaluates to a functional value with one argument.When this function is applied to a value v, this value ismatched against each pattern pattern₁ to pattern_n.If one of these matchings succeeds, that is, if the value vmatches the pattern pattern_i for some i,then the expression expr_i associated to the selected patternis evaluated, and its value becomes the value of the functionapplication. The evaluation of expr_i takes place in anenvironment enriched by the bindings performed during the matching.

If several patterns match the argument v, the one that occursfirst in the function definition is selected. If none of the patternsmatches the argument, the exception Match_failure is raised.

The other form of function definition is introduced by the keyword fun:

funparameter₁ … parameter_n-> expr

This expression is equivalent to:

funparameter₁-> … fun parameter_n-> expr

An optional type constraint typexpr can be added before -> to enforcethe type of the result to be compatible with the constraint typexpr:

funparameter₁ … parameter_n: typexpr-> expr

is equivalent to

funparameter₁-> … fun parameter_n-> (expr: typexpr )

Beware of the small syntactic difference between a type constraint onthe last parameter

funparameter₁ … (parameter_n: typexpr)-> expr

and one on the result

funparameter₁ … parameter_n: typexpr-> expr

The parameter patterns ~lab and ~(lab [:typ])are shorthands for respectively ~lab: lab and~lab:( lab [:typ]), and similarly for their optionalcounterparts.

A function of the form fun?lab:( pattern= expr₀)-> expr is equivalent to

fun?lab: ident->let pattern=match identwithSome ident-> ident|None-> expr₀in expr

where identis a fresh variable, except that it is unspecified when expr₀ is evaluated.

After these two transformations, expressions are of the form

fun [label₁] pattern₁-> … fun [label_n] pattern_n-> expr

If we ignore labels, which will only be meaningful at functionapplication, this is equivalent to

functionpattern₁-> … function pattern_n-> expr

That is, the fun expression above evaluates to a curried functionwith n arguments: after applying this function n times to thevalues v₁ … v_n, the values will be matchedin parallel against the patterns pattern₁ … pattern_n.If the matching succeeds, the function returns the value of expr inan environment enriched by the bindings performed during the matchings.If the matching fails, the exception Match_failure is raised.

Guards in pattern-matchings

The cases of a pattern matching (in the function, match andtry constructs) can include guard expressions, which arearbitrary boolean expressions that must evaluate to true for thematch case to be selected. Guards occur just before the -> token andare introduced by the when keyword:

Matching proceeds as described before, except that if the valuematches some pattern pattern_i which has a guard cond_i, then theexpression cond_i is evaluated (in an environment enriched by thebindings performed during matching). If cond_i evaluates to true,then expr_i is evaluated and its value returned as the result of thematching, as usual. But if cond_i evaluates to false, the matchingis resumed against the patterns following pattern_i.

Local definitions

The let and letrec constructs bind value names locally.The construct

letpattern₁= expr₁and … and pattern_n= expr_nin expr

evaluates expr₁ … expr_n in some unspecified order and matchestheir values against the patterns pattern₁ … pattern_n. If thematchings succeed, expr is evaluated in the environment enriched bythe bindings performed during matching, and the value of expr isreturned as the value of the whole let expression. If one of thematchings fails, the exception Match_failure is raised.

An alternate syntax is provided to bind variables to functionalvalues: instead of writing

letident=fun parameter₁ … parameter_m-> expr

in a let expression, one may instead write

letident parameter₁ … parameter_m= expr

Recursive definitions of names are introduced by letrec:

letrecpattern₁= expr₁and … and pattern_n= expr_nin expr

The only difference with the let construct described above isthat the bindings of names to values performed by thepattern-matching are considered already performed when the expressionsexpr₁ to expr_n are evaluated. That is, the expressions expr₁to expr_n can reference identifiers that are bound by one of thepatterns pattern₁, …, pattern_n, and expect them to have thesame value as in expr, the body of the letrec construct.

The recursive definition is guaranteed to behave as described above ifthe expressions expr₁ to expr_n are function definitions(fun … or function …), and the patterns pattern₁… pattern_n are just value names, as in:

letrecname₁=fun …and …and name_n=fun …in expr

This defines name₁ … name_n as mutually recursive functionslocal to expr.

The behavior of other forms of letrec definitions isimplementation-dependent. The current implementation also supportsa certain class of recursive definitions of non-functional values,as explained in section 8.1.

Explicit polymorphic type annotations

(Introduced in OCaml 3.12)

Polymorphic type annotations in let-definitions behave in a waysimilar to polymorphic methods:

letpattern₁: typ₁ … typ_n. typeexpr= expr

These annotations explicitly require the defined value to be polymorphic,and allow one to use this polymorphism in recursive occurrences(when using letrec). Note however that this is a normal polymorphictype, unifiable with any instance of itself.

It is possible to define local exceptions in expressions: letexception constr-declin expr .The syntactic scope of the exception constructor is the innerexpression, but nothing prevents exception values created with thisconstructor from escaping this scope. Two executions of the definitionabove result in two incompatible exception constructors (as for anyexception definition). For instance, the following assertion istrue:

  let gen () = let exception A in A
  let () = assert(gen () <> gen ())

7.7.3 Control structures

Sequence

The expression expr₁; expr₂ evaluates expr₁ first, thenexpr₂, and returns the value of expr₂.

Conditional

The expression ifexpr₁then expr₂else expr₃ evaluates tothe value of expr₂ if expr₁ evaluates to the boolean true,and to the value of expr₃ if expr₁ evaluates to the booleanfalse.

The elseexpr₃ part can be omitted, in which case it defaults toelse().

Case expression

The expression

matches the value of expr against the patterns pattern₁ topattern_n. If the matching against pattern_i succeeds, theassociated expression expr_i is evaluated, and its value becomes thevalue of the whole match expression. The evaluation ofexpr_i takes place in an environment enriched by the bindingsperformed during matching. If several patterns match the value ofexpr, the one that occurs first in the match expression isselected. If none of the patterns match the value of expr, theexception Match_failure is raised.

Boolean operators

The expression expr₁&& expr₂ evaluates to true if bothexpr₁ and expr₂ evaluate to true; otherwise, it evaluates tofalse. The first component, expr₁, is evaluated first. Thesecond component, expr₂, is not evaluated if the first componentevaluates to false. Hence, the expression expr₁&& expr₂ behavesexactly as

ifexpr₁then expr₂elsefalse.

The expression expr₁|| expr₂ evaluates to true if one ofthe expressionsexpr₁ and expr₂ evaluates to true; otherwise, it evaluates tofalse. The first component, expr₁, is evaluated first. Thesecond component, expr₂, is not evaluated if the first componentevaluates to true. Hence, the expression expr₁|| expr₂ behavesexactly as

ifexpr₁thentrueelse expr₂.

The boolean operators & and or are deprecated synonyms for(respectively) && and ||.

Loops

The expression whileexpr₁do expr₂done repeatedlyevaluates expr₂ while expr₁ evaluates to true. The loopcondition expr₁ is evaluated and tested at the beginning of eachiteration. The whole while … done expression evaluates tothe unit value ().

The expression forname= expr₁to expr₂do expr₃donefirst evaluates the expressions expr₁ and expr₂ (the boundaries)into integer values n and p. Then, the loop body expr₃ isrepeatedly evaluated in an environment where name is successivelybound to the valuesn, n+1, …, p−1, p.The loop body is never evaluated if n > p.

The expression forname= expr₁downto expr₂do expr₃doneevaluates similarly, except that name is successively bound to the valuesn, n−1, …, p+1, p.The loop body is never evaluated if n < p.

In both cases, the whole for expression evaluates to the unitvalue ().

Exception handling

The expression

evaluates the expression expr and returns its value if theevaluation of expr does not raise any exception. If the evaluationof expr raises an exception, the exception value is matched againstthe patterns pattern₁ to pattern_n. If the matching againstpattern_i succeeds, the associated expression expr_i is evaluated,and its value becomes the value of the whole try expression. Theevaluation of expr_i takes place in an environment enriched by thebindings performed during matching. If several patterns match the value ofexpr, the one that occurs first in the try expression isselected. If none of the patterns matches the value of expr, theexception value is raised again, thereby transparently “passingthrough” the try construct.

7.7.4 Operations on data structures

Products

The expression expr₁, … , expr_n evaluates to then-tuple of the values of expressions expr₁ to expr_n. Theevaluation order of the subexpressions is not specified.

Variants

The expression constr expr evaluates to the unary variant valuewhose constructor is constr, and whose argument is the value ofexpr. Similarly, the expression constr( expr₁, … , expr_n) evaluates to the n-ary variant value whose constructor isconstr and whose arguments are the values of expr₁, …, expr_n.

The expression constr( expr₁, …, expr_n) evaluates to thevariant value whose constructor is constr, and whose arguments arethe values of expr₁ … expr_n.

For lists, some syntactic sugar is provided. The expressionexpr₁:: expr₂ stands for the constructor (::) applied to the arguments (expr₁, expr₂), and thereforeevaluates to the list whose head is the value of expr₁ and whose tailis the value of expr₂. The expression [expr₁; … ; expr_n] is equivalent to expr₁:: … :: expr_n::[], and therefore evaluates to the list whose elements are thevalues of expr₁ to expr_n.

Polymorphic variants

The expression `tag-name expr evaluates to the polymorphic variantvalue whose tag is tag-name, and whose argument is the value of expr.

Records

The expression {field₁ [=expr₁] ; … ; field_n [=expr_n]} evaluates to the record value{ field₁ = v₁; …; field_n = v_n }where v_i is the value of expr_i for i = 1,… , n.A single identifier field_k stands for field_k= field_k,and a qualified identifier module-path. field_k stands formodule-path. field_k= field_k.The fields field₁ to field_n must all belong to the same recordtype; each field of this record type must appear exactlyonce in the record expression, though they can appear in anyorder. The order in which expr₁ to expr_n are evaluated is notspecified. Optional type constraints can be added after each field{field₁: typexpr₁= expr₁;… ; field_n: typexpr_n= expr_n}to force the type of field_k to be compatible with typexpr_k.

The expression{exprwith field₁ [=expr₁] ; … ; field_n [=expr_n] }builds a fresh record with fields field₁ … field_n equal toexpr₁ … expr_n, and all other fields having the same value asin the record expr. In other terms, it returns a shallow copy ofthe record expr, except for the fields field₁ … field_n,which are initialized to expr₁ … expr_n. As previously,single identifier field_k stands for field_k= field_k,a qualified identifier module-path. field_k stands formodule-path. field_k= field_k and it ispossible to add an optional type constraint on each field being updatedwith{exprwith field₁: typexpr₁= expr₁; … ; field_n: typexpr_n= expr_n}.

The expression expr₁. field evaluates expr₁ to a recordvalue, and returns the value associated to field in this recordvalue.

The expression expr₁. field<- expr₂ evaluates expr₁ to a recordvalue, which is then modified in-place by replacing the valueassociated to field in this record by the value ofexpr₂. This operation is permitted only if field has beendeclared mutable in the definition of the record type. The wholeexpression expr₁. field<- expr₂ evaluates to the unit value().

Arrays

The expression [|expr₁; … ; expr_n|] evaluates toa n-element array, whose elements are initialized with the values ofexpr₁ to expr_n respectively. The order in which theseexpressions are evaluated is unspecified.

The expression expr₁.( expr₂) returns the value of elementnumber expr₂ in the array denoted by expr₁. The first elementhas number 0; the last element has number n−1, where n is thesize of the array. The exception Invalid_argument is raised if theaccess is out of bounds.

The expression expr₁.( expr₂)<- expr₃ modifies in-placethe array denoted by expr₁, replacing element number expr₂ bythe value of expr₃. The exception Invalid_argument is raised ifthe access is out of bounds. The value of the whole expression is ().

Strings

The expression expr₁.[ expr₂] returns the value of characternumber expr₂ in the string denoted by expr₁. The first characterhas number 0; the last character has number n−1, where n is thelength of the string. The exception Invalid_argument is raised if theaccess is out of bounds.

The expression expr₁.[ expr₂]<- expr₃ modifies in-placethe string denoted by expr₁, replacing character number expr₂ bythe value of expr₃. The exception Invalid_argument is raised ifthe access is out of bounds. The value of the whole expression is ().

Note: this possibility is offered only for backwardcompatibility with older versions of OCaml and will be removed in afuture version. New code should use byte sequences and the Bytes.setfunction.

7.7.5 Operators

Symbols from the class infix-symbol, as well as the keywords*, +, -, -., =, !=, <, >, or, ||,&, &&, :=, mod, land, lor, lxor, lsl, lsr,and asr can appear in infix position (between twoexpressions). Symbols from the class prefix-symbol, as well asthe keywords - and -.can appear in prefix position (in front of an expression).

Infix and prefix symbols do not have a fixed meaning: they are simplyinterpreted as applications of functions bound to the namescorresponding to the symbols. The expression prefix-symbol expr isinterpreted as the application (prefix-symbol) expr. Similarly, the expression expr₁ infix-symbol expr₂ isinterpreted as the application (infix-symbol) expr₁ expr₂.

The table below lists the symbols defined in the initial environmentand their initial meaning. (See the description of the corelibrary module Pervasives in chapter 23 for moredetails). Their meaning may be changed at any time usinglet(infix-op) name₁ name₂= …

Note: the operators &&, ||, and ~- are handled speciallyand it is not advisable to change their meaning.

The keywords - and -. can appear both as infix andprefix operators. When they appear as prefix operators, they areinterpreted respectively as the functions (~-) and (~-.).

7.7.6 Objects

Object creation

When class-path evaluates to a class body, newclass-pathevaluates to a new object containing the instance variables andmethods of this class.

When class-path evaluates to a class function, newclass-pathevaluates to a function expecting the same number of arguments andreturning a new object of this class.

Immediate object creation

Creating directly an object through the objectclass-bodyendconstruct is operationally equivalent to defining locally a classclass-name=object class-bodyend —see sections7.9.2 and following for the syntax of class-body—and immediately creating a single object from it by newclass-name.

The typing of immediate objects is slightly different from explicitlydefining a class in two respects. First, the inferred object type maycontain free type variables. Second, since the class body of animmediate object will never be extended, its self type can be unifiedwith a closed object type.

Method invocation

The expression expr# method-name invokes the methodmethod-name of the object denoted by expr.

If method-name is a polymorphic method, its type should be known atthe invocation site. This is true for instance if expr is the nameof a fresh object (letident = new class-path … ) or ifthere is a type constraint. Principality of the derivation can bechecked in the -principal mode.

Accessing and modifying instance variables

The instance variables of a class are visible only in the body of themethods defined in the same class or a class that inherits from theclass defining the instance variables. The expression inst-var-nameevaluates to the value of the given instance variable. The expressioninst-var-name<- expr assigns the value of expr to the instancevariable inst-var-name, which must be mutable. The whole expressioninst-var-name<- expr evaluates to ().

Object duplication

An object can be duplicated using the library function Oo.copy(seeModule Oo). Inside a method, the expression {< [inst-var-name [=expr] { ;inst-var-name [=expr] }] >}returns a copy of self with the given instance variables replaced bythe values of the associated expressions. A single instance variablename id stands for id= id. Other instance variables have the samevalue in the returned object as in self.

7.7.7 Coercions

Expressions whose type contains object or polymorphic variant typescan be explicitly coerced (weakened) to a supertype.The expression (expr:> typexpr) coerces the expression exprto type typexpr.The expression (expr: typexpr₁:> typexpr₂) coerces theexpression expr from type typexpr₁ to type typexpr₂.

The former operator will sometimes fail to coerce an expression exprfrom a type typ₁ to a type typ₂even if type typ₁ is a subtype of typetyp₂: in the current implementation it only expands two levels oftype abbreviations containing objects and/or polymorphic variants,keeping only recursion when it is explicit in the class type (for objects).As an exception to the above algorithm, if both the inferred type of exprand typ are ground (i.e. do not contain type variables), theformer operator behaves as the latter one, taking the inferred type ofexpr as typ₁. In case of failure with the former operator,the latter one should be used.

It is only possible to coerce an expression expr from typetyp₁ to type typ₂, if the type of expr is an instance oftyp₁ (like for a type annotation), and typ₁ is a subtypeof typ₂. The type of the coerced expression is aninstance of typ₂. If the types contain variables,they may be instantiated by the subtyping algorithm, but this is onlydone after determining whether typ₁ is a potential subtype oftyp₂. This means that typing may fail during this latterunification step, even if some instance of typ₁ is a subtype ofsome instance of typ₂.In the following paragraphs we describe the subtyping relation used.

Object types

A fixed object type admits as subtype any object type that includes allits methods. The types of the methods shall be subtypes of those inthe supertype. Namely,

<met₁: typ₁; … ; met_n: typ_n>

is a supertype of

<met₁: typ′₁; … ;met_n: typ′_n;met_n+1:typ′_n+1; … ;met_n+m:typ′_n+m [;..] >

which may contain an ellipsis .. if every typ_i is a supertype ofthe corresponding typ′_i.

A monomorphic method type can be a supertype of a polymorphic methodtype. Namely, if typ is an instance of typ′, then 'a₁… 'a_n.typ′ is a subtype of typ.

Inside a class definition, newly defined types are not available forsubtyping, as the type abbreviations are not yet completelydefined. There is an exception for coercing self to the (exact)type of its class: this is allowed if the type of self does notappear in a contravariant position in the class type, i.e. ifthere are no binary methods.

Polymorphic variant types

A polymorphic variant type typ is a subtype of another polymorphicvariant type typ′ if the upper bound of typ (i.e. themaximum set of constructors that may appear in an instance of typ)is included in the lower bound of typ′, and the types of argumentsfor the constructors of typ are subtypes of those intyp′. Namely,

[[<] [C]($49815e5ab82eadea.md#constr-name)<sub>1</sub>of [typ]($2ecc3987e27872fa.md#typexpr)<sub>1</sub>| … | C_nof typ_n]

which may be a shrinkable type, is a subtype of

[[>] [C]($49815e5ab82eadea.md#constr-name)<sub>1</sub>of [typ]($2ecc3987e27872fa.md#typexpr)′<sub>1</sub>| … |C_nof typ′_n|[C]($49815e5ab82eadea.md#constr-name)<sub>n+1</sub>of[typ]($2ecc3987e27872fa.md#typexpr)′<sub>n+1</sub>| … |C_n+moftyp′_n+m]

which may be an extensible type, if every typ_i is a subtype of typ′_i.

Variance

Other types do not introduce new subtyping, but they may propagate thesubtyping of their arguments. For instance, typ₁ typ₂ is asubtype of typ′₁typ′₂ when typ₁ and typ₂ arerespectively subtypes of typ′₁ and typ′₂.For function types, the relation is more subtle:typ₁-> typ₂ is a subtype of typ′₁ ->typ′₂if typ₁ is a supertype of typ′₁ and typ₂ is asubtype of typ′₂. For this reason, function types are covariant intheir second argument (like tuples), but contravariant in their firstargument. Mutable types, like array or ref are neither covariantnor contravariant, they are nonvariant, that is they do not propagatesubtyping.

For user-defined types, the variance is automatically inferred: aparameter is covariant if it has only covariant occurrences,contravariant if it has only contravariant occurrences,variance-free if it has no occurrences, and nonvariant otherwise.A variance-free parameter may change freely through subtyping, it doesnot have to be a subtype or a supertype.For abstract and private types, the variance must be given explicitly(see section 7.8.1),otherwise the default is nonvariant. This is also the case forconstrained arguments in type definitions.

7.7.8 Other

Assertion checking

OCaml supports the assert construct to check debugging assertions.The expression assertexpr evaluates the expression expr andreturns () if expr evaluates to true. If it evaluates tofalse the exceptionAssert_failure is raised with the source file name and thelocation of expr as arguments. Assertionchecking can be turned off with the -noassert compiler option. Inthis case, expr is not evaluated at all.

As a special case, assert false is reduced toraise(Assert_failure …), which gives it a polymorphictype. This means that it can be used in place of any expression (forexample as a branch of any pattern-matching). It also means thatthe assert false “assertions” cannot be turned off by the-noassert option.

Lazy expressions

The expression lazyexpr returns a value v of type Lazy.t thatencapsulates the computation of expr. The argument expr is notevaluated at this point in the program. Instead, its evaluation willbe performed the first time the function Lazy.force is applied to the valuev, returning the actual value of expr. Subsequent applicationsof Lazy.force to v do not evaluate expr again. Applicationsof Lazy.force may be implicit through pattern matching (see 7.6).

Local modules

The expressionletmodulemodule-name= module-exprin exprlocally binds the module expression module-expr to the identifiermodule-name during the evaluation of the expression expr.It then returns the value of expr. For example:

 let remove_duplicates comparison_fun string_list =
   let module StringSet =
     Set.Make(struct type t = string
                     let compare = comparison_fun end) in
   StringSet.elements
     (List.fold_right StringSet.add string_list StringSet.empty)
val remove_duplicates :
  (string -> string -> int) -> string list -> string list = <fun>

Local opens

The expressions letopenmodule-pathin expr andmodule-path.( expr) are strictly equivalent. Theseconstructions locally open the module referred to by the module pathmodule-path in the respective scope of the expression expr.

When the body of a local open expression is delimited by[], [||], or {}, the parentheses can be omitted.For expression, parentheses can also be omitted for {<>}.For example, module-path.[ expr] is equivalent tomodule-path.([ expr]), and module-path.[| expr|] isequivalent to module-path.([| expr|]).