Update to the Double::toString(double) Javadoc

[raffaello.giulietti at gmail.com]

Hi,

as may be known, the current Javadoc for Double::toString(double) is not
specific enough. As a consequence, different implementations can return
different results.

To see this, here are some quotes from the Javadoc. It asks: "How many
digits must be printed for the fractional part of m or a?" It answers:
"There must be at least one digit to represent the fractional part, and
beyond that as many, but only as many, more digits as are needed to
uniquely distinguish the argument value from adjacent values of type
double."

One interpretation is: output "as many" digit of m (or a) itself. But
this can lead to unnecessarily long results. For example, the true value
of the double v closest to 0.3 is
v = 0.299999999999999988897769753748434595763683319091796875
so according to this restricted interpretation the method should return
"0.29999999999999998"
because shorter prefixes do not round to v.

Another interpretation exploits the astute word "represent" in the
answer, so it might sound: output "as many" digits of a nearby, vaguely
determined "short" number that "represents" m (or a) and happens to
round to v. In this case the obvious choice is
"0.3"
which is the result returned by the method.

One problem with this interpretation is that sometimes there is more
than one choice. For example, both 4.8E-324 and 4.9E-324 round to
Double.MIN_VALUE. The method chooses the latter one, presumably because
it is closer to the double, but this is not specified. It is also not
specified what happens if two equally shortest numbers that round to the
same double are also equally close to it.

Of course, the same holds for Float::toString(float).



The code that was uploaded to this mailing list [1] as a contribution to
fix [2], contains a purportedly better Javadoc that imposes a uniquely
specified result (see method math.DoubleToDecimal::toString(double) ).
It has been carefully written to ensure that the spirit of the current
Javadoc is preserved as much as possible and to make sure that the
results returned by the contributed code and by the current OpenJDK
implementation are consistent (modulo the anomalies discussed in [2]).



The question is if this needs to be submitted to the Compatibility &
Specification Review Group?
If so, what is the correct process to follow for an individual
contributor like me?

I ask because I would like my contribution to be accepted for the next
OpenJDK 11 LTS release: I have no idea on how long it would take for a
spec change to be approved, if the need arises at all in a case like
this one.



Greetings
Raffaello



[1]
http://mail.openjdk.java.net/pipermail/core-libs-dev/2018-April/052696.html
[2] https://bugs.openjdk.java.net/browse/JDK-4511638