[llvm-dev] Misleading documentation on FP to integer conversion instructions?

Tue Sep 8 09:36:28 PDT 2020

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>