Update to the Double::toString(double) Javadoc

[joe darcy]

Hello Raffaello,


On 4/27/2018 7:39 AM, raffaello.giulietti at gmail.com wrote:
> 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).

For background on the design of this printing methodology see  "How to 
Print Floating-Point Numbers Accurately," Guy L. Steele and Jon L. White 
in the proceedings of the 1990 PLDI.

> 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?

It does sound like the change merits CSR review.  On a procedural front, 
to create a CSR, one needs an account in the bug system, so the sponsor 
of your issue with an account, Brian Burkhalter I believe, would need to 
assist here. Conceptually, the CSR process is described on its wiki page 
https://wiki.openjdk.java.net/display/csr/Main. The review is concerned 
with evaluating the compatibility impact of the spec (or behavioral 
change), so information about those matters is provided and considered.

>
> 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.
>

The normal review SLA for CSR review is a week. Note this is time to 
review rather than time to approve since the CSR can have comments that 
need to be addressed, etc.

HTH and thanks for the code submission,

-Joe