< prev index next >
src/java.base/share/classes/java/lang/Float.java
Print this page
@@ -29,10 +29,11 @@
import java.lang.constant.Constable;
import java.lang.constant.ConstantDesc;
import java.util.Optional;
import jdk.internal.math.FloatingDecimal;
+import jdk.internal.math.FloatToDecimal;
import jdk.internal.HotSpotIntrinsicCandidate;
/**
* The {@code Float} class wraps a value of primitive type
* {@code float} in an object. An object of type
@@ -140,77 +141,124 @@
*/
@SuppressWarnings("unchecked")
public static final Class<Float> TYPE = (Class<Float>) Class.getPrimitiveClass("float");
/**
- * Returns a string representation of the {@code float}
- * argument. All characters mentioned below are ASCII characters.
+ * Returns a string rendering of the {@code float} 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 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> 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>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 java.lang.Integer#toString(int)}.
- *
+ * <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>×10<sup><i>i</i></sup>
+ * for some (unique) integers <i>d</i> > 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> ≤ <i>d</i> < 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> ≥ 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>
- * 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 float}. 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>f</i>. Then <i>f</i> must be the {@code float}
- * value nearest to <i>x</i>; or, if two {@code float} values are
- * equally close to <i>x</i>, then <i>f</i> must be one of
- * them and the least significant bit of the significand of
- * <i>f</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 (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>…<i>d</i><sub><i>n</i></sub>
+ * be the usual decimal expansion of the significand.
+ * Note that <i>d</i><sub>1</sub> ≠ 0 ≠ <i>d</i><sub><i>n</i></sub>.
+ * <ul>
+ * <li>Case -3 ≤ <i>e</i> < 0:
+ * <i>d</i><sub><code>v</code></sub> is formatted as
+ * <code>0.0</code>…<code>0</code><!--
+ * --><i>d</i><sub>1</sub>…<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 × 10<sup>-4</sup> is formatted as
+ * {@code 0.0123}.
+ * <li>Case 0 ≤ <i>e</i> < 7:
+ * <ul>
+ * <li>Subcase <i>i</i> ≥ 0:
+ * <i>d</i><sub><code>v</code></sub> is formatted as
+ * <i>d</i><sub>1</sub>…<i>d</i><sub><i>n</i></sub><!--
+ * --><code>0</code>…<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 × 10<sup>2</sup> is formatted as
+ * {@code 12300.0}.
+ * <li>Subcase <i>i</i> < 0:
+ * <i>d</i><sub><code>v</code></sub> is formatted as
+ * <i>d</i><sub>1</sub>…<!--
+ * --><i>d</i><sub><i>n</i>+<i>i</i></sub>.<!--
+ * --><i>d</i><sub><i>n</i>+<i>i</i>+1</sub>…<!--
+ * --><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 × 10<sup>-1</sup> is formatted as
+ * {@code 12.3}.
+ * </ul>
+ * <li>Case <i>e</i> < -3 or <i>e</i> ≥ 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 × 10<sup>23</sup> is formatted as
+ * {@code 1.0E23}.
+ * <li>Subcase <i>n</i> > 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><!--
+ * -->…<i>d</i><sub><i>n</i></sub><code>E</code><i>e</i>.
+ * For example, 123 × 10<sup>-21</sup> is formatted as
+ * {@code 1.23E-19}.
+ * </ul>
+ * </ul>
*
- * @param f the float to be converted.
- * @return a string representation of the argument.
+ * @param v the {@code float} to be rendered.
+ * @return a string rendering of the argument.
*/
- public static String toString(float f) {
- return FloatingDecimal.toJavaFormatString(f);
+ public static String toString(float v) {
+ return FloatToDecimal.toString(v);
}
/**
* Returns a hexadecimal string representation of the
* {@code float} argument. All characters mentioned below are
< prev index next >