Objective Caml for Scientists

This is a web-friendly version of the first chapter of the book OCaml for Scientists.

Chapter 1: Introduction

A Brief History of OCaml

The Meta-Language (ML) was originally developed at Edinburgh University in the 1970's as a language designed to efficiently represent other languages. The language was pioneered by Robin Milner for the Logic of Computable Functions (LCF) theorem prover. The original ML, and its derivatives, were designed to stretch theoretical computer science to the limit, yielding remarkably robust and concise programming languages which can also be very efficient.

The Categorical Abstract Machine Language (CAML) was the acronym originally used to describe what is now known as the Caml family of languages. Gérard Huet designed and implemented Caml at Institut National de Recherche en Informatique et en Automatique (INRIA) in France, until 1994. Since then, development has continued as part of projet Cristal, now led by Xavier Leroy.

Objective Caml (OCaml) is the current flagship language of projet Cristal. The Cristal group have produced freely available tools for this language. Most notably, an interpreter which runs OCaml code in a virtual machine (VM) and two compilers, one which compiles OCaml to a machine independent byte-code which can then be executed by a byte-code interpreter and another which compiles OCaml directly to native code. At the time of writing, the native-code compiler is capable of producing code for Alpha, Sparc, x86, MIPS, HPPA, PowerPC, ARM, ia64 and x86-64 CPUs and the associated run-time environment has been ported to the Linux, Windows, MacOS X, BSD, Solaris, HPUX, IRIX and Tru64 operating systems.

Benefits of OCaml

Before delving into the syntax of the language itself, we shall list the main, advantageous features offered by the OCaml language:

Safety

OCaml programs are thoroughly checked at compile-time such that they are proven to be entirely safe to run, e.g. a compiled OCaml program cannot segfault.

Functional

Functions may be nested, passed as arguments to other functions and stored in data structures as values.

Strongly typed

The types of all values are checked during compilation to ensure that they are well defined and validly used.

Statically typed

Any typing errors in a program are picked up at compile-time by the compiler, instead of at run-time as in many other languages.

Type inference

The types of values are automatically inferred during compilation by the context in which they occur. Therefore, the types of variables and functions in OCaml code does not need to be specified explicitly, dramatically reducing source code size.

Polymorphism

In cases where any of several different types may be valid, any such type can be used. This greatly simplifies the writing of generic, reusable code.

Pattern matching

Values, particularly the contents of data structures, can be matched against arbitrarily-complicated patterns in order to determine the appropriate action.

Modules

Programs can be structured by grouping their data structures and related functions into modules.

Objects

Data structures and related functions can also be grouped into objects (object-oriented programming).

Separate compilation

Source files can be compiled separately into object files which are then linked together to form an executable. When linking, object files are automatically type checked and optimized before the final executable is created.

Running OCaml programs

OCaml provides three different ways to execute code. We shall now examine each of these three approaches, explaining how code can be executed using them and noting their relative advantages and disadvantages.

Top-level

The OCaml top-level interactively interprets OCaml code and is started by running the program ocaml:

$ ocaml
        Objective Caml version 3.08.0
 
#

OCaml code may then be entered at this # prompt, the end of which is delimited by ;;. For example, the following calculates 1+3=4:

# 1 + 3;;
- : int = 4
#

The top-level will also print the type of the result as well as its value (when the result has a value). For example, the following defines a variable called sqr which is a function:

# let sqr x = x *. x;;
val sqr : float -> float = <fun>
#

This response indicates that a function called sqr has been defined which accepts a float and returns a float. In general, the response of the top-level is either of the form:

- : type = value

or consisting of one or more descriptions of the form:

val name : type = value

where - indicates that a value has been returned but was not bound to a variable name, name is the name of a variable which has been bound, type is the type of the value and value is the value itself. Values are described explicitly for many data structures, such as 4 in the former case, but several other kinds of value are simply classified, such as <fun> to indicate that the value is a function in the latter case.

Programs entered into the top-level execute almost as quickly as byte-code compiled programs (which is often quite a bit slower than native-code compiled programs). However, the interactivity of the top-level makes testing the validity of code segments much easier.

In the remainder of this book, we shall write numerous code snippets in this style, as if they had been entered into the top-level.

Byte-code compilation

When stored in a plain text file with the suffix “.ml”, an OCaml program can be compiled to a machine independent byte-code using the ocamlc compiler. For example, for a file “test.ml” containing the code:

let _ = print_endline "Hello world!"

This file may be compiled at the Unix shell $ prompt into a byte-code executable called “test”:

$ ocamlc test.ml -o test

and then executed:

$ ./test
Hello world!

