[m-rev.] for review: update the reference manual for fixed size integer types

Zoltan Somogyi zoltan.somogyi at runbox.com
Thu Aug 24 15:23:50 AEST 2017

On Thu, 24 Aug 2017 14:16:08 +1000 (AEST), Julien Fischer <jfischer at opturion.com> wrote:
> diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
> index e837e9ecd..41a942149 100644
> --- a/doc/reference_manual.texi
> +++ b/doc/reference_manual.texi
> @@ -312,10 +312,19 @@ A character-code literal is @samp{0'} followed by any single character.
>   Decimal, binary, octal and hexadecimal literals may be optionally terminated by
>   a suffix that indicates whether the literal represents a signed or unsigned
> -integer.
> -The suffix @samp{i} indicates that the literal is a signed integer.
> -The suffix @samp{u} indicates that the literal is an unsigned integer.
> -Integer literals without such a terminating suffix are considered to be signed.
> +integer and what the size of that integer is.
> +These suffixes are:
> + at multitable {i_or_no_suffix} {Unsigned} {Implementation_defined}
> + at headitem Suffix @tab Signedness @tab Size
> + at item @code{i} or no suffix   @tab Signed   @tab Implementation-defined
> + at item @code{i8}               @tab Signed   @tab 8-bit
> + at item @code{i16}              @tab Signed   @tab 16-bit
> + at item @code{i32}              @tab Signed   @tab 32-bit
> + at item @code{u}                @tab Unsigned @tab Implementation-defined
> + at item @code{u8}               @tab Unsigned @tab 8-bit
> + at item @code{u16}              @tab Unsigned @tab 16-bit
> + at item @code{u32}              @tab Unsigned @tab 32-bit
> + at end multitable

I would replace "Implementation-defined" with "Pointer-sized", with
a note below saying that this is the natural size of pointers on the given platform
(which itself is of course implementation-defined). The later section specifies
MR_Integer/MR_Unsigned anyway.

> @@ -2597,8 +2608,8 @@ Furthermore, different platforms often have their own natural orderings
>   which are not necessarily consistent with each other.
>   As such, the standard ordering for most types is not fully defined.
> -For the primitive types @code{int} and @code{uint} the standard ordering is the
> -usual numerical ordering.
> +For the primitive integer types the standard ordering is the usual numerical
> +ordering.
>   Implementations should reject code containing overflowing integer literals.

I would add a comma after "types".

>   For the primitive type @code{float},
> @@ -5249,10 +5260,8 @@ For the low-level C backend, e.g. the asm_fast grades, the type of this
>   variable will be @code{MR_Word}.
>   For the high-level C backend, e.g. the hlc grades, the type of this variable
>   depends upon the Mercury type of the mutable.
> -For mutables of the Mercury types @code{int}, @code{uint}, @code{float},
> - at code{char} and @code{string}, the corresponding C types will be
> - at code{MR_Integer}, @code{MR_Unsigned}, @code{MR_Float}, @code{MR_Char} and
> - at code{MR_String} respectively.
> +For mutables of a Mercury primitive type the corresponding C type is given by
> +the mapping in @ref{C data passing conventions}.
>   For mutables of any other type the corresponding C type will be @code{MR_Word}.

Again, I would add a comma between "primitive type" and "the".

>   This attribute is not currently implemented for the non-C backends.
> @@ -6801,7 +6810,7 @@ then the behaviour is undefined --- your program may misbehave or crash.)
>   If there are both Mercury definitions and foreign_proc definitions for
>   a procedure and/or foreign_proc definitions for different languages,
> -it is implementation defined which definition is used.
> +it is implementation-defined which definition is used.

I think we *should* specify which definition is used, by giving, for each
target language, a preference list of the foreign_proc languages applicable
to that target, and specifying that the Mercury clause definition will be used
only if there is no foreign_proc definition in a language that is acceptable
for that target. But that is for a different diff.

The diff is otherwise fine.


More information about the reviews mailing list