On Wed, 19 Jun 2024 01:49:47 GMT, Joe Darcy <da...@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