In this case, the result was to print the string “Hello world!” onto the screen. Byte-code compilation is an adequate way to execute OCaml programs which do not perform intensive computations. If the time taken to execute a program needs to be reduced then native-code compilation can be used instead.

Native-code compilation

The “test.ml” program could equivalently have been compiled to native code, creating a stand-alone, native-code executable called “test”, using:

$ ocamlopt test.ml -o test

The resulting executable runs in exactly the same way:

$ ./test
Hello world!

Programs compiled to native code, particularly in the context of numerically intensive programs, can be considerably faster to execute.

OCaml syntax

Before we consider the features offered by OCaml, a brief overview of the syntax of the language is instructive, so that we can provide actual code examples later. Other books give more systematic, thorough and formal introductions to the whole of the OCaml language.

Language overview

In this section we shall evolve the notions of values, types, variables, functions, simple containers (lists and arrays) and program flow control. These notions will then be used to introduce more advanced features in the later sections of this chapter.

When presented with a block of code, even the most seasoned and fluent programmer will not be able to infer the purpose of the code. Consequently, programs should contain additional descriptions written in plain English, known as comments. In OCaml, comments are enclosed between (* and *). They may be nested, i.e. (* (* ... *) *) is a valid comment. Comments are treated as whitespace, i.e. a(* ... *)b is understood to mean a b rather than ab.

Just as numbers can be defined to be members of sets such as integer ( in Z), real ( in R), complex ( in C) and so on, so values in programs are also defined to be members of sets. These sets are known as types.

Types

Fundamentally, languages provide basic types and, often, allow more sophisticated types to be defined in terms of the basic types. OCaml provides a number of built-in types: unit, int, float, char, string and bool. We shall examine these built-in types before discussing the compound tuple, record and variant types.

Only one value is of type unit and this value is written () and, therefore, conveys no information. This is used to implement functions which require no input or expressions which return no value. For example, a new line can be printed by calling the print_newline function as print_newline (). This function requires no input, so it accepts a single argument () of type unit, and returns the value () of type unit.

Integers are written -2, -1, 0, 1 and 2. Floating-point numbers are written -2., -1., -0.5, 0., 0.5, 1. and 2.. For example:

# 3;;
- : int = 3
# 5.;;
- : float = 5.

Arithmetic can be performed using the conventional +, -, *, /, mod binary infix operators over the integers. For example, the following expression is evaluated according to usual mathematical convention regarding operator precedence, with multiplication taking precedence over addition:

# 1 * 2 + 2 * 3;;
- : int = 8

The floating-point infix functions have slightly different names, suffixed by a full-stop: +., -., *., /. as well as ** (raise to the power). For example, the following calculates (1×2)+(2×3)=8:

# 1. *. 2. +. 2. *. 3.;;
- : float = 8.

The distinct names of the operators for different types arises as the most elegant solution to allowing the unambiguous inference of types in the presence of different forms of arithmetic. The definition of new operators is discussed later, in section . In order to perform arithmetic using mixed types, functions such as float_of_int can be used to convert between types.

Unlike other languages, OCaml is phenomenally pedantic about types. For example, the following fails because * denotes the multiplication of a pair of integers and cannot, therefore, be applied to a value of type float:

# 2 * 2.;;
This expression has type float but is here used with type int

Note that the OCaml top-level underlines the erroneous portion of the code.

Explicitly converting the value of type float to a value of type int using the built-in function int_of_float results in a valid expression which the top-level will execute:

# 2 * (int_of_float 2.);;
- : int = 4

In general, arithmetic is typically performed using a single number representation (e.g. either int or float) and conversions between representations are, therefore, comparatively rare.

Single characters (of type char) are written in single quotes, e.g. 'a', which may also be written using a 3-digit decimal code, e.g. '\097'.

Strings are written in double quotes, e.g. "Hello World!". Characters in a string of length n may be extracted using the notation s.[i] for i in {0… n−1}. For example, the fifth character in this string is “o”:

# "Hello world!".[4];;
- : char = 'o'

The character at index i in a string s may be set to c using the notation s.[i] <- c.

A pair of strings may be concatenated using the ^ operator:

# "Hello " ^ "world!";;
- : string = "Hello world!"

Booleans are either true or false. Booleans are created by the usual comparison functions =, <> (not equal to), <, >, <=, >=. These functions are polymorphic, meaning they may be applied to pairs of values of the same type for any type. The usual, short-circuit-evaluated logical comparisons && and || are also present. For example, the following expression tests that one is less than three and 2.5 is less than 2.7:

# 1 < 3 && 2.5 < 2.7;;
- : bool = true

Values may be assigned, or bound, to names. As OCaml is a functional language, these values may be expressions mapping values to values — functions. We shall now examine the binding of values and expressions to variable and function names.

Variables and functions

