RFR: JDK-8295391: Add discussion of binary <-> decimal conversion issues

[Raffaello Giulietti]

On Wed, 8 Nov 2023 17:29:28 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Add discussion of some of the common pitfalls related to decimal <-> binary conversion.

src/java.base/share/classes/java/lang/Double.java line 257:

> 255:  * <br>// Numeric values listed are exact values
> 256:  * <br>oneTenthApproxAsFloat = 0.100000001490116119384765625;
> 257:  * <br>ulpOfoneTenthApproxAsFloat = Math.ulp(1.0f) = 7.450580596923828125E-9;

Suggestion:

 * <br>ulpOfoneTenthApproxAsFloat = Math.ulp(0.1f) = 7.450580596923828125E-9;

src/java.base/share/classes/java/lang/Double.java line 264:

> 262:  * <p>In particular, a correctly rounded decimal to binary conversion
> 263:  * of any string representing a number in this range, say by {@link
> 264:  * Float#valueOf(float)}, will be converted to the same value:

Suggestion:

 * Float#valueOf(String)}, will be converted to the same value:

src/java.base/share/classes/java/lang/Double.java line 287:

> 285:  * <li>less than the exact result
> 286:  * <li>equal to the exact result
> 287:  * </ul>

More compactly:
`the same floating-point value as a result can be greater than, less than, or equal to the exact result.`

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16566#discussion_r1387022202
PR Review Comment: https://git.openjdk.org/jdk/pull/16566#discussion_r1387027404
PR Review Comment: https://git.openjdk.org/jdk/pull/16566#discussion_r1387029494