Chapter 4 Labels and variants

(Chapter written by Jacques Garrigue)

This chapter gives an overview of the new features inOCaml 3: labels, and polymorphic variants.

4.1 Labels

If you have a look at modules ending in Labels in the standardlibrary, you will see that function types have annotations you did nothave in the functions you defined yourself.

 ListLabels.map;;
- : f:('a -> 'b) -> 'a list -> 'b list = <fun>

 StringLabels.sub;;
- : string -> pos:int -> len:int -> string = <fun>

Such annotations of the form name: are called labels. They aremeant to document the code, allow more checking, and give moreflexibility to function application.You can give such names to arguments in your programs, by prefixing themwith a tilde ~.

 let f ~x ~y = x - y;;
val f : x:int -> y:int -> int = <fun>

 let x = 3 and y = 2 in f ~x ~y;;
- : int = 1

When you want to use distinct names for the variable and the labelappearing in the type, you can use a naming label of the form~name:. This also applies when the argument is not a variable.

 let f ~x:x1 ~y:y1 = x1 - y1;;
val f : x:int -> y:int -> int = <fun>

 f ~x:3 ~y:2;;
- : int = 1

Labels obey the same rules as other identifiers in OCaml, that is youcannot use a reserved keyword (like in or to) as label.

Formal parameters and arguments are matched according to theirrespective labels¹, the absence of labelbeing interpreted as the empty label.This allows commuting arguments in applications. One can alsopartially apply a function on any argument, creating a new function ofthe remaining parameters.

 let f ~x ~y = x - y;;
val f : x:int -> y:int -> int = <fun>

 f ~y:2 ~x:3;;
- : int = 1

 ListLabels.fold_left;;