Variables and functions are both defined using the let construct and must be given names beginning with lower-case letters. For example, the following defines a variable called a to have the value 2:

# let a = 2;;
val a : int = 2

Note that the language automatically infers types. In this case, a has been inferred to be of type int.

Definitions using let can be defined locally using the syntax:

let name = expr1 in expr2

This evaluates expr1 and binds the result to the variable name before evaluating expr2. For example, the following evaluates a² in the context a=3, giving 9:

# let a = 3 in a * a;;
- : int = 9

Note that the value 3 bound to the variable a in this example was local to the expression a * a and, therefore, the global definition of a is still 2:

# a;;
- : int = 2

More recent definitions shadow previous definitions. For example, the following supersedes the definition a=2 with a=a× a in order to calculate 2×2×2×2=16:

# let a = 2 in
  let a = a * a in
  a * a;;
- : int = 16

As OCaml is a functional language, values can be functions and variables can be bound to them in exactly the same way as we have just seen. Specifically, function definitions append a list of arguments between the name of the function and the = in the let construct. For example, a function called sqr which accepts an argument called x and returns x * x may be defined as:

# let sqr x = x * x;;
val sqr : int -> int = <fun>

In this case, the use of the integer multiply * results in OCaml correctly inferring the type of sqr to be int -> int, i.e. the sqr function accepts a value of type int and returns a value of type int.

The function sqr may then be applied to an integer as:

# sqr 5;;
- : int = 25

Typically, more sophisticated computations require the use of more complicated types. We shall now examine the three simplest ways by which more complicated types may be constructed.

Tuples, records and variants

Tuples are the simplest form of compound types, containing a fixed number of values which may be of different types. The type of a tuple is written analogously to conventional set-theoretic style, using * to denote the cartesian product between the sets of possible values for each type. For example, a tuple of three integers, conventionally denoted by the triple (i,j,k) in Z×Z×Z, can be represented by values (i, j, k) of the type int * int * int. When written, tuple values are comma-separated and enclosed in parentheses. For example, the following tuple contains three different values of type int:

# (1, 2, 3);;
- : int * int * int = (1, 2, 3)

A tuple containing n values is described as an n-tuple, e.g. the tuple (1, 2, 3) is a 3-tuple.

Records are essentially tuples with named components, known as fields. Records and, in particular, the names of their fields must be defined using a type construct before they can be used. When written, record fields are written name : type where name is the name of the field (which must start with a lower-case letter) and type is the type of values in that field, and are semicolon-separated and enclosed in curly braces. For example, a record containing the x and y components of a 2D vector could be defined as:

# type vec2 = { x:float; y:float };;
type vec2 = { x:float; y:float }

A value of this type representing the zero vector can then be defined using:

# let zero = { x=0.; y=0. };;
val zero : vec2 = {x = 0.; y = 0.}

Note that the use of a record with fields x and y allowed OCaml to infer the type of zero as vec2.

Whereas the tuples are order-dependent, i.e. (1,2)≠(2,1), the named fields of a record may appear in any order, i.e. { x=1,y=2}≡{ y=2,x=1}. Thus, we could, equivalently, have provided the x and y fields in reverse order:

# let zero = { y=0.; x=0. };;
val zero : vec2 = {x = 0.; y = 0.}

The fields in this record can be extracted individually using the notation record.field where record is the name of the record and field is the name of the field within that record. For example, the x field in the variable zero is 0:

# zero.x;;
- : float = 0.

Also, a shorthand with notation exists for the creation of a new record from an existing record with a single field replaced. This is particularly useful when records contain many fields. For example, the record {x=1.; y=0.} may be obtained by replacing the field x in the variable zero with 1:

# let x_axis = { zero with x=1. };;
val x_axis : vec2 = {x = 1.; y = 0.}

Although OCaml is a functional language, OCaml does support imperative programming. Fundamentally, record fields can be marked as mutable, in which case their value may be changed. For example, the type of a mutable, two-dimensional vector called vec2 may be defined as:

# type vec2 = { mutable x:float; mutable y:float };;
type vec2 = { mutable x : float; mutable y : float; }

A value r of this type may be defined:

# let r = { x=1.; y=2. };;
val r : vec2 = {x = 1.; y = 2.}

The x-coordinate of the vector r may be altered in-place using an imperative style:

# r.x <- 3.;;
- : unit = ()

The side-effect of this expression has mutated the value of the variable r, the x-coordinate of which is now 3 instead of 1:

# r;;
- : vec = {x = 3.; y = 2.}

However, a record with a single, mutable field can often be useful. This data structure, called a reference, is already provided by the type ref. For example, the following defines a variable named a which is a reference to the integer 2:

