src/java.base/share/classes/java/lang/Double.java

*** 30,39 ****
--- 30,40 ----
  import java.lang.constant.ConstantDesc;
  import java.util.Optional;
  
  import jdk.internal.math.FloatingDecimal;
  import jdk.internal.math.DoubleConsts;
+ import jdk.internal.math.DoubleToDecimal;
  import jdk.internal.HotSpotIntrinsicCandidate;
  
  /**
   * The {@code Double} class wraps a value of the primitive type
   * {@code double} in an object. An object of type
*** 143,215 ****
       */
      @SuppressWarnings("unchecked")
      public static final Class<Double>   TYPE = (Class<Double>) Class.getPrimitiveClass("double");
  
      /**
!      * Returns a string representation of the {@code double}
!      * argument. All characters mentioned below are ASCII characters.
       * <ul>
!      * <li>If the argument is NaN, the result is the string
!      *     "{@code NaN}".
!      * <li>Otherwise, the result is a string that represents the sign and
!      * magnitude (absolute value) of the argument. If the sign is negative,
!      * the first character of the result is '{@code -}'
!      * ({@code '\u005Cu002D'}); if the sign is positive, no sign character
!      * appears in the result. As for the magnitude <i>m</i>:
       * <ul>
!      * <li>If <i>m</i> is infinity, it is represented by the characters
!      * {@code "Infinity"}; thus, positive infinity produces the result
!      * {@code "Infinity"} and negative infinity produces the result
!      * {@code "-Infinity"}.
!      *
!      * <li>If <i>m</i> is zero, it is represented by the characters
!      * {@code "0.0"}; thus, negative zero produces the result
!      * {@code "-0.0"} and positive zero produces the result
!      * {@code "0.0"}.
!      *
!      * <li>If <i>m</i> is greater than or equal to 10<sup>-3</sup> but less
!      * than 10<sup>7</sup>, then it is represented as the integer part of
!      * <i>m</i>, in decimal form with no leading zeroes, followed by
!      * '{@code .}' ({@code '\u005Cu002E'}), followed by one or
!      * more decimal digits representing the fractional part of <i>m</i>.
!      *
!      * <li>If <i>m</i> is less than 10<sup>-3</sup> or greater than or
!      * equal to 10<sup>7</sup>, then it is represented in so-called
!      * "computerized scientific notation." Let <i>n</i> be the unique
!      * integer such that 10<sup><i>n</i></sup> &le; <i>m</i> {@literal <}
!      * 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the
!      * mathematically exact quotient of <i>m</i> and
!      * 10<sup><i>n</i></sup> so that 1 &le; <i>a</i> {@literal <} 10. The
!      * magnitude is then represented as the integer part of <i>a</i>,
!      * as a single decimal digit, followed by '{@code .}'
!      * ({@code '\u005Cu002E'}), followed by decimal digits
!      * representing the fractional part of <i>a</i>, followed by the
!      * letter '{@code E}' ({@code '\u005Cu0045'}), followed
!      * by a representation of <i>n</i> as a decimal integer, as
!      * produced by the method {@link Integer#toString(int)}.
       * </ul>
       * </ul>
-      * How many digits must be printed for the fractional part of
-      * <i>m</i> or <i>a</i>? 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 {@code double}. That is, suppose that
-      * <i>x</i> is the exact mathematical value represented by the decimal
-      * representation produced by this method for a finite nonzero argument
-      * <i>d</i>. Then <i>d</i> must be the {@code double} value nearest
-      * to <i>x</i>; or if two {@code double} values are equally close
-      * to <i>x</i>, then <i>d</i> must be one of them and the least
-      * significant bit of the significand of <i>d</i> must be {@code 0}.
       *
!      * <p>To create localized string representations of a floating-point
!      * value, use subclasses of {@link java.text.NumberFormat}.
       *
!      * @param   d   the {@code double} to be converted.
!      * @return a string representation of the argument.
       */
