Update to the Double::toString(double) Javadoc

joe darcy joe.darcy at oracle.com
Fri Apr 27 18:58:08 UTC 2018

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,


More information about the core-libs-dev mailing list