8.3 Private types

• 8.3.1 Private variant and record types
• 8.3.2 Private type abbreviations
• 8.3.3 Private row types

Private type declarations in module signatures, of the formtype t = private …, enable libraries toreveal some, but not all aspects of the implementation of a type toclients of the library. In this respect, they strike a middle groundbetween abstract type declarations, where no information is revealedon the type implementation, and data type definitions and typeabbreviations, where all aspects of the type implementation arepublicized. Private type declarations come in three flavors: forvariant and record types (section 8.3.1),for type abbreviations (section 8.3.2),and for row types (section 8.3.3).

8.3.1 Private variant and record types

(Introduced in Objective Caml 3.07)

Values of a variant or record type declared privatecan be de-structured normally in pattern-matching or viathe expr. field notation for record accesses. However, values ofthese types cannot be constructed directly by constructor applicationor record construction. Moreover, assignment on a mutable field of aprivate record type is not allowed.

The typical use of private types is in the export signature of amodule, to ensure that construction of values of the private type alwaysgo through the functions provided by the module, while still allowingpattern-matching outside the defining module. For example:

 module M : sig
   type t = private A | B of int
   val a : t
   val b : int -> t
 end = struct
   type t = A | B of int
   let a = A
   let b n = assert (n > 0); B n
 end
 

Here, the private declaration ensures that in any value of typeM.t, the argument to the B constructor is always a positive integer.

With respect to the variance of their parameters, private types arehandled like abstract types. That is, if a private type hasparameters, their variance is the one explicitly given by prefixingthe parameter by a ‘+’ or a ‘-’, it is invariant otherwise.

8.3.2 Private type abbreviations

(Introduced in Objective Caml 3.11)

Unlike a regular type abbreviation, a private type abbreviationdeclares a type that is distinct from its implementation type typexpr.However, coercions from the type to typexpr are permitted.Moreover, the compiler “knows” the implementation type and can takeadvantage of this knowledge to perform type-directed optimizations.

The following example uses a private type abbreviation to define amodule of nonnegative integers:

 module N : sig
   type t = private int
   val of_int: int -> t
   val to_int: t -> int
 end = struct
   type t = int
   let of_int n = assert (n >= 0); n
   let to_int n = n
 end
 

The type N.t is incompatible with int, ensuring that nonnegativeintegers and regular integers are not confused. However, if x hastype N.t, the coercion (x :> int) is legal and returns theunderlying integer, just like N.to_int x. Deep coercions are alsosupported: if l has type N.t list, the coercion (l :> int list)returns the list of underlying integers, like List.map N.to_int lbut without copying the list l.

Note that the coercion (expr:> typexpr) is actually an abbreviatedform,and will only work in presence of private abbreviations if neither thetype of expr nor typexpr contain any type variables. If they do,you must use the full form (expr: typexpr₁:> typexpr₂) wheretypexpr₁ is the expected type of expr. Concretely, this would be (x : N.t :> int) and (l : N.t list :> int list) for the above examples.

8.3.3 Private row types

(Introduced in Objective Caml 3.09)

Private row types are type abbreviations where part of thestructure of the type is left abstract. Concretely typexpr in theabove should denote either an object type or a polymorphic varianttype, with some possibility of refinement left. If the privatedeclaration is used in an interface, the corresponding implementationmay either provide a ground instance, or a refined private type.

 module M : sig type c = private < x : int; .. > val o : c end =
 struct
   class c = object method x = 3 method y = 2 end
   let o = new c
 end
 

This declaration does more than hiding the y method, it also makesthe type c incompatible with any other closed object type, meaningthat only o will be of type c. In that respect it behavessimilarly to private record types. But private row types aremore flexible with respect to incremental refinement. This feature canbe used in combination with functors.

 module F(X : sig type c = private < x : int; .. > end) =
 struct
   let get_x (o : X.c) = o#x
 end
 module G(X : sig type c = private < x : int; y : int; .. > end) =
 struct
   include F(X)
   let get_y (o : X.c) = o#y
 end
 

A polymorphic variant type [t], for example

 type t = [ `A of int | `B of bool ]
 

can be refined in two ways. A definition [u] may add new field to [t],and the declaration

 type u = private [> t]
 

will keep those new fields abstract. Construction of values of type[u] is possible using the known variants of [t], but anypattern-matching will require a default case to handle the potentialextra fields. Dually, a declaration [u] may restrict the fields of [t]through abstraction: the declaration

 type v = private [< t > `A]
 

corresponds to private variant types. One cannot create a value of theprivate type [v], except using the constructors that are explicitlylisted as present, (`A n) in this example; yet, whenpatter-matching on a [v], one should assume that any of theconstructors of [t] could be present.

Similarly to abstract types, the variance of type parametersis not inferred, and must be given explicitly.