JLS 3.10.2 -- Exposition of hexadecimal f.p. literals

[Joe Darcy]

Hello,

Catching up on email...

On 10/18/2019 11:28 AM, Alex Buckley wrote:
> The following issue was raised on the java-se-spec-comments list:
>
> https://mail.openjdk.java.net/pipermail/java-se-spec-comments/2019-October/000003.html 
>
>
> -----
> In 3.10.2, Floating-Point Literals, hexadecimal floating-point 
> literals are poorly explained. It is not mentioned that the "binary 
> exponent" part is in base 2 instead of the decimal floating-point 
> exponent base 10. An example would be useful. Something like "0xFFp1 = 
> 510.0".
>
> It is also somewhat unclear if hexadecimal floating-point literals are 
> double- or single-precision by default. The first text paragraph of 
> page 36 could clear this up if changed from "A floating-point literal 
> is of type float [...]" to "A floating-point literal (decimal or 
> hexadecimal) is of type float [...]".
>
> The values for the largest/smallest positive finite non-zero 
> float/double literals should also be given in hexadecimal notation and 
> include mention of the predefined constants MIN_VALUE and MAX_VALUE of 
> the Float and Double classes.
>
> Finally, on page 37 the reference to "a non-zero denormalized number" 
> should add "(see 4.2.3)".
> -----
>
> These are largely issues of editorial clarity, not correctness. I 
> defer to Joe Darcy to decide whether, 15 years after hexadecimal f.p. 
> literals were added to the JLS (Third Edition, for Java SE 5), it is 
> worth trying to incorporate/update material from 
> https://blogs.oracle.com/darcy/hexadecimal-floating-point-literals 
> into JLS 3.10.2.
>
FWIW, javadoc of the Double.toHexString method does have a more detailed 
description of the double value to hex-string mapping. However, it would 
be an aid to readers of the JLS to include a bit more exposition about 
hexadecimal floating-point literals. For example, in the API spec 
Double.MAX_VALUE is listed as its numerical value ((2-2^-52 )·2^1023 ), 
as a decimal floating-point value, and as a hexadecimal floating-point 
value (0x1.fffffffffffffP+1023):

https://docs.oracle.com/en/java/javase/13/docs/api/java.base/java/lang/Double.html#MAX_VALUE

Analogous text could be included for the JLS discussion of the min and 
max values of float and double.

To make an explicit statement about the value of a floating-point 
literal, I suggest after the sentence

"A floating-point literal may be expressed in decimal (base 10) or 
hexadecimal (base 16). "

adding something like

"The exact numerical value of a decimal floating-point literals is

     decimal_sequence * 10 ^ exponent

The exact numerical value of a hexadecimal floating-point literal is

     hex_sequence * 2 ^ exponent

The conversion of the exact numerical value to a particular 
floating-point value is handled as if by Float.valueOf or Double.valueOf 
for literals of type float and double, respectively."

HTH,

-Joe