7 Expressions

• 7.1 Precedence and associativity
• 7.2 Basic expressions
• 7.3 Control structures
• 7.4 Operations on data structures
• 7.5 Operators
• 7.6 Objects
• 7.7 Coercions
• 7.8 Other

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

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

It is simple to test or refresh one’s understanding:

7.2 Basic expressions

Constants

An expression consisting in a constant evaluates to this constant. For example,3.14 or[||].

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) andbeginexprend have the samevalue asexpr. The two constructs are semantically equivalent, but itis good style to usebegin …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 ofexpr to becompatible withtypexpr.

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

Function application

Function application is denoted by juxtaposition of (possibly labeled)expressions. The expressionexprargument₁ …argument_nevaluates the expressionexpr and those appearing inargument₁toargument_n. The expressionexpr must evaluate to afunctional valuef, which is then applied to the values ofargument₁, …,argument_n.

The order in which the expressionsexpr,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 ofexpr, the corresponding argument will be automaticallywrapped with the constructorSome, 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 aredefaulted,i.e. the valueNone 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 off.

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.

As a special case, OCaml supportslabels-omitted full applications:if the function has a known arity, all the arguments are unlabeled,and their number matches the number of non-optional parameters, thenlabels are ignored and non-optional parameters are matched in theirdefinition order. Optional arguments are defaulted. This omission oflabels is discouraged and results in a warning, see13.5.1.

Function definition

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

This expression evaluates to a functional value with one argument.When this function is applied to a valuev, this value ismatched against each patternpattern₁ topattern_n.If one of these matchings succeeds, that is, if the valuevmatches the patternpattern_i for somei,then the expressionexpr_i associated to the selected patternis evaluated, and its value becomes the value of the functionapplication. The evaluation ofexpr_i takes place in anenvironment enriched by the bindings performed during the matching.

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

The other form of function definition is introduced by the keywordfun:

This expression is equivalent to:

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

is equivalent to

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

and one on the result

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 formfun?lab:(pattern=expr₀)->expr is equivalent to

whereidentis a fresh variable, except that it is unspecified whenexpr₀ is evaluated.

After these two transformations, expressions are of the form

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

That is, thefun expression above evaluates to a curried functionwithn arguments: after applying this functionn times to thevaluesv₁ …v_n, the values will be matchedin parallel against the patternspattern₁ …pattern_n.If the matching succeeds, the function returns the value ofexpr inan environment enriched by the bindings performed during the matchings.If the matching fails, the exceptionMatch_failure is raised.

Guards in pattern-matchings

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

Matching proceeds as described before, except that if the valuematches some patternpattern_i which has a guardcond_i, then theexpressioncond_i is evaluated (in an environment enriched by thebindings performed during matching). Ifcond_i evaluates totrue,thenexpr_i is evaluated and its value returned as the result of thematching, as usual. But ifcond_i evaluates tofalse, the matchingis resumed against the patterns followingpattern_i.

Local definitions

Thelet andletrec constructs bind value names locally.The construct

evaluatesexpr₁ …expr_n in some unspecified order and matchestheir values against the patternspattern₁ …pattern_n. If thematchings succeed,expr is evaluated in the environment enriched bythe bindings performed during matching, and the value ofexpr isreturned as the value of the wholelet expression. If one of thematchings fails, the exceptionMatch_failure is raised.

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

in alet expression, one may instead write

Recursive definitions of names are introduced byletrec:

The only difference with thelet construct described above isthat the bindings of names to values performed by thepattern-matching are considered already performed when the expressionsexpr₁ toexpr_n are evaluated. That is, the expressionsexpr₁toexpr_n can reference identifiers that are bound by one of thepatternspattern₁, …,pattern_n, and expect them to have thesame value as inexpr, the body of theletrec construct.

The recursive definition is guaranteed to behave as described above ifthe expressionsexpr₁ toexpr_n are function definitions(fun … orfunction …), and the patternspattern₁…pattern_n are just value names, as in:

This definesname₁ …name_n as mutually recursive functionslocal toexpr.

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

Local exceptions

(Introduced in OCaml 4.04)

It is possible to define local exceptions in expressions:letexceptionconstr-declinexpr .

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:

Explicit polymorphic type annotations

(Introduced in OCaml 3.12)

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

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

7.3 Control structures

Sequence

The expressionexpr₁;expr₂ evaluatesexpr₁ first, thenexpr₂, and returns the value ofexpr₂.

Conditional

The expressionifexpr₁thenexpr₂elseexpr₃ evaluates tothe value ofexpr₂ ifexpr₁ evaluates to the booleantrue,and to the value ofexpr₃ ifexpr₁ evaluates to the booleanfalse.

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

Case expression

The expression

matches the value ofexpr against the patternspattern₁ topattern_n. If the matching againstpattern_i succeeds, theassociated expressionexpr_i is evaluated, and its value becomes thevalue of the wholematch 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 thematch expression isselected.

