Import Upstream version 20180207

[hcoop/debian/mlton.git] / doc / guide / src / EqualityType.adoc

EqualityType
============

An equality type is a type to which <:PolymorphicEquality:> can be
applied.  The <:DefinitionOfStandardML:Definition> and the
<:BasisLibrary:Basis Library> precisely spell out which types are
equality types.

* `bool`, `char`, `IntInf.int`, ++Int__<N>__.int++, `string`, and ++Word__<N>__.word++ are equality types.

* for any `t`, both `t array` and `t ref` are equality types.

* if `t` is an equality type, then `t list`, and `t vector` are equality types.

* if `t1`, ..., `tn` are equality types, then `t1 * ... * tn` and `{l1: t1, ..., ln: tn}` are equality types.

* if `t1`, ..., `tn` are equality types and `t` <:AdmitsEquality:>, then `(t1, ..., tn) t` is an equality type.

To check that a type t is an equality type, use the following idiom.
[source,sml]
----
structure S: sig eqtype t end =
   struct
      type t = ...
   end
----

Notably, `exn` and `real` are not equality types.  Neither is `t1 -> t2`, for any `t1` and `t2`.

Equality on arrays and ref cells is by identity, not structure.
For example, `ref 13 = ref 13` is `false`.
On the other hand, equality for lists, strings, and vectors is by
structure, not identity.  For example, the following equalities hold.

[source,sml]
----
val _ = [1, 2, 3] = 1 :: [2, 3]
val _ = "foo" = concat ["f", "o", "o"]
val _ = Vector.fromList [1, 2, 3] = Vector.tabulate (3, fn i => i + 1)
----