llvm dev - Sep 2020 - Misleading documentation on FP to integer conversion instructions?

The LLVM IR reference manual states, for fptosi:

"The ‘fptosi’ instruction converts its floating-point
<http://llvm.org/docs/LangRef.html#t-floating> operand into the nearest
(rounding towards zero) signed integer value."

I interpreted this to mean that it rounds:

The nearest integer to 0.3 is 0.

The nearest integer to 0.9 is 1.

The nearest integer to 0.5 is either 0 or 1. And this is where the
"rounding towards zero" applies - the result is prescribed to be 0.

In actuality, the instruction truncates, returning 0 for all cases.

Should this be reworded, perhaps to use the word "truncate"?
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200904/07a39ca1/attachment.html>

> On Sep 4, 2020, at 6:26 AM, David Jones via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 
> The LLVM IR reference manual states, for fptosi:
> 
> "The ‘fptosi’ instruction converts its floating-point
<http://llvm.org/docs/LangRef.html#t-floating> operand into the nearest
(rounding towards zero) signed integer value."
> 
> I interpreted this to mean that it rounds:
> 
> The nearest integer to 0.3 is 0.
> 
> The nearest integer to 0.9 is 1.
> 
> The nearest integer to 0.5 is either 0 or 1. And this is where the
"rounding towards zero" applies - the result is prescribed to be 0.
> 
> In actuality, the instruction truncates, returning 0 for all cases.
> 
> Should this be reworded, perhaps to use the word "truncate”?
“Rounding towards zero” is a term of art from IEEE 754.  See
https://en.wikipedia.org/wiki/IEEE_754#Directed_roundings
<https://en.wikipedia.org/wiki/IEEE_754#Directed_roundings>

I agree that the documentation could be made more accessible by *also* using the
colloquial term “truncation”, but round-towards-zero is the correct name for
this behavior and should be retained.

—Owen
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200904/046374a0/attachment.html>

If fptosi takes 0.9 -> 0, then that is not 'rounding' in any sense
I'm
aware of (IEEE754 or otherwise).
Rounding (in the IEE754 sense) determines how a number is converted when it
is halfway between two
candidate results.  (see round(), ceil(), floor()).

fptosi seems to model the behavior of a C cast from float to int,
which truncates the fractional bits (as in trunc()).

Steve


On Fri, Sep 4, 2020 at 10:51 AM Owen Anderson via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
>
>
> On Sep 4, 2020, at 6:26 AM, David Jones via llvm-dev <
> llvm-dev at lists.llvm.org> wrote:
>
> The LLVM IR reference manual states, for fptosi:
>
> "The ‘fptosi’ instruction converts its floating-point
> <http://llvm.org/docs/LangRef.html#t-floating> operand into the
nearest
> (rounding towards zero) signed integer value."
>
> I interpreted this to mean that it rounds:
>
> The nearest integer to 0.3 is 0.
>
> The nearest integer to 0.9 is 1.
>
> The nearest integer to 0.5 is either 0 or 1. And this is where the
> "rounding towards zero" applies - the result is prescribed to be
0.
>
> In actuality, the instruction truncates, returning 0 for all cases.
>
> Should this be reworded, perhaps to use the word "truncate”?
>
>
> “Rounding towards zero” is a term of art from IEEE 754.  See
> https://en.wikipedia.org/wiki/IEEE_754#Directed_roundings
>
> I agree that the documentation could be made more accessible by *also*
> using the colloquial term “truncation”, but round-towards-zero is the
> correct name for this behavior and should be retained.
>
> —Owen
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200904/4d45fe6b/attachment.html>