RFR: 8333768: Minor doc updates to java.lang.{Float, Double} [v4]

[Raffaello Giulietti]

On Wed, 19 Jun 2024 01:49:47 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/Double.java line 595:
>> 
>>> 593:      * This method corresponds to the convertToDecimalCharacter
>>> 594:      * operation defined in IEEE 754.
>>> 595:      *
>> 
>> Does it?
>> 
>> IEEE 754 `convertToDecimalCharacter` takes a 2nd argument, the `conversionSpecification` which "specifies the precision and formatting of the _decimalCharacterSequence_ result". There's no such flexibility here.
>> 
>> Moreover, there seems to be no way to have a `conversionSpecification` that ensures the "shortest decimal" semantics of this method.
>> 
>> Finally, IEEE 754 requires to signal inexact exceptions.
>> 
>> Suggestion:
>> 
>>      * This method vaguely corresponds to the convertToDecimalCharacter
>> 
>> 
>> The same holds for the other additional `@apiNote`s.
>
>> Does it?
>> 
>> IEEE 754 `convertToDecimalCharacter` takes a 2nd argument, the `conversionSpecification` which "specifies the precision and formatting of the _decimalCharacterSequence_ result". There's no such flexibility here.
>> 
>> Moreover, there seems to be no way to have a `conversionSpecification` that ensures the "shortest decimal" semantics of this method.
>> 
>> Finally, IEEE 754 requires to signal inexact exceptions.
>> 
>> The same holds for the other additional `@apiNote`s.
> 
> Thanks for the comments @rgiulietti .
> 
> I've weakened the language for this method and added a javadoc to Formatter, which more closely aligns with the IEEE model of binary -> decimal conversion. For toHexString, the IEEE standard does state:
> 
> "When converting to hexadecimal-significand character sequences in the absence of an explicit precision
> specification, enough hexadecimal characters shall be used to represent the binary floating-point number
> exactly."
> 
> so the there isn't an exactly corresponding concern there.
> 
> With the frame condition that the Java platform ignores the sticky flags, I think making the linkage to IEEE operations is still informative. Basically, (in many case) if you project down to the subset of IEEE 754 the Java platform supports, this Java method computes the same floating-point value as this IEEE operation, etc.

Take the `double` closest to the exact decimal 0.1.

My understanding is that IEEE with a precision of 17 would convert it to the decimal 0.10000000000000001.

However, `Formatter` with a specifier `"%.17f"` will render this as 0.10000000000000000. That's because `Formatter`'s spec is based on this method (which produces 0.1), so cannot generate the trailing 1.

Similarly, the `double` closest to 1.2 is converted to 1.19999999999999996 by IEEE and to 1.20000000000000000 by `Formatter`, because this method produces 1.2.

In other words, neither this method nor the functionality offered by `Formatter` and friends correspond to IEEE, at least not in full.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/19590#discussion_r1646298859