If none of the patterns match the value ofexpr, theexceptionMatch_failure is raised.

Boolean operators

The expressionexpr₁&&expr₂ evaluates totrue if bothexpr₁ andexpr₂ evaluate totrue; otherwise, it evaluates tofalse. The first component,expr₁, is evaluated first. Thesecond component,expr₂, is not evaluated if the first componentevaluates tofalse. Hence, the expressionexpr₁&&expr₂ behavesexactly as

The expressionexpr₁||expr₂ evaluates totrue if one ofthe expressionsexpr₁ andexpr₂ evaluates totrue; otherwise, it evaluates tofalse. The first component,expr₁, is evaluated first. Thesecond component,expr₂, is not evaluated if the first componentevaluates totrue. Hence, the expressionexpr₁||expr₂ behavesexactly as

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

Loops

The expressionwhileexpr₁doexpr₂done repeatedlyevaluatesexpr₂ whileexpr₁ evaluates totrue. The loopconditionexpr₁ is evaluated and tested at the beginning of eachiteration. The wholewhile …done expression evaluates tothe unit value().

As a special case,whiletruedoexprdone is given apolymorphic type, allowing it to be used in place of any expression(for example as a branch of any pattern-matching).

The expressionforname=expr₁toexpr₂doexpr₃donefirst evaluates the expressionsexpr₁ andexpr₂ (the boundaries)into integer valuesn andp. Then, the loop bodyexpr₃ isrepeatedly evaluated in an environment wherename is successivelybound to the valuesn,n+1, …,p−1,p.The loop body is never evaluated ifn >p.

The expressionforname=expr₁downtoexpr₂doexpr₃doneevaluates similarly, except thatname is successively bound to the valuesn,n−1, …,p+1,p.The loop body is never evaluated ifn <p.

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

Exception handling

The expression

evaluates the expressionexpr and returns its value if theevaluation ofexpr does not raise any exception. If the evaluationofexpr raises an exception, the exception value is matched againstthe patternspattern₁ topattern_n. If the matching againstpattern_i succeeds, the associated expressionexpr_i is evaluated,and its value becomes the value of the wholetry expression. Theevaluation ofexpr_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 thetry expression isselected. If none of the patterns matches the value ofexpr, theexception value is raised again, thereby transparently “passingthrough” thetry construct.

7.4 Operations on data structures

Products

The expressionexpr₁, …,expr_n evaluates to then-tuple of the values of expressionsexpr₁ toexpr_n. Theevaluation order of the subexpressions is not specified.

Variants

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

The expressionconstr(expr₁, …,expr_n) evaluates to thevariant value whose constructor isconstr, and whose arguments arethe values ofexpr₁ …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 ofexpr₁ and whose tailis the value ofexpr₂. The expression[expr₁; …;expr_n] is equivalent toexpr₁:: …::expr_n::[], and therefore evaluates to the list whose elements are thevalues ofexpr₁ toexpr_n.

Polymorphic variants

