Misleading documentation on FP to integer conversion instructions?

The LLVM IR reference manual states, for fptosi:

“The ‘fptosi’ instruction converts its floating-point 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

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

One might argue that 0 is “the value closest and no greater in magnitude than the infinitely precise result” of rounding 0.9 to an integer. But this seems like nitpicking.
I agree that Owen’s suggestion of adding wording similar to the Wikipedia entry is a reasonable way to disambiguate.

Conversely, we can simply use the wording from the C standard as that is what the operation implements:

When a finite value of real floating type is converted to an integer type other than _Bool,
the fractional part is discarded (i.e., the value is truncated toward zero). If the value of
the integral part cannot be represented by the integer type, the behavior is undefined.

Rounding towards zero
appears to be a kind of generic term for a variety of operations not always with our more common sense.

Neil Nelson

From: llvm-dev [mailto:llvm-dev-bounces@lists.llvm.org]

On Behalf Of Stephen Neuendorffer via llvm-dev
Subject: Re: [llvm-dev] Misleading documentation on FP to integer conversion instructions?

If fptosi takes 0.9 → 0, then that is not ‘rounding’ in any sense I’m aware of (IEEE754 or otherwise).

The IEEE 754 spec does include the term “round toward 0” (truncation) in the five rounding modes.

Rounding (in the IEE754 sense) determines how a number is converted when it is halfway between

two candidate results. (see round(), ceil(), floor()).

The term for that is “round to nearest”; the word “rounding” by itself intentionally includes all possible rounding modes.

The problem with the LLVM documentation is the use of the word “nearest” in the description of round toward 0; that part should be removed or reworded to avoid confusion.

  • Chuck

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

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

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 with an approximate value that has a shorter, simpler, or more explicit representation (Wikipedia: 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

"The fptosi instruction rounds its operand to the nearest integer closer to zero (commonly known as truncation)"

Cheers,
Wol