(Introduced in OCaml 3.12, generalized in 4.06)
A “destructive” substitution (with ... := ...) behaves essentially like normal signature constraints (with ... = ...), but it additionally removes the redefined type or module from the signature.
Prior to OCaml 4.06, there were a number of restrictions: one could only remove types and modules at the outermost level (not inside submodules), and in the case of with type the definition had to be another type constructor with the same type parameters.
A natural application of destructive substitution is merging two signatures sharing a type name.
One can also use this to completely remove a field:
or to rename one:
Note that you can also remove manifest types, by substituting with the same type.
(Introduced in OCaml 4.08)
Local substitutions behave like destructive substitutions (with ... := ...) but instead of being applied to a whole signature after the fact, they are introduced during the specification of the signature, and will apply to all the items that follow.
This provides a convenient way to introduce local names for types and modules when defining a signature:
Note that, unlike type declarations, type substitution declarations are not recursive, so substitutions like the following are rejected: