[m-rev.] for review: extend coverage of builtin types in the reference manual

[Julien Fischer]

For review by anyone.

This one probably requires a few set of eyes; it changes the language in
a number of ways.  Most of this of been discussed on the mailing lists
before and there has been no disagreement.

There has been some discussion in the past about allowing float to be
a binary128 IEEE (i.e. quad-precision) number; this is *not* what the
change below allows for.  The reasons for this is that hardware support
for that format is pretty rare and it isn't generally accessible in the
majority of environments in which Mercury runs.  My preferred direction
for floating-point numbers in Mercury is that we transition to having
multiple floating-point types and that the float type would eventually
be restricted to be a binary64 value.

Julien.

---------------------------------------

Extend coverage of builtin types in the reference manual.

Replace the table of builtin types with separate subsections that cover
the primitive and other builtin types.

Add documentation for the fixed size integer types.

Tighten up the specification of builtin types in various ways, namely:

  - require that int and uint are at least 32-bits in width.
  - require that int and uint be the same width.
  - require that float be either a 32- or 64-bit IEEE floating-point value.
  - specify that char corresponds to a Unicode code point.
  - restrict the allowed encoding for Mercury strings to be either UTF-8 or UTF-16.

doc/reference_manual.texi:
     As above.


diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
index f9862f2..be29fc5 100644
--- a/doc/reference_manual.texi
+++ b/doc/reference_manual.texi
@@ -1999,46 +1999,155 @@ type classes (@pxref{Type classes}), and existentially quantified types
  @node Builtin types
  @section Builtin types

-Certain special types are builtin, or are defined in the Mercury library:
+This section describes the special types that are builtin into the Mercury
+implementation or defined in the standard library.
+
+ at menu
+* Primitive types::
+* Other builtin types::
+ at end menu
+
+ at node Primitive types
+ at subsection Primitive types
+
+There is a special syntax for constants of all primitive types except
+ at code{char}.
+(For @code{char}, the standard syntax suffixes.)
+
+ at menu
+* Signed integer types::
+* Unsigned integer types::
+* Floating-point type::
+* Character type::
+* String type::
+ at end menu
+
+ at node Signed integer types
+ at subsubsection Signed integer types
+There are five primitive signed integer types: @code{int}, @code{int8},
+ at code{int16}, @code{int32} and @code{int64}.
+
+Except for @code{int}, the width of each of these is given by the numeric
+suffix in its name.
+
+The width of @code{int} is implementation defined, but must be at least 32-bits
+and must be equal to the width of the type @code{uint}.
+
+All signed integer types use two's-complement representation.
+
+Values of the type @code{int8} must be in the range @math{-128} to @math{127},
+inclusive.
+
+Values of the type @code{int16} must be in the range @math{-32768} to @math{32767},
+inclusive.
+
+Values of the type @code{int32} must be in the range @math{-2147483648} to
+ at math{2147483647}, inclusive.
+
+Values of the type @code{int64} must be in the range @math{-9223372036854775808}
+to @math{9223372036854775807}, inclusive.
+
+Values of the type @code{int} must be in the range to @math{-(2^{N - 1})} to
+ at math{2^{N - 1} - 1}, inclusive; @math{N} being the width of @code{int}.
+
+ at node Unsigned integer types
+ at subsubsection Unsigned integer types
+There are five primitive unsigned integer types: @code{uint}, @code{uint8},
+ at code{uint16}, @code{uint32} and @code{uint64}.
+
+Except for @code{uint}, the width of each of these types is given by the numeric
+suffix in its name.
+
+The width of @code{uint} is implementation defined, but must be at least
+32-bits and must be equal to the width of the type @code{int}.
+
+Values of the type @code{uint8} must be in the range @math{0} to @math{255},
+inclusive.
+
+Values of the type @code{uint16} must be in the range @math{0} to @math{65535},
+inclusive.
+
+Values of the type @code{uint32} must be in the range @math{0} to
+ at math{4294967295}, inclusive.
+
+Values of the type @code{uint64} must be in the range @math{0} to
+ at math{18446744073709551615}.
+
+Values of the type @math{uint} must be in the range @math{0} to
+ at math{2^N - 1}, inclusive; @math{N} being the width of @code{uint}.
+
+ at node Floating-point type
+ at subsubsection Floating-point type
+There is one floating-point type: @code{float}.
+
+It is represented using either the 32-bit single-precision IEEE 754 format or
+the 64-bit double-precision IEEE 754 format.
+
+The choice between the two formats is implementation dependent.
+
+ at node Character type
+ at subsubsection Character type
+There is one character type: @code{char}.
+
+Values of this type represent Unicode code points.
+
+ at node String type
+ at subsubsection String type
+There is one string type: @code{string}.
+
+A string is a sequence of characters encoded using either the UTF-8 or UTF-16
+encoding of Unicode.
+
+The choice between the two encodings is implementation dependent.
+
+ at node Other builtin types
+ at subsection Other builtin types
+
+ at menu
+* Predicate and function types::
+* Tuple types::
+* The universal type::
+* The ``state-of-the-world'' type::
+ at end menu
+
+ at node Predicate and function types
+ at subsubsection Predicate and function types
+The predicate types are @code{pred}, @code{pred(T)}, @code{pred(T1, T2)}, @dots{}
+
+ at noindent
+The function types are  @code{(func) = T}, @code{func(T1) = T}, @code{func(T1, T2) = T}, @dots{}
+
+Higher-order predicate and function types are used to pass procedure addresses
+and closures to other predicates and functions.  @xref{Higher-order}.
+
+ at node Tuple types
+ at subsubsection Tuple types
+The tuple types are @code{@{@}}, @code{@{T@}}, @code{@{T1, T2@}}, @dots{}

- at table @asis
- at item Primitive types: @code{char}, @code{int}, @code{int8}, @code{int16},
- at code{int32}, @code{int64}, @code{uint}, @code{uint8}, @code{uint16},
- at code{uint32}, @code{uint64}, @code{float}, @code{string}.
-There is a special syntax for constants for all primitive types except
- at code{char}.  (For @code{char}, the standard syntax suffices.)
-
- at item Predicate types: @code{pred}, @code{pred(T)}, @code{pred(T1, T2)}, @dots{}
- at itemx Function types: @code{(func) = T}, @code{func(T1) = T},
- at itemx @code{func(T1, T2) = T}, @dots{}
-These higher-order function and predicate types are used to pass procedure
-addresses and closures to other predicates.  @xref{Higher-order}.
-
- at item Tuple types: @code{@{@}}, @code{@{T@}}, @code{@{T1, T2@}}, @dots{}.
  A tuple type is equivalent to a discriminated union type
  (@pxref{Discriminated unions}) with declaration
  @example
-:- type @{Arg1, Arg2, @dots{}, ArgN@}
-        --->    @{ @{Arg1, Arg2, @dots{}, ArgN@} @}.
+ :- type @{Arg1, Arg2, @dots{}, ArgN@}
+         --->    @{ @{Arg1, Arg2, @dots{}, ArgN@} @}.
  @end example

- at item The universal type: @code{univ}.
+ at node The universal type
+ at subsubsection The universal type
  The type @code{univ} is defined in the standard library module @code{univ},
  along with the predicates @code{type_to_univ/2} and @code{univ_to_type/2}.
  With those predicates, any type can be converted to the universal type
  and back again.
-The universal type is useful for situations
-where you need heterogeneous collections.
+The universal type is useful for situations where you need heterogeneous
+collections.

- at item The ``state-of-the-world'' type: @code{io.state}.
+ at node The ``state-of-the-world'' type
+ at subsubsection The ``state-of-the-world'' type
  The type @code{io.state} is defined in the standard library module @code{io},
  and represents the state of the world.
-Predicates which perform I/O are passed the old state of the world
-and produce a new state of the world.
+Predicates which perform I/O are passed the old state of the world and produce
+a new state of the world.
  In this way, we can give a declarative semantics to code that performs I/O.

- at end table
-
  @node User-defined types
  @section User-defined types