# let a = ref 2;;
val a : int ref = {contents = 2}

The type of a is then int ref. The value referred to by a may be obtained using !a:

# !a;;
- : int = 2

The value of a may be set using :=:

# a := 3;
- : unit = ()
# a;;
- : int ref = {contents = 3}

In the case of references to integers, two additional functions are provided, incr and decr, which increment and decrement references to integers, respectively:

# incr a;;
- : unit = ()
# a;;
val a : int ref = {contents = 4}

The types of values stored in tuples and records are defined at compile-time. OCaml completely verifies the correct use of these types at compile-time. However, this is too restrictive in many circumstances. These requirements can be slightly relaxed by allowing a type to be defined which can acquire one of several possible types at run-time. These are known as variant types. OCaml still verifies the correct use of variant types as far as is theoretically possible.

Variant types are defined using the type construct with the possible constituent types referred to by constructors (the names of which must begin with upper-case letters) separated by the | character. For example, a variant type named button which may adopt the values On or Off may be written:

# type button = On | Off;;
type button = On | Off

The constructors On and Off may then be used as values of type button:

# On;;
- : button = On
# Off;;
- : button = Off

In this case, the constructors On and Off convey no information in themselves (i.e. like the type unit, On and Off do not carry data) but the choice of On or Off does convey information. Note that both expressions were correctly inferred to have results of type button.

More usefully, constructors may take arguments, allowing them to convey information by carrying data. The arguments are defined using of and are written in the same form as that of a tuple. For example, a replacement button type which provides an On constructor accepting two arguments may be written:

# type button = On of int * string | Off;;
type button = On of int * string | Off

The On constructor may then be used to create values of type button by appending the argument in the style of a tuple:

# On (1, "mine");;
- : button = On (1, "mine")
# On (2, "hers");;
- : button = On (2, "hers")
# Off;;
- : button = Off

Types can also be defined recursively, which is very useful when defining more sophisticated data structures, such as trees. For example, a binary tree contains either zero or two binary trees and can be defined as:

# type binary_tree = Leaf | Node of binary_tree * binary_tree;;
type binary_tree = Leaf | Node of binary_tree * binary_tree

A value of type binary_tree may be written in terms of these constructors:

# Node (Node (Leaf, Leaf), Leaf);;
- : binary_tree = Node (Node (Leaf, Leaf), Leaf) 

Of course, we could also place data in the nodes to make a more useful data structure. This line of thinking will be pursued in chapter . In the mean time, let us consider two special data structures which have notations built into the language.

Lists and arrays

Lists are written [a; b; c] and arrays are written [|a; b; c|]. As we shall see in chapter , lists and arrays have different merits.

The types of lists and arrays of integers, for example, are written int list and int array, respectively:

# [1; 2; 3];;
- : int list = [1; 2; 3]
# [|1; 2; 3|];;
- : int array = [|1; 2; 3|]

In the case of lists, the infix cons operator :: provides a simple way to prepend an element to the front of a list. For example, prepending 1 onto the list [2; 3] gives the list [1; 2; 3]:

# 1 :: [2; 3];;
- : int list = [1; 2; 3]

In the case of arrays, the notation array.(i) may be used to extract the i+1^th element. For example, [|1; 2; 3|].(1) gives the second element 2:

# [|1; 2; 3|].(1);;
- : int = 2

Also, a short-hand notation can be used to represent lists or arrays of tuples by omitting the parentheses. For example, [(a, b); (c, d)] may be written [a, b; c, d]:

# [1, 2; 3, 4];;
- : (int * int) list = [(1, 2); (3, 4)]
# [|1, 2; 3, 4|];;
- : (int * int) array = [|(1, 2); (3, 4)|]

The use and properties of lists, arrays and several other data structures will be discussed in chapter . In the mean time, we shall examine programming constructs which allow more interesting computations to be performed.

If

Like many other programming languages, OCaml provides an if construct which allows a boolean “predicate” expression to determine which of two expressions is evaluated and returned, as well as a special if construct which optionally evaluates an expression of type unit:

if expr1 then expr2
if expr1 then expr2 else expr3

In both cases, expr1 must evaluate to a value of type bool. In the former case, expr2 is expected to evaluate to the value of type unit. In the latter case, both expr2 and expr3 must evaluate to values of the same type.

The former evaluates the boolean expression expr1 and, only if the result is true, evaluates the expression expr2. Thus, the former is equivalent to:

if expr1 then expr2 else ()

The latter similarly evaluates expr1 but returning the result of either expr2, if expr1 evaluated to true, or of expr3 otherwise.

For example, the following function prints “Less than three” if the given argument is less than three:

# let f x = if x < 3 then print_endline "Less than three";;
val f : int -> unit = <fun>
# f 1;;
Less than three
- : unit = ()
# f 5;;
- : unit = ()

The following function returns the string “Less” if the argument is less than 3 and “Greater” otherwise:

# let f x = if x < 3 then "Less" else "Greater";;
val f : int -> string = <fun>
# f 1;;
- : string = "Less"
# f 5;;
- : string = "Greater"

The parts of the language we have covered can already be used to write some interesting programs. However, attention should be paid to the way in which programs are constructed from these parts.

Program composition

As we have seen, program segments may be written in the top-level which replies by reciting the automatically inferred types and executing expressions. However, the ;; used to force the top-level into producing output is not necessary in programs compiled with ocamlc and ocamlopt. For example, the two previous functions can be defined simultaneously, with only a single ;; at the end:

# let f1 x = if x < 3 then print_endline "Less than three"
  let f2 x = if x < 3 then "Less" else "Greater";;
val f1 : int -> unit = <fun>
val f2 : int -> string = <fun> 

Note that OCaml has determined that this input corresponds to two separate function definitions. In fact, when written for the ocamlc or ocamlopt compilers, programs can be written entirely without ;;, such as:

let f1 x = if x < 3 then print_endline "Less than three"
let f2 x = if x < 3 then "Less" else "Greater"

As we have seen, expressions which act by way of a side-effect (such as printing) produce the value () of type unit. Many situations require a sequence of such expressions to be evaluated. Expressions of type unit may be concatenated into a compound expression by using the ; separator. For example, a function to print “A”, “B” and then “C” on three separate lines could be written:

# let f () =
    print_endline "A";
    print_endline "B";
    print_endline "C";;
val f : unit -> unit = <fun>

Note that there is no final ;, only the delimiting ;;, so the value () of type unit produced by the final call to print_endline is returned by our f function.

More about functions

Functions can also be defined anonymously, known as λ-abstraction in computer science. For example, the following defines a function f(x)=x× x which has a type representing f:Z→Z:

# fun x -> x * x;;
- : int -> int = <fun>

This is an anonymous equivalent to the sqr function defined earlier. The type of this expression is also inferred to be int -> int. This anonymous function can be called as if it were the name of a conventional function. For example, applying the function f to the value 2 gives 2×2=4:

# (fun x -> x * x) 2;;
val : int = 4

Consequently, we could have defined sqr equivalently as:

# let sqr = fun x -> x * x;;
val sqr : int -> int = <fun>

Once defined, this version of the sqr function is indistinguishable from the original.

The let … in construct allows definitions to be nested, including function definitions. For example, the following function ipow3 raises a given int to the power three using a sqr function nested within the body of the ipow3 function:

# let ipow3 x =
    let sqr x = x * x in
    x * sqr x;;
val ipow3 : int -> int = <fun>

Note that the function application sqr x takes precedence over the multiplication.

The let construct may also be used to define the elements of a tuple simultaneously. For example, the following defines two variables, a and b, simultaneously:

# let (a, b) = (3, 4);;
val a : int = 3
val b : int = 4

This is particularly useful when factoring code. For example, the following definition of the ipow4 function contains an implementation of the sqr function which is identical to that in our previous definition of the ipow3 function:

# let ipow4 x =
    let sqr x = x * x in
    (sqr x) * (sqr x);;
val ipow4 : int -> int = <fun>

Just as common subexpressions in a mathematical expression can be factored, so the ipow3 and ipow4 functions can be factored by sharing a common sqr function and returning the ipow3 and ipow4 functions simultaneously in a 2-tuple:

# let (ipow3, ipow4) =
    let sqr x = x * x in
    ((fun x -> x * (sqr x)), fun x -> (sqr x) * (sqr x));;
val ipow3 : int -> int = <fun>
val ipow4 : int -> int = <fun>

Factoring code is an important way to keep programs manageable. In particular, programs can be factored much more aggressively in the presence of higher-order functions — something which can be done in OCaml but not Java, C++ or Fortran. We shall discuss such factoring of OCaml programs as a means of code structuring in chapter . In the mean time, we shall examine functions which perform computations by applying themselves.

As we have already seen, variable names in variable and function definitions refer to their previously defined values. This default behaviour can be overridden using the rec keyword, which allows a variable definition to refer to itself. This is necessary to define a recursive function. For example, the following implementation of the ipow function, which computes n^m for n,m≥0 in Z, calls itself recursively with smaller m to build up the result until the base-case n^m=1 for m=0 is reached:

# let rec ipow n m = if m = 0 then 1 else n * ipow n (m - 1);;
val ipow : int -> int -> int = <fun>

For example, 2¹⁶=65,536:

# ipow 2 16;;
- : int = 65536