- : f:('a -> 'b -> 'a) -> init:'a -> 'b list -> 'a = <fun>

 ListLabels.fold_left [1;2;3] ~init:0 ~f:( + );;
- : int = 6

 ListLabels.fold_left ~init:0;;
- : f:(int -> 'a -> int) -> 'a list -> int = <fun>

If several arguments of a function bear the same label (or no label),they will not commute among themselves, and order matters. But theycan still commute with other arguments.

 let hline ~x:x1 ~x:x2 ~y = (x1, x2, y);;
val hline : x:'a -> x:'b -> y:'c -> 'a * 'b * 'c = <fun>

 hline ~x:3 ~y:2 ~x:5;;
- : int * int * int = (3, 5, 2)

As an exception to the above parameter matching rules, if anapplication is total (omitting all optional arguments), labels may beomitted.In practice, many applications are total, so that labels can often beomitted.

 f 3 2;;
- : int = 1

 ListLabels.map succ [1;2;3];;
- : int list = [2; 3; 4]

But beware that functions like ListLabels.fold_left whose resulttype is a type variable will never be considered as totally applied.

 ListLabels.fold_left ( + ) 0 [1;2;3];;
Error: This expression has type int -> int -> int
       but an expression was expected of type 'a list

When a function is passed as an argument to a higher-order function,labels must match in both types. Neither adding nor removing labelsare allowed.

 let h g = g ~x:3 ~y:2;;
val h : (x:int -> y:int -> 'a) -> 'a = <fun>

 h f;;
- : int = 1

 h ( + ) ;;
Error: This expression has type int -> int -> int
       but an expression was expected of type x:int -> y:int -> 'a

Note that when you don’t need an argument, you can still use a wildcardpattern, but you must prefix it with the label.

 h (fun ~x:_ ~y -> y+1);;
- : int = 3

4.1.1 Optional arguments

An interesting feature of labeled arguments is that they can be madeoptional. For optional parameters, the question mark ? replaces thetilde ~ of non-optional ones, and the label is also prefixed by ?in the function type.Default values may be given for such optional parameters.

 let bump ?(step = 1) x = x + step;;
val bump : ?step:int -> int -> int = <fun>

 bump 2;;
- : int = 3

 bump ~step:3 2;;
- : int = 5

A function taking some optional arguments must also take at least onenon-optional argument. The criterion for deciding whether an optionalargument has been omitted is the non-labeled application of anargument appearing after this optional argument in the function type.Note that if that argument is labeled, you will only be able toeliminate optional arguments by totally applying the function,omitting all optional arguments and omitting all labels for allremaining arguments.

 let test ?(x = 0) ?(y = 0) () ?(z = 0) () = (x, y, z);;
val test : ?x:int -> ?y:int -> unit -> ?z:int -> unit -> int * int * int =
  <fun>

 test ();;
- : ?z:int -> unit -> int * int * int = <fun>

 test ~x:2 () ~z:3 ();;
- : int * int * int = (2, 0, 3)

Optional parameters may also commute with non-optional or unlabeledones, as long as they are applied simultaneously. By nature, optionalarguments do not commute with unlabeled arguments appliedindependently.

 test ~y:2 ~x:3 () ();;
- : int * int * int = (3, 2, 0)

 test () () ~z:1 ~y:2 ~x:3;;
- : int * int * int = (3, 2, 1)

 (test () ()) ~z:1 ;;
Error: This expression has type int * int * int
       This is not a function; it cannot be applied.

Here (test () ()) is already (0,0,0) and cannot be furtherapplied.

Optional arguments are actually implemented as option types. Ifyou do not give a default value, you have access to their internalrepresentation, type 'a option = None | Some of 'a. You can thenprovide different behaviors when an argument is present or not.

 let bump ?step x =
    match step with
    | None -> x * 2
    | Some y -> x + y
  ;;
val bump : ?step:int -> int -> int = <fun>

It may also be useful to relay an optional argument from a functioncall to another. This can be done by prefixing the applied argumentwith ?. This question mark disables the wrapping of optionalargument in an option type.

 let test2 ?x ?y () = test ?x ?y () ();;
val test2 : ?x:int -> ?y:int -> unit -> int * int * int = <fun>

 test2 ?x:None;;
- : ?y:int -> unit -> int * int * int = <fun>

4.1.2 Labels and type inference

While they provide an increased comfort for writing functionapplications, labels and optional arguments have the pitfall that theycannot be inferred as completely as the rest of the language.

You can see it in the following two examples.

 let h' g = g ~y:2 ~x:3;;
val h' : (y:int -> x:int -> 'a) -> 'a = <fun>

 h' f ;;
Error: This expression has type x:int -> y:int -> int
       but an expression was expected of type y:int -> x:int -> 'a

 let bump_it bump x =
    bump ~step:2 x;;
val bump_it : (step:int -> 'a -> 'b) -> 'a -> 'b = <fun>

 bump_it bump 1 ;;
Error: This expression has type ?step:int -> int -> int
       but an expression was expected of type step:int -> 'a -> 'b

The first case is simple: g is passed ~y and then ~x, but fexpects ~x and then ~y. This is correctly handled if we know thetype of g to be x:int -> y:int -> int in advance, but otherwisethis causes the above type clash. The simplest workaround is to applyformal parameters in a standard order.

The second example is more subtle: while we intended the argumentbump to be of type ?step:int -> int -> int, it is inferred asstep:int -> int -> 'a.These two types being incompatible (internally normal and optionalarguments are different), a type error occurs when applying bump_itto the real bump.

We will not try here to explain in detail how type inference works.One must just understand that there is not enough information in theabove program to deduce the correct type of g or bump. That is,there is no way to know whether an argument is optional or not, orwhich is the correct order, by looking only at how a function isapplied. The strategy used by the compiler is to assume that there areno optional arguments, and that applications are done in the rightorder.

The right way to solve this problem for optional parameters is to adda type annotation to the argument bump.

 let bump_it (bump : ?step:int -> int -> int) x =
    bump ~step:2 x;;
val bump_it : (?step:int -> int -> int) -> int -> int = <fun>

 bump_it bump 1;;
- : int = 3

In practice, such problems appear mostly when using objects whosemethods have optional arguments, so that writing the type of objectarguments is often a good idea.

Normally the compiler generates a type error if you attempt to pass toa function a parameter whose type is different from the expected one.However, in the specific case where the expected type is a non-labeledfunction type, and the argument is a function expecting optionalparameters, the compiler will attempt to transform the argument tohave it match the expected type, by passing None for all optionalparameters.

 let twice f (x : int) = f(f x);;
val twice : (int -> int) -> int -> int = <fun>

 twice bump 2;;
- : int = 8

This transformation is coherent with the intended semantics,including side-effects. That is, if the application of optionalparameters shall produce side-effects, these are delayed until thereceived function is really applied to an argument.

4.1.3 Suggestions for labeling

Like for names, choosing labels for functions is not an easy task. Agood labeling is a labeling which

• makes programs more readable,
• is easy to remember,
• when possible, allows useful partial applications. We explain here the rules we applied when labeling OCamllibraries.

To speak in an “object-oriented” way, one can consider that eachfunction has a main argument, its object, and other argumentsrelated with its action, the parameters. To permit thecombination of functions through functionals in commuting label mode, theobject will not be labeled. Its role is clear from the functionitself. The parameters are labeled with names reminding oftheir nature or their role. The best labels combine nature androle. When this is not possible the role is to be preferred, since thenature willoften be given by the type itself. Obscure abbreviations should beavoided.

ListLabels.map : f:('a -> 'b) -> 'a list -> 'b list
UnixLabels.write : file_descr -> buf:bytes -> pos:int -> len:int -> unit

When there are several objects of same nature and role, they are allleft unlabeled.

ListLabels.iter2 : f:('a -> 'b -> 'c) -> 'a list -> 'b list -> unit

When there is no preferable object, all arguments are labeled.

BytesLabels.blit :
  src:bytes -> src_pos:int -> dst:bytes -> dst_pos:int -> len:int -> unit

However, when there is only one argument, it is often left unlabeled.

BytesLabels.create : int -> bytes

This principle also applies to functions of several arguments whosereturn type is a type variable, as long as the role of each argumentis not ambiguous. Labeling such functions may lead to awkward errormessages when one attempts to omit labels in an application, as wehave seen with ListLabels.fold_left.

Here are some of the label names you will find throughout thelibraries.

All these are only suggestions, but keep in mind that thechoice of labels is essential for readability. Bizarre choices willmake the program harder to maintain.

In the ideal, the right function name with right labels should beenough to understand the function’s meaning. Since one can get thisinformation with OCamlBrowser or the ocaml toplevel, the documentationis only used when a more detailed specification is needed.

4.2 Polymorphic variants

Variants as presented in section 1.4 are apowerful tool to build data structures and algorithms. However theysometimes lack flexibility when used in modular programming. This isdue to the fact that every constructor is assigned to a unique typewhen defined and used. Even if the same name appears in the definitionof multiple types, the constructor itself belongs to only one type.Therefore, one cannot decide that a given constructor belongs tomultiple types, or consider a value of some type to belong to someother type with more constructors.

With polymorphic variants, this original assumption is removed. Thatis, a variant tag does not belong to any type in particular, the typesystem will just check that it is an admissible value according to itsuse. You need not define a type before using a variant tag. A varianttype will be inferred independently for each of its uses.

Basic use

In programs, polymorphic variants work like usual ones. You just haveto prefix their names with a backquote character `.

 [`On; `Off];;
- : [> `Off | `On ] list = [`On; `Off]

 `Number 1;;
- : [> `Number of int ] = `Number 1

 let f = function `On -> 1 | `Off -> 0 | `Number n -> n;;
val f : [< `Number of int | `Off | `On ] -> int = <fun>

 List.map f [`On; `Off];;
- : int list = [1; 0]

[>Off|On] list means that to match this list, you should atleast be able to match Off andOn, without argument.[<On|Off|Number of int] means that f may be applied toOff,On (both without argument), orNumbern wheren is an integer.The > and < inside the variant types show that they may still berefined, either by defining more tags or by allowing less. As such, theycontain an implicit type variable. Because each of the variant typesappears only once in the whole type, their implicit type variables arenot shown.

The above variant types were polymorphic, allowing further refinement.When writing type annotations, one will most often describe fixedvariant types, that is types that cannot be refined. This isalso the case for type abbreviations. Such types do not contain < or>, but just an enumeration of the tags and their associated types,just like in a normal datatype definition.

 type 'a vlist = [`Nil | `Cons of 'a * 'a vlist];;
type 'a vlist = [ `Cons of 'a * 'a vlist | `Nil ]

 let rec map f : 'a vlist -> 'b vlist = function
    | `Nil -> `Nil
    | `Cons(a, l) -> `Cons(f a, map f l)
  ;;
val map : ('a -> 'b) -> 'a vlist -> 'b vlist = <fun>

Advanced use

Type-checking polymorphic variants is a subtle thing, and someexpressions may result in more complex type information.

 let f = function `A -> `C | `B -> `D | x -> x;;
val f : ([> `A | `B | `C | `D ] as 'a) -> 'a = <fun>

 f `E;;
- : [> `A | `B | `C | `D | `E ] = `E

Here we are seeing two phenomena. First, since this matching is open(the last case catches any tag), we obtain the type [> A |B]rather than [< A |B] in a closed matching. Then, since x isreturned as is, input and return types are identical. The notation as 'a denotes such type sharing. If we apply f to yet another tag`E, it gets added to the list.

 let f1 = function `A x -> x = 1 | `B -> true | `C -> false
  let f2 = function `A x -> x = "a" | `B -> true ;;
val f1 : [< `A of int | `B | `C ] -> bool = <fun>
val f2 : [< `A of string | `B ] -> bool = <fun>

 let f x = f1 x && f2 x;;
val f : [< `A of string & int | `B ] -> bool = <fun>

Here f1 and f2 both accept the variant tags A andB, but theargument of A is int for f1 and string for f2. In f’stypeC, only accepted by f1, disappears, but both argument typesappear for A as int & string. This means that if wepass the variant tagA to f, its argument should be _both_int and string. Since there is no such value, f cannot beapplied to A, andB is the only accepted input.

Even if a value has a fixed variant type, one can still give it alarger type through coercions. Coercions are normally written withboth the source type and the destination type, but in simple cases thesource type may be omitted.

 type 'a wlist = [`Nil | `Cons of 'a * 'a wlist | `Snoc of 'a wlist * 'a];;
type 'a wlist = [ `Cons of 'a * 'a wlist | `Nil | `Snoc of 'a wlist * 'a ]

 let wlist_of_vlist  l = (l : 'a vlist :> 'a wlist);;
val wlist_of_vlist : 'a vlist -> 'a wlist = <fun>

 let open_vlist l = (l : 'a vlist :> [> 'a vlist]);;
val open_vlist : 'a vlist -> [> 'a vlist ] = <fun>

 fun x -> (x :> [`A|`B|`C]);;
- : [< `A | `B | `C ] -> [ `A | `B | `C ] = <fun>

You may also selectively coerce values through pattern matching.

 let split_cases = function
    | `Nil | `Cons _ as x -> `A x
    | `Snoc _ as x -> `B x
  ;;
val split_cases :
  [< `Cons of 'a | `Nil | `Snoc of 'b ] ->
  [> `A of [> `Cons of 'a | `Nil ] | `B of [> `Snoc of 'b ] ] = <fun>

When an or-pattern composed of variant tags is wrapped inside analias-pattern, the alias is given a type containing only the tagsenumerated in the or-pattern. This allows for many useful idioms, likeincremental definition of functions.

 let num x = `Num x
  let eval1 eval (`Num x) = x
  let rec eval x = eval1 eval x ;;
val num : 'a -> [> `Num of 'a ] = <fun>
val eval1 : 'a -> [< `Num of 'b ] -> 'b = <fun>
val eval : [< `Num of 'a ] -> 'a = <fun>

 let plus x y = `Plus(x,y)
  let eval2 eval = function
    | `Plus(x,y) -> eval x + eval y
    | `Num _ as x -> eval1 eval x
  let rec eval x = eval2 eval x ;;
val plus : 'a -> 'b -> [> `Plus of 'a * 'b ] = <fun>
val eval2 : ('a -> int) -> [< `Num of int | `Plus of 'a * 'a ] -> int = <fun>
val eval : ([< `Num of int | `Plus of 'a * 'a ] as 'a) -> int = <fun>

To make this even more comfortable, you may use type definitions asabbreviations for or-patterns. That is, if you have defined type myvariant = [Tag1 of int |Tag2 of bool], then the pattern #myvariant isequivalent to writing (Tag1(_ : int) |Tag2(_ : bool)).

Such abbreviations may be used alone,

 let f = function
    | #myvariant -> "myvariant"
    | `Tag3 -> "Tag3";;
val f : [< `Tag1 of int | `Tag2 of bool | `Tag3 ] -> string = <fun>

or combined with with aliases.

 let g1 = function `Tag1 _ -> "Tag1" | `Tag2 _ -> "Tag2";;
val g1 : [< `Tag1 of 'a | `Tag2 of 'b ] -> string = <fun>

 let g = function
    | #myvariant as x -> g1 x
    | `Tag3 -> "Tag3";;
val g : [< `Tag1 of int | `Tag2 of bool | `Tag3 ] -> string = <fun>

4.2.1 Weaknesses of polymorphic variants

After seeing the power of polymorphic variants, one may wonder whythey were added to core language variants, rather than replacing them.

The answer is twofold. One first aspect is that while being prettyefficient, the lack of static type information allows for lessoptimizations, and makes polymorphic variants slightly heavier thancore language ones. However noticeable differences would onlyappear on huge data structures.

More important is the fact that polymorphic variants, while beingtype-safe, result in a weaker type discipline. That is, core languagevariants do actually much more than ensuring type-safety, they alsocheck that you use only declared constructors, that all constructorspresent in a data-structure are compatible, and they enforce typingconstraints to their parameters.

For this reason, you must be more careful about making types explicitwhen you use polymorphic variants. When you write a library, this iseasy since you can describe exact types in interfaces, but for simpleprograms you are probably better off with core language variants.

Beware also that some idioms make trivial errors very hard to find.For instance, the following code is probably wrong but the compilerhas no way to see it.

 type abc = [`A | `B | `C] ;;
type abc = [ `A | `B | `C ]

 let f = function
    | `As -> "A"
    | #abc -> "other" ;;
val f : [< `A | `As | `B | `C ] -> string = <fun>

 let f : abc -> string = f ;;
val f : abc -> string = <fun>

You can avoid such risks by annotating the definition itself.

 let f : abc -> string = function
    | `As -> "A"
    | #abc -> "other" ;;
Error: This pattern matches values of type [? `As ]
       but a pattern was expected which matches values of type abc
       The second variant type does not allow tag(s) `As

• 1
• This correspond to the commuting label modeof Objective Caml 3.00 through 3.02, with some additional flexibilityon total applications. The so-called classic mode (-nolabelsoptions) is now deprecated for normal use.