!     public static String toString(double d) {
!         return FloatingDecimal.toJavaFormatString(d);
      }
  
      /**
       * Returns a hexadecimal string representation of the
       * {@code double} argument. All characters mentioned below
--- 144,267 ----
       */
      @SuppressWarnings("unchecked")
      public static final Class<Double>   TYPE = (Class<Double>) Class.getPrimitiveClass("double");
  
      /**
!      * Returns a string rendering of the {@code double} argument.
!      *
!      * <p>The characters of the result are all drawn from the ASCII set.
       * <ul>
!      * <li> Any NaN, whether quiet or signaling, is rendered as
!      * {@code "NaN"}, regardless of the sign bit.
!      * <li> The infinities +&infin; and -&infin; are rendered as
!      * {@code "Infinity"} and {@code "-Infinity"}, respectively.
!      * <li> The positive and negative zeroes are rendered as
!      * {@code "0.0"} and {@code "-0.0"}, respectively.
!      * <li> A finite negative {@code v} is rendered as the sign
!      * '{@code -}' followed by the rendering of the magnitude -{@code v}.
!      * <li> A finite positive {@code v} is rendered in two stages:
       * <ul>
!      * <li> <em>Selection of a decimal</em>: A well-defined
!      * decimal <i>d</i><sub><code>v</code></sub> is selected
!      * to represent {@code v}.
!      * <li> <em>Formatting as a string</em>: The decimal
!      * <i>d</i><sub><code>v</code></sub> is formatted as a string,
!      * either in plain or in computerized scientific notation,
!      * depending on its value.
       * </ul>
       * </ul>
       *
!      * <p>A <em>decimal</em> is a number of the form
!      * <i>d</i>&times;10<sup><i>i</i></sup>
!      * for some (unique) integers <i>d</i> &gt; 0 and <i>i</i> such that
!      * <i>d</i> is not a multiple of 10.
!      * These integers are the <em>significand</em> and
!      * the <em>exponent</em>, respectively, of the decimal.
!      * The <em>length</em> of the decimal is the (unique)
!      * integer <i>n</i> meeting
!      * 10<sup><i>n</i>-1</sup> &le; <i>d</i> &lt; 10<sup><i>n</i></sup>.
       *
!      * <p>The decimal <i>d</i><sub><code>v</code></sub>
!      * for a finite positive {@code v} is defined as follows:
!      * <ul>
!      * <li>Let <i>R</i> be the set of all decimals that round to {@code v}
!      * according to the usual round-to-closest rule of
!      * IEEE 754 floating-point arithmetic.
!      * <li>Let <i>m</i> be the minimal length over all decimals in <i>R</i>.
!      * <li>When <i>m</i> &ge; 2, let <i>T</i> be the set of all decimals
!      * in <i>R</i> with length <i>m</i>.
!      * Otherwise, let <i>T</i> be the set of all decimals
!      * in <i>R</i> with length 1 or 2.
!      * <li>Define <i>d</i><sub><code>v</code></sub> as
!      * the decimal in <i>T</i> that is closest to {@code v}.
!      * Or if there are two such decimals in <i>T</i>,
!      * select the one with the even significand (there is exactly one).
!      * </ul>
!      *
!      * <p>The (uniquely) selected decimal <i>d</i><sub><code>v</code></sub>
!      * is then formatted.
!      *
!      * <p>Let <i>d</i>, <i>i</i> and <i>n</i> be the significand, exponent and
!      * length of <i>d</i><sub><code>v</code></sub>, respectively.
!      * Further, let <i>e</i> = <i>n</i> + <i>i</i> - 1 and let
!      * <i>d</i><sub>1</sub>&hellip;<i>d</i><sub><i>n</i></sub>
!      * be the usual decimal expansion of the significand.
!      * Note that <i>d</i><sub>1</sub> &ne; 0 &ne; <i>d</i><sub><i>n</i></sub>.
!      * <ul>
!      * <li>Case -3 &le; <i>e</i> &lt; 0:
!      * <i>d</i><sub><code>v</code></sub> is formatted as
!      * <code>0.0</code>&hellip;<code>0</code><!--
!      * --><i>d</i><sub>1</sub>&hellip;<i>d</i><sub><i>n</i></sub>,
!      * where there are exactly -(<i>n</i> + <i>i</i>) zeroes between
!      * the decimal point and <i>d</i><sub>1</sub>.
!      * For example, 123 &times; 10<sup>-4</sup> is formatted as
!      * {@code 0.0123}.
!      * <li>Case 0 &le; <i>e</i> &lt; 7:
!      * <ul>
!      * <li>Subcase <i>i</i> &ge; 0:
!      * <i>d</i><sub><code>v</code></sub> is formatted as
!      * <i>d</i><sub>1</sub>&hellip;<i>d</i><sub><i>n</i></sub><!--
!      * --><code>0</code>&hellip;<code>0.0</code>,
!      * where there are exactly <i>i</i> zeroes
!      * between <i>d</i><sub><i>n</i></sub> and the decimal point.
!      * For example, 123 &times; 10<sup>2</sup> is formatted as
!      * {@code 12300.0}.
!      * <li>Subcase <i>i</i> &lt; 0:
!      * <i>d</i><sub><code>v</code></sub> is formatted as
!      * <i>d</i><sub>1</sub>&hellip;<!--
!      * --><i>d</i><sub><i>n</i>+<i>i</i></sub>.<!--
!      * --><i>d</i><sub><i>n</i>+<i>i</i>+1</sub>&hellip;<!--
!      * --><i>d</i><sub><i>n</i></sub>.
!      * There are exactly -<i>i</i> digits to the right of
!      * the decimal point.
!      * For example, 123 &times; 10<sup>-1</sup> is formatted as
!      * {@code 12.3}.
!      * </ul>
!      * <li>Case <i>e</i> &lt; -3 or <i>e</i> &ge; 7:
!      * computerized scientific notation is used to format
!      * <i>d</i><sub><code>v</code></sub>.
!      * Here <i>e</i> is formatted as by {@link Integer#toString(int)}.
!      * <ul>
!      * <li>Subcase <i>n</i> = 1:
!      * <i>d</i><sub><code>v</code></sub> is formatted as
!      * <i>d</i><sub>1</sub><code>.0E</code><i>e</i>.
!      * For example, 1 &times; 10<sup>23</sup> is formatted as
!      * {@code 1.0E23}.
!      * <li>Subcase <i>n</i> &gt; 1:
!      * <i>d</i><sub><code>v</code></sub> is formatted as
!      * <i>d</i><sub>1</sub><code>.</code><i>d</i><sub>2</sub><!--
!      * -->&hellip;<i>d</i><sub><i>n</i></sub><code>E</code><i>e</i>.
!      * For example, 123 &times; 10<sup>-21</sup> is formatted as
!      * {@code 1.23E-19}.
!      * </ul>
!      * </ul>
!      *
!      * @param v the {@code double} to be rendered.
!      * @return a string rendering of the argument.
       */
!     public static String toString(double v) {
!         return DoubleToDecimal.toString(v);
      }
  
      /**
       * Returns a hexadecimal string representation of the
       * {@code double} argument. All characters mentioned below