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

> On Sep 4, 2020, at 2:40 PM, Neil Nelson via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 
>> 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()).
Rounding in the IEEE 754 sense is simply an algorithm to choose one of the two
closest values from some set. It does not only concern how halfway cases are
handled. There are a number of rounding attributes defined by IEEE 754:

- round to nearest, ties to even (default rounding)
- round to nearest, ties away from zero (only for decimal)
- round to nearest, ties toward zero (used only for augmented addition)
- round up
- round down
- round toward zero

The last of these is the rounding mode under discussion on this thread. Note
that the first three have to specify how halfway cases are handled (“ties to
…”), but the latter three do not (because the result is constant across the
interval between any two values, so there is not change at “halfway”).

– Steve
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200904/29e5528b/attachment.html>

Regardless of whether "rounding towards zero" is a term of art,
putting it
in parentheses creates confusion.  Parenthetical phrases should be used to
provide additional but non-essential information to a sentence.  If
striking out a parenthetical expression changes the meaning of the
sentence, then it shouldn't have been parenthetical.
> 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.

The remaining sentence is not only different than what was intended, but it
is also false.
> The ‘fptosi’ instruction converts its floating-point
<http://llvm.org/docs/LangRef.html#t-floating> operand into the nearest
signed integer value whose absolute value is not larger than the
floating-point operand (i.e., it rounds towards zero).

By the way, parenthetical phrases aren't always inside parentheses.
Sometimes they are set off with commas or dashes instead.

On Fri, Sep 4, 2020 at 12:40 PM Steve (Numerics) Canon via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
> On Sep 4, 2020, at 2:40 PM, Neil Nelson via llvm-dev <
> llvm-dev at lists.llvm.org> wrote:
>
>
> 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()).
>
>
> Rounding in the IEEE 754 sense is simply an algorithm to choose one of the
> two closest values from some set. It does not only concern how halfway
> cases are handled. There are a number of rounding attributes defined by
> IEEE 754:
>
> - round to nearest, ties to even (default rounding)
> - round to nearest, ties away from zero (only for decimal)
> - round to nearest, ties toward zero (used only for augmented addition)
> - round up
> - round down
> - round toward zero
>
> The last of these is the rounding mode under discussion on this thread.
> Note that the first three have to specify how halfway cases are handled
> (“ties to …”), but the latter three do not (because the result is constant
> across the interval between any two values, so there is not change at
> “halfway”).
>
> – Steve
> _______________________________________________
> 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/20200908/bebcb001/attachment.html>

Hello neighbors,

You can argue that the documentation is confusing (because some were confused;
ipso facto), but this appeal to grammar is wrong.

A sentence cannot (grammatically) rely on the portion in parentheses. However,
the portion in parentheses can (and typically does) alter the meaning of a
sentence. Why would anyone go to all that trouble if it couldn’t?

Even if what the author (Adrian) said was true, the sentence is still acceptable
(albeit potentially confusing). The result is the nearest signed integer value.
Oh (gasp!), but what does “nearest” mean in this sentence? We have yet to
establish any sort of metric. Enter the parentheses, one of whose (common) uses
is to provide clarification. And thus, with a clarification (in parentheses),
the sentence is complete, and read literally leaves no room for ambiguity (but
how does one round? Oh, in the direction of zero. Got it). However, as it has
confused at least one person it is also accurate to label it confusing.
Misleading? Well that implies intent, and is an unfortunate word choice.

This is perfectly cromulent use of the word “rounding. Rounding means replacing
a number<https://en.wikipedia.org/wiki/Number> with an
approximate<https://en.wikipedia.org/wiki/Approximation> value that has a
shorter<https://en.wikipedia.org/wiki/Concision>,
simpler<https://en.wikipedia.org/wiki/Simplicity>, or more explicit
representation (Wikipedia:
Rounding<https://en.wikipedia.org/wiki/Rounding>). It makes no assumption
of what shorter, simpler, or more explicit means. One must clarify. The
documentation does, in an unambiguous manner.

Your friend,
Jordan

From: llvm-dev <llvm-dev-bounces at lists.llvm.org> on behalf of Adrian
McCarthy via llvm-dev <llvm-dev at lists.llvm.org>
Reply-To: Adrian McCarthy <amccarth at google.com>
Date: Tuesday, September 8, 2020 at 9:05 AM
To: "Steve (Numerics) Canon" <scanon at apple.com>
Cc: llvm-dev <llvm-dev at lists.llvm.org>
Subject: Re: [llvm-dev] Misleading documentation on FP to integer conversion
instructions?

Regardless of whether "rounding towards zero" is a term of art,
putting it in parentheses creates confusion.  Parenthetical phrases should be
used to provide additional but non-essential information to a sentence.  If
striking out a parenthetical expression changes the meaning of the sentence,
then it shouldn't have been parenthetical.
> The ‘fptosi’ instruction converts its
floating-point<https://urldefense.proofpoint.com/v2/url?u=http-3A__llvm.org_docs_LangRef.html-23t-2Dfloating&d=DwMFaQ&c=5VD0RTtNlTh3ycd41b3MUw&r=E_cXPNvxfZblQcT36zywtDUO0KZpVd9qvHbRN7gfLOU&m=1L8phTIjRC_ce9r56UvwXomoUY2JQ9RNbzdm0jJUW2U&s=PKl7LvjMA5oLaeb-HzAPIWxBMguf3T00GXYALXdXmJo&e=>
operand into the nearest (rounding towards zero) signed integer value.
The remaining sentence is not only different than what was intended, but it is
also false.
> The ‘fptosi’ instruction converts its
floating-point<https://urldefense.proofpoint.com/v2/url?u=http-3A__llvm.org_docs_LangRef.html-23t-2Dfloating&d=DwMFaQ&c=5VD0RTtNlTh3ycd41b3MUw&r=E_cXPNvxfZblQcT36zywtDUO0KZpVd9qvHbRN7gfLOU&m=1L8phTIjRC_ce9r56UvwXomoUY2JQ9RNbzdm0jJUW2U&s=PKl7LvjMA5oLaeb-HzAPIWxBMguf3T00GXYALXdXmJo&e=>
operand into the nearest signed integer value whose absolute value is not larger
than the floating-point operand (i.e., it rounds towards zero).
By the way, parenthetical phrases aren't always inside parentheses. 
Sometimes they are set off with commas or dashes instead.

On Fri, Sep 4, 2020 at 12:40 PM Steve (Numerics) Canon via llvm-dev <llvm-dev
at lists.llvm.org<mailto:llvm-dev at lists.llvm.org>> wrote:
On Sep 4, 2020, at 2:40 PM, Neil Nelson via llvm-dev <llvm-dev at
lists.llvm.org<mailto:llvm-dev at lists.llvm.org>> wrote:

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

Rounding in the IEEE 754 sense is simply an algorithm to choose one of the two
closest values from some set. It does not only concern how halfway cases are
handled. There are a number of rounding attributes defined by IEEE 754:

- round to nearest, ties to even (default rounding)
- round to nearest, ties away from zero (only for decimal)
- round to nearest, ties toward zero (used only for augmented addition)
- round up
- round down
- round toward zero

The last of these is the rounding mode under discussion on this thread. Note
that the first three have to specify how halfway cases are handled (“ties to
…”), but the latter three do not (because the result is constant across the
interval between any two values, so there is not change at “halfway”).

– Steve
_______________________________________________
LLVM Developers mailing list
llvm-dev at lists.llvm.org<mailto:llvm-dev at lists.llvm.org>
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev<https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.llvm.org_cgi-2Dbin_mailman_listinfo_llvm-2Ddev&d=DwMFaQ&c=5VD0RTtNlTh3ycd41b3MUw&r=E_cXPNvxfZblQcT36zywtDUO0KZpVd9qvHbRN7gfLOU&m=1L8phTIjRC_ce9r56UvwXomoUY2JQ9RNbzdm0jJUW2U&s=wAB-SJpJVLEdvO0EQhi0nzvhRAe_r9UnAdrXuI3gIKw&e=>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200908/96b8cc1c/attachment.html>

On 08/09/2020 17:04, Adrian McCarthy via llvm-dev wrote:
>  > The ‘|fptosi|’ instruction converts its floating-point 
> <http://llvm.org/docs/LangRef.html#t-floating> operand into the
nearest
> signed integer value whose absolute value is not larger than the 
> floating-point operand (i.e., it rounds towards zero).
"The fptosi instruction rounds its operand to the nearest integer closer 
to zero (commonly known as truncation)"

Cheers,
Wol