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

[Julien Fischer]

Hi Zoltan,

On Thu, 24 Aug 2017, Zoltan Somogyi wrote:

> 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.

Except that's only true for the C backends; for both Java and C#
backends int and uint are 32-bits regardless of what the size of a
pointer on the platform is.

>> @@ -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".

Done.

>>   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".

Done.

>>   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.

Agreed.

Julien.