< prev index next >
src/java.base/share/classes/java/lang/Double.java
Print this page
@@ -23,10 +23,11 @@
* questions.
*/
package java.lang;
+import jdk.internal.math.DoubleToDecimal;
import jdk.internal.math.FloatingDecimal;
import jdk.internal.math.DoubleConsts;
import jdk.internal.HotSpotIntrinsicCandidate;
/**
@@ -137,73 +138,112 @@
*/
@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.
+ * Returns a string rendering of the {@code double} argument.
+ *
+ * <p>The characters of the result are all drawn from the ASCII set.
* <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>:
+ * <li> Any NaN, whether quiet or signaling, is rendered symbolically
+ * as {@code "NaN"}, regardless of the sign bit.
+ * <li> The infinities +∞ and -∞ 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> Otherwise {@code v} is finite and non-zero.
+ * It is rendered in two stages:
* <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> ≤ <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 ≤ <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)}.
+ * <li> <em>Selection of a decimal</em>: A well-specified non-zero
+ * decimal <i>d</i> is selected to represent {@code v}.
+ * <li> <em>Formatting as a string</em>: The decimal <i>d</i> is
+ * formatted as a string, either in plain or in computerized
+ * scientific notation, depending on its value.
* </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}.
+ * <p>The selected decimal <i>d</i> has a length <i>n</i> if it can be
+ * written as <i>d</i> = <i>c</i>·10<sup><i>q</i></sup> for some
+ * integers <i>q</i> and <i>c</i> meeting 10<sup><i>n</i>-1</sup> ≤
+ * |<i>c</i>| < 10<sup><i>n</i></sup>. It has all the following
+ * properties:
+ * <ul>
+ * <li> It rounds to {@code v} according to the usual round-to-closest
+ * rule of IEEE 754 floating-point arithmetic.
+ * <li> Among the decimals above, it has a length of 2 or more.
+ * <li> Among all such decimals, it is one of those with the shortest
+ * length.
+ * <li> Among the latter ones, it is the one closest to {@code v}. Or
+ * if there are two that are equally close to {@code v}, it is the one
+ * whose least significant digit is even.
+ * </ul>
+ * More formally, let <i>d'</i> = <i>c'</i>·10<sup><i>q'</i></sup>
+ * ≠ <i>d</i> be any other decimal that rounds to {@code v} according to
+ * IEEE 754 and of a length <i>n'</i>. Then:
+ * <ul>
+ * <li> either <i>n'</i> = 1, thus <i>d'</i> is too short;
+ * <li> or <i>n'</i> > <i>n</i>, thus <i>d'</i> is too long;
+ * <li> or <i>n'</i> = <i>n</i> and
+ * <ul>
+ * <li> either |<i>d</i> - {@code v}| < |<i>d'</i> - {@code v}|:
+ * thus <i>d'</i> is farther from {@code v};
+ * <li> or |<i>d</i> - {@code v}| = |<i>d'</i> - {@code v}| and
+ * <i>c</i> is even while <i>c'</i> is odd
+ * </ul>
+ * </ul>
*
- * @param d the {@code double} to be converted.
- * @return a string representation of the argument.
+ * <p>The selected decimal <i>d</i> is then formatted as a string.
+ * If <i>d</i> < 0, the first character of the string is the sign
+ * '{@code -}'. Let |<i>d</i>| = <i>m</i>·10<sup><i>k</i></sup>,
+ * for the unique pair of integer <i>k</i> and real <i>m</i> meeting
+ * 1 ≤ <i>m</i> < 10. Also, let the decimal expansion of <i>m</i> be
+ * <i>m</i><sub>1</sub> . <i>m</i><sub>2</sub> <!--
+ * -->… <i>m</i><sub><i>i</i></sub>,
+ * with <i>i</i> ≥ 1 and <i>m</i><sub><i>i</i></sub> ≠ 0.
+ * <ul>
+ * <li>Case -3 ≤ k < 0: |<i>d</i>| is formatted as
+ * 0 . 0…0<i>m</i><sub>1</sub>…<!--
+ * --><i>m</i><sub><i>i</i></sub>,
+ * where there are exactly -<i>k</i> leading zeroes before
+ * <i>m</i><sub>1</sub>, including the zero to the left of the
+ * decimal point; for example, {@code "0.01234"}.
+ * <li>Case 0 ≤ <i>k</i> < 7:
+ * <ul>
+ * <li>Subcase <i>i</i> < <i>k</i> + 2:
+ * |<i>d</i>| is formatted as
+ * <i>m</i><sub>1</sub>…<!--
+ * --><i>m</i><sub><i>i</i></sub>0…0 . 0,
+ * where there are exactly <i>k</i> + 2 - <i>i</i> trailing zeroes
+ * after <i>m</i><sub><i>i</i></sub>, including the zero to the
+ * right of the decimal point; for example, {@code "1200.0"}.
+ * <li>Subcase <i>i</i> ≥ <i>k</i> + 2:
+ * |<i>d</i>| is formatted as <i>m</i><sub>1</sub>…<!--
+ * --><i>m</i><sub><i>k</i>+1</sub> . <!--
+ * --><i>m</i><sub><i>k</i>+2</sub>…<!--
+ * --><i>m</i><sub><i>i</i></sub>; for example, {@code "1234.32"}.
+ * </ul>
+ * <li>Case <i>k</i> < -3 or <i>k</i> ≥ 7:
+ * computerized scientific notation is used to format |<i>d</i>|,
+ * by combining <i>m</i> and <i>k</i> separated by the exponent
+ * indicator '{@code E}'. The exponent <i>k</i> is formatted as in
+ * {@link Integer#toString(int)}.
+ * <ul>
+ * <li>Subcase <i>i</i> = 1: |<i>d</i>| is formatted as
+ * <i>m</i><sub>1</sub> . 0E<i>k</i>;
+ * for example, {@code "2.0E23"}.
+ * <li>Subcase <i>i</i> > 1: |<i>d</i>| is formatted as
+ * <i>m</i><sub>1</sub> . <i>m</i><sub>2</sub><!--
+ * -->…<i>m</i><sub><i>i</i></sub>E<i>k</i>;
+ * for example, {@code "1.234E-32"}.
+ * </ul>
+ * </ul>
+ *
+ * @param v the {@code double} to be rendered.
+ * @return a string rendering of the argument.
*/
- public static String toString(double d) {
- return FloatingDecimal.toJavaFormatString(d);
+ public static String toString(double v) {
+ return DoubleToDecimal.toString(v);
}
/**
* Returns a hexadecimal string representation of the
* {@code double} argument. All characters mentioned below
< prev index next >