Re: RFR: 8333768: Minor doc updates to java.lang.{Float, Double} [v4]
On Wed, 19 Jun 2024 01:43:27 GMT, Joe Darcy wrote: >> Misc small doc updates and addition of `@Overrides` annotations. > > Joe Darcy has updated the pull request incrementally with one additional > commit since the last revision: > > Respond to review feedback. Added some typographical updates to Math/StrictMath to replace hyphens with HTML minus characters, which read better in that context. - PR Comment: https://git.openjdk.org/jdk/pull/19590#issuecomment-2227122249
Re: RFR: 8333768: Minor doc updates to java.lang.{Float, Double} [v4]
On Wed, 19 Jun 2024 01:49:47 GMT, Joe Darcy 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.10001. However, `Formatter` with a specifier `"%.17f"` will render this as 0.1. 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.19996 by IEEE and to 1.2 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
Re: RFR: 8333768: Minor doc updates to java.lang.{Float, Double} [v4]
On Fri, 7 Jun 2024 12:48:51 GMT, Raffaello Giulietti wrote: >> Joe Darcy has updated the pull request incrementally with one additional >> commit since the last revision: >> >> Respond to review feedback. > > 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. - PR Review Comment: https://git.openjdk.org/jdk/pull/19590#discussion_r1645286967
Re: RFR: 8333768: Minor doc updates to java.lang.{Float, Double} [v4]
> Misc small doc updates and addition of `@Overrides` annotations. Joe Darcy has updated the pull request incrementally with one additional commit since the last revision: Respond to review feedback. - Changes: - all: https://git.openjdk.org/jdk/pull/19590/files - new: https://git.openjdk.org/jdk/pull/19590/files/9df534a3..4277c32b Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=19590&range=03 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=19590&range=02-03 Stats: 30 lines in 2 files changed: 26 ins; 0 del; 4 mod Patch: https://git.openjdk.org/jdk/pull/19590.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/19590/head:pull/19590 PR: https://git.openjdk.org/jdk/pull/19590
