Update to the Double::toString(double) Javadoc

raffaello.giulietti at gmail.com raffaello.giulietti at gmail.com
Fri Apr 27 19:36:07 UTC 2018

Hi Joe,

so I beg Brian to get in touch with me for the CSR review.

I'm familiar with the paper of Steele and White.
For background on the design of my contribution see [1].


[1] https://9b7022c5f9.files.wordpress.com/2018/04/todec.pdf

On 2018-04-27 20:58, joe darcy wrote:
> 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

More information about the core-libs-dev mailing list