All of the programming constructs we have just introduced may be structured into modules.

Modules

In OCaml, modules are the most commonly used means to encapsulate related definitions. For example, many function definitions pertaining to lists are encapsulated in the List module. Visible definitions in modules may be referred to by the notation module.name where module is the name of the module and name is the name of the type or variable definition. For example, the List module contains a function length which returns the number of elements in the given list:

# List.length ["one"; "two"; "three"];;
- : int = 3

The Pervasives module contains many common definitions, such as sqrt, and is automatically opened before a program starts so these definitions are available immediately.

The OCaml module system and program structuring in general are examined in chapter . We shall now examine some of the more advanced features of OCaml in more detail.

Pattern matching

As a program is executed, it is quite often necessary to choose the future course of action based upon the value of a previously computed result. As we have already seen, a two-way choice can be implemented using the if construct. However, the ability to choose from several different possible actions is often desirable. Although such cases can be reduced to a series of if tests, languages typically provide a more general construct to compare a result with several different possibilities more succinctly, more clearly and sometimes more efficiently than manually nested ifs. In Fortran, this is the SELECT CASE construct. In C and C++, it is the switch case construct.

Unlike conventional languages, OCaml allows the value of a previous result to be compared against various patterns - pattern matching. As we shall see, this approach is considerably more powerful than the conventional approaches.

The most common pattern matching construct in OCaml is in the match … with … expression:

match expr with
  pattern1 -> expr1
| pattern2 -> expr2
| pattern3 -> expr3
| …

This evaluates expr and compares the resulting value firstly with pattern1 then with pattern2 and so on, until a pattern is found which matches the value of expr, in which case the corresponding expression (e.g. expr2) is evaluated and returned. A pattern is an expression composed of constants and variable names. When a pattern matches an argument, the variables are bound to values of the corresponding expressions.

Patterns may contain arbitrary data structures (tuples, records, variant types, lists and arrays) and, in particular, the cons operator :: may be used in a pattern to decapitate a list. Also, the pattern _ matches any value without assigning a name to it. This is useful for clarifying that part of a pattern is not referred to in the corresponding expression.

For example, the following function compares its argument with several possible patterns of type int, returning the expression of type string corresponding to the pattern which matches:

# let f i = match i with
    0 -> "Zero"
  | 3 -> "Three"
  | _ -> "Neither zero nor three";;

Applying this function to some expressions of type int demonstrates the functionality of the match construct:

# f 0;;
- : string = "Zero"
# f 1;;
- : string = "Neither zero nor three"
# f (1 + 2);;
- : string = "Three" 

As pattern matching is such a fundamental concept in OCaml programming, we shall provide several more examples using pattern matching in this section.

A function is_empty_list which examines a given list and returns true if the list is empty and false if the list contains any elements, may be written without pattern matching by simply testing equality with the empty list:

# let is_empty_list l =
    l = [];;
val is_empty_list : 'a list -> bool = <fun>

Using pattern matching, this example may be written using the match … with … construct as:

# let is_empty_list l = match l with
    [] -> true
  | _ -> false;;
val is_empty_list : 'a list -> bool = <fun>

Note the use of the anonymous _ pattern to match any value, in this case accounting for all other possibilities.

The is_empty_list function can also be written using the function … construct, used to create one-argument λ-functions which are pattern matched over their argument:

# let is_empty_list = function
    [] -> true
  | _ -> false;;
val is_empty_list : 'a list -> bool = <fun>

In general, functions which pattern match over their last argument may be rewritten more succinctly using function. Let us now consider some additional sophistication supported by OCaml's pattern matching.

Guarded patterns

Patterns can also have arbitrary tests associated with them, written using the when construct. Such patterns are referred to as guarded patterns and are only allowed to match when the associated boolean expression evaluates to true. For example, the following function evaluates to true only for lists which contain three integers, i, j and k, satisfying the equality i−j−k=0:

# let f = function
    [i; j; k] when i - j - k = 0 -> true
  | _ -> false;;
val f : int list -> bool = <fun>
# f [2; 3];;
- : bool = false
# f [5; 2; 3];;
- : bool = true
# f [1; 2; 3];;
- : bool = false

Subsequent patterns sharing the same variable bindings and corresponding expression may be written in the short-hand notation:

match … with
  pattern1 | pattern2 | … -> …
| …

For example, the following function returns true if the given integer is in the set {−1,0,1} and false otherwise:

# let is_sign = function
    -1 | 0 | 1 -> true
  | _ -> false;;
val is_sign : int -> bool = <fun>

The sophistication provided by pattern matching may be misused. Fortunately, the OCaml compilers go to great lengths to enforce correct use, even brashly criticising the programmers style when appropriate.

Erroneous patterns