The expression`tag-nameexpr evaluates to the polymorphic variantvalue whose tag istag-name, and whose argument is the value ofexpr.

Records

The expression{field₁ [=expr₁]; …;field_n [=expr_n]} evaluates to the record value{field₁ =v₁; …;field_n =v_n }wherev_i is the value ofexpr_i fori = 1,… ,n.A single identifierfield_k stands forfield_k=field_k,and a qualified identifiermodule-path.field_k stands formodule-path.field_k=field_k.The fieldsfield₁ tofield_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 whichexpr₁ toexpr_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 offield_k to be compatible withtypexpr_k.

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

The expressionexpr₁.field evaluatesexpr₁ to a recordvalue, and returns the value associated tofield in this recordvalue.

The expressionexpr₁.field<-expr₂ evaluatesexpr₁ to a recordvalue, which is then modified in-place by replacing the valueassociated tofield in this record by the value ofexpr₂. This operation is permitted only iffield has beendeclaredmutable in the definition of the record type. The wholeexpressionexpr₁.field<-expr₂ evaluates to the unit value().

Arrays

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

The expressionexpr₁.(expr₂) returns the value of elementnumberexpr₂ in the array denoted byexpr₁. The first elementhas number 0; the last element has numbern−1, wheren is thesize of the array. The exceptionInvalid_argument is raised if theaccess is out of bounds.

The expressionexpr₁.(expr₂)<-expr₃ modifies in-placethe array denoted byexpr₁, replacing element numberexpr₂ bythe value ofexpr₃. The exceptionInvalid_argument is raised ifthe access is out of bounds. The value of the whole expression is().

Strings

The expressionexpr₁.[expr₂] returns the value of characternumberexpr₂ in the string denoted byexpr₁. The first characterhas number 0; the last character has numbern−1, wheren is thelength of the string. The exceptionInvalid_argument is raised if theaccess is out of bounds.

The expressionexpr₁.[expr₂]<-expr₃ modifies in-placethe string denoted byexpr₁, replacing character numberexpr₂ bythe value ofexpr₃. The exceptionInvalid_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 theBytes.setfunction.

7.5 Operators

Symbols from the classinfix-symbol, as well as the keywords*,+,-,-.,=,!=,<,>,or,||,&,&&,:=,mod,land,lor,lxor,lsl,lsr,andasr can appear in infix position (between twoexpressions). Symbols from the classprefix-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 expressionprefix-symbolexpr isinterpreted as the application(prefix-symbol)expr. Similarly, the expressionexpr₁infix-symbolexpr₂ 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 moduleStdlib in chapter 28 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.6 Objects

Object creation

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

Whenclass-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 theobjectclass-bodyendconstruct is operationally equivalent to defining locally aclassclass-name=objectclass-bodyend —see sections11.9.2 and following for the syntax ofclass-body—and immediately creating a single object from it bynewclass-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 expressionexpr#method-name invokes the methodmethod-name of the object denoted byexpr.

Ifmethod-name is a polymorphic method, its type should be known atthe invocation site. This is true for instance ifexpr is the nameof a fresh object (letident =newclass-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 expressioninst-var-nameevaluates to the value of the given instance variable. The expressioninst-var-name<-expr assigns the value ofexpr to the instancevariableinst-var-name, which must be mutable. The whole expressioninst-var-name<-expr evaluates to().

Object duplication

An object can be duplicated using the library functionOo.copy(see moduleOo). 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 variablenameid stands forid=id. Other instance variables have the samevalue in the returned object as in self.

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 expressionexprto typetypexpr.The expression(expr:typexpr₁:>typexpr₂) coerces theexpressionexpr from typetypexpr₁ to typetypexpr₂.

The former operator will sometimes fail to coerce an expressionexprfrom a typetyp₁ to a typetyp₂even if typetyp₁ 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 ofexprandtyp are ground (i.e. do not contain type variables), theformer operator behaves as the latter one, taking the inferred type ofexpr astyp₁. In case of failure with the former operator,the latter one should be used.

It is only possible to coerce an expressionexpr from typetyp₁ to typetyp₂, if the type ofexpr is an instance oftyp₁ (like for a type annotation), andtyp₁ is a subtypeoftyp₂. The type of the coerced expression is aninstance oftyp₂. If the types contain variables,they may be instantiated by the subtyping algorithm, but this is onlydone after determining whethertyp₁ is a potential subtype oftyp₂. This means that typing may fail during this latterunification step, even if some instance oftyp₁ is a subtype ofsome instance oftyp₂.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,

is a supertype of

which may contain an ellipsis.. if everytyp_i is a supertype ofthe correspondingtyp′_i.

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

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

Polymorphic variant types

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

which may be a shrinkable type, is a subtype of

which may be an extensible type, if everytyp_i is a subtype oftyp′_i.

Variance

Other types do not introduce new subtyping, but they may propagate thesubtyping of their arguments. For instance,typ₁*typ₂ is asubtype oftyp′₁*typ′₂ whentyp₁ andtyp₂ arerespectively subtypes oftyp′₁ andtyp′₂.For function types, the relation is more subtle:typ₁->typ₂ is a subtype oftyp′₁ ->typ′₂iftyp₁ is a supertype oftyp′₁ andtyp₂ is asubtype oftyp′₂. For this reason, function types are covariant intheir second argument (like tuples), but contravariant in their firstargument. Mutable types, likearray orref 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 11.8.1),otherwise the default is nonvariant. This is also the case forconstrained arguments in type definitions.

7.8 Other

Assertion checking

OCaml supports theassert construct to check debugging assertions.The expressionassertexpr evaluates the expressionexpr andreturns() ifexpr evaluates totrue. If it evaluates tofalse the exceptionAssert_failure is raised with the source file name and thelocation ofexpr 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 thattheassert false “assertions” cannot be turned off by the-noassert option.

Lazy expressions

The expressionlazyexpr returns a valuev of typeLazy.t thatencapsulates the computation ofexpr. The argumentexpr is notevaluated at this point in the program. Instead, its evaluation willbe performed the first time the functionLazy.force is applied to the valuev, returning the actual value ofexpr. Subsequent applicationsofLazy.force tov do not evaluateexpr again. ApplicationsofLazy.force may be implicit through pattern matching (see 11.6).

Local modules

The expressionletmodulemodule-name=module-exprinexprlocally binds the module expressionmodule-expr to the identifiermodule-name during the evaluation of the expressionexpr.It then returns the value ofexpr. For example:

Local opens

The expressionsletopenmodule-pathinexpr andmodule-path.(expr) are strictly equivalent. Theseconstructions locally open the module referred to by the module pathmodule-path in the respective scope of the expressionexpr.

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]), andmodule-path.[|expr|] isequivalent tomodule-path.([|expr|]).