Sequences of patterns which match to the same corresponding expression are required to share the same set of variable bindings. For example, although the following function makes sense to a human, the OCaml compilers object to the patterns (a, 0.) and (0., b) binding different sets of variables ({ a} and { b}, respectively):

# let product a b = match (a, b) with
    (a, 0.) | (0., b) -> 0.
  | (a, b) -> a *. b;;
Variable a must occur on both sides of this | pattern

In this case, this function could be corrected by using the anonymous _ pattern as neither a nor b is used in the first case:

# let product a b = match (a, b) with
    (_, 0.) | (0., _) -> 0.
  | (a, b) -> a *. b;;
val product : float -> float -> float = <fun> 

This actually conveys useful information about the code. Specifically, that the values matched by _ are not used in the corresponding expression.

OCaml uses type information to determine the possible values of expression being matched over. If the set of pattern matches fails to cover all of the possible values of the input then, at compile-time, the compiler emits:

Warning: this pattern-matching is not exhaustive

followed by examples of values which could not be matched. If a program containing such pattern matches is executed and no matching pattern is found at run-time then the Match_failure exception is raised. Exceptions will be discussed in section .

For example, in the context of the variant type:

# type int_option = None | Some of int;;
type int_option = None | Some of int

The OCaml compiler will warn of a function matching only Some … values and neglecting the None value:

# let extract = function Some i -> i;;
Warning: this pattern-matching is not exhaustive.
Here is an example of a value that is not matched:
None
val extract : int_option -> int = <fun>

This extract function then works as expected on Some … values:

# extract (Some 3);;
- : int = 3

but causes a Match_failure exception to be raised at run-time if a None value is given, as none of the patterns in the pattern match of the extract function match this value:

# extract None;;
Exception: Match_failure ("", 5, -40).

As some approaches to pattern matching lead to more robust programs, some notions of good and bad programming styles arise in the context of pattern matching.

Good style

The compiler cannot prove that any given pattern match covers all eventualities in the general case. Thus, some style guidelines may be productively adhered to when writing pattern matches, to aid the compiler in its proofs:

• Guarded patterns should be used only when necessary. In particular, in any given pattern matching, at least one pattern should be unguarded.
• Unless all eventualities are clearly covered (such as [] and h::t which, between them, match any list) the last pattern should be general.

As proof generation cannot be automated in general, the OCaml compilers do not try to prove that a sequence of guarded patterns will match all possible inputs. Instead, the programmer is expected to adhere to a good programming style, making the breadth of the final match explicit by removing the guard. For example, the OCaml compilers do not prove that the following pattern match covers all possibilities:

# let sign = function
    i when i < 0. -> -1
  | 0. -> 0
  | i when i > 0. -> 1;;
Warning: this pattern-matching is not exhaustive.
Here is an example of a value that is not matched:
1.
(However, some guarded clause may match this value.) 
val sign : float -> int = <fun>

In this case, the function should have been written without the guard on the last pattern:

# let sign = function
    i when i < 0. -> -1
  | 0. -> 0
  | _ -> 1;;
val sign : float -> int = <fun>

Also, the OCaml compilers will try to determine any patterns which can never be matched. If such a pattern is found, the compiler will emit a warning. For example, in this case the first match accounts for all possible input values and, therefore, the second match will never be used:

# let product a b = match (a, b) with
    (a, b) -> a *. b
  | (_, 0.) | (0., _) -> 0.;;
Warning: this match case is unused.
val product : float -> float -> float = <fun> 

When matching over the constructors of a type, all eventualities should be caught explicitly, i.e. the final pattern should not be made completely general. For example, in the context of a type which can represent different number representations:

# type number = Integer of int | Real of float;;
type number = Integer of int | Real of float

A function to test for equality with zero could be written in the following, poor style:

# let bad_is_zero = function
    Integer 0 -> true
  | Real 0. -> true
  | _ -> false;;
val bad_is_zero : number -> bool = <fun>

When applied to various values of type number, this function correctly acts a predicate to test for equality with zero:

# bad_is_zero (Integer (-1));;
- : bool = false
# bad_is_zero (Integer 0);;
- : bool = true
# bad_is_zero (Real 0.);;
- : bool = true
# bad_is_zero (Real 2.6);;
- : bool = false

Although the bad_is_zero function works in this case, a better style would be to extract the numerical values from the constructors and test their equality with zero, avoiding the final catch-all case in the pattern match:

# let good_is_zero = function
    Integer i -> i = 0
  | Real x -> x = 0.;;
val good_is_zero : number -> bool = <fun>

Not only is the latter style more concise but, more importantly, this style is more robust. For example, if whilst developing our program, we were to supplement the definition of our number type with a new representation, say of the complex numbers z=x+iy in C:

# type number = Integer of int | Real of float | Complex of float * float;;
type number = Integer of int | Real of float | Complex of float * float

the bad_is_zero function, which is written in the poor style, would compile without warning to give incorrect functionality:

# let bad_is_zero = function
    Integer 0 -> true
  | Real 0. -> true
  | _ -> false;;
val bad_is_zero : number -> bool = <fun>

Specifically, this function treats all values which are not zero-integers and zero-reals as being non-zero. Thus, zero-complex z=0+0i is incorrectly deemed to be non-zero:

# bad_is_zero (Complex (0., 0.));;
- : bool = false

In contrast, the good_is_zero function, which was written using the good style, would allow the compiler to spot that part of the number type was no longer being accounted for in the pattern match:

# let good_is_zero = function
    Integer i -> i = 0
  | Real x -> x = 0.;;
Warning: this pattern-matching is not exhaustive.
Here is an example of a value that is not matched:
Complex (_, _)
val good_is_zero : number -> bool = <fun>

The programmer could then supplement this function with a case for complex numbers:

# let good_is_zero = function
    Integer i -> i = 0
  | Real x -> x = 0.
  | Complex (x, y) -> x = 0. && y = 0.;;
val good_is_zero : number -> bool = <fun> 

The resulting function would then provide the correct functionality:

# good_is_zero (Complex (0., 0.));;
- : bool = true

Clearly, the ability have such safety checks performed at compile-time can be very valuable. This is another important aspect of safety provided by the OCaml language, which results in considerably more robust programs.

Due to the ubiquity of pattern matching in OCaml programs, the number and structure of pattern matches can be non-trivial. In particular, patterns may be nested and may be performed in parallel.

Nested patterns

In some cases, nested pattern matches may be desirable. Inner pattern matches may be bundled either into parentheses (…) or, equivalently, into a begin … end construct. When split across multiple lines, the begin … end construct is the conventional choice. For example, the following function tests equality between two values of type number:

# let number_equal a b = match a with
    Integer i ->
      begin
        match b with
          Integer j when i = j -> true
        | Complex (x, 0.) | Real x when x = float_of_int i -> true
        | Integer _ | Real _ | Complex _ -> false
      end
  | Real x | Complex (x, 0.) ->
      begin
        match b with
          Integer i when x = float_of_int i -> true
        | Complex (y, 0.) | Real y when x = y -> true
        | Integer _ | Real _ | Complex _ -> false
      end
  | Complex (x1, y1) ->
      begin
        match b with
          Complex (x2, y2) when x1 = x2 && y1 = y2 -> true
        | Integer _ | Real _ | Complex _ -> false
      end;;
val number_equal : number -> number -> bool = <fun>

In many cases, nested patterns may be written more succinctly and, in fact, more efficient, when presented as a single pattern match which matches different values simultaneously.

Parallel pattern matching

In many cases, nested pattern matches may be combined into a single pattern match. This functionality is often obtained by combining variables into a tuple which is then matched over. This is known as parallel pattern matching. For example, the previous function could have been written:

# let number_equal a b = match (a, b) with
    (Integer i, Integer j) -> i = j
  | (Integer i, (Real x | Complex (x, 0.)))
  | ((Real x | Complex (x, 0.)), Integer i) -> x = float_of_int i
  | ((Real x1 | Complex (x1, 0.)), (Complex (x2, 0.) | Real x2)) -> x1 = x2
  | ((Integer _ | Real _), Complex _)
  | (Complex _, (Integer _ | Real _)) -> false
  | (Complex (x1, y1), Complex (x2, y2)) -> x1 = x2 && y1 = y2;;
val number_equal : number -> number -> bool = <fun>

As a core feature of the OCaml language, pattern matching will be used extensively in the remainder of this book, particularly when dissecting data structures in chapter . One remaining form of pattern matching in OCaml programs appears in the handling of exceptions.

Exceptions

In many programming languages, program execution can be interrupted by the raising of an exception. This is a useful facility, typically used to handle problems such as failing to open a file or an unexpected flow of execution (e.g. due to a program being given invalid input) but exceptions are also useful as an efficient means to escape a computation, as we shall see in section .

Like a variant constructor in OCaml, the name of an exception must begin with a capital letter and an exception may or may not carry an associated value. Before an exception can be used, it must declared. An exception which does not carry associated data may be declared as:

exception Name

An exception which carries associated data of type type may be declared:

exception Name of type

Exceptions are raised using the raise construct. For example, the following raises a built-in exception called Failure which carries a string:

# raise (Failure "My problem");;
Exception: Failure "My problem".

Exceptions may also be caught using the syntax:

try
  expr
with
  pattern1 <