15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import java.lang.invoke.MethodHandles;
29 import java.lang.constant.Constable;
30 import java.lang.constant.ConstantDesc;
31 import java.util.Optional;
32
33 import jdk.internal.math.FloatingDecimal;
34 import jdk.internal.math.DoubleConsts;
35 import jdk.internal.HotSpotIntrinsicCandidate;
36
37 /**
38 * The {@code Double} class wraps a value of the primitive type
39 * {@code double} in an object. An object of type
40 * {@code Double} contains a single field whose type is
41 * {@code double}.
42 *
43 * <p>In addition, this class provides several methods for converting a
44 * {@code double} to a {@code String} and a
45 * {@code String} to a {@code double}, as well as other
46 * constants and methods useful when dealing with a
47 * {@code double}.
48 *
49 * @author Lee Boynton
50 * @author Arthur van Hoff
51 * @author Joseph D. Darcy
52 * @since 1.0
53 */
54 public final class Double extends Number
128 */
129 public static final int SIZE = 64;
130
131 /**
132 * The number of bytes used to represent a {@code double} value.
133 *
134 * @since 1.8
135 */
136 public static final int BYTES = SIZE / Byte.SIZE;
137
138 /**
139 * The {@code Class} instance representing the primitive type
140 * {@code double}.
141 *
142 * @since 1.1
143 */
144 @SuppressWarnings("unchecked")
145 public static final Class<Double> TYPE = (Class<Double>) Class.getPrimitiveClass("double");
146
147 /**
148 * Returns a string representation of the {@code double}
149 * argument. All characters mentioned below are ASCII characters.
150 * <ul>
151 * <li>If the argument is NaN, the result is the string
152 * "{@code NaN}".
153 * <li>Otherwise, the result is a string that represents the sign and
154 * magnitude (absolute value) of the argument. If the sign is negative,
155 * the first character of the result is '{@code -}'
156 * ({@code '\u005Cu002D'}); if the sign is positive, no sign character
157 * appears in the result. As for the magnitude <i>m</i>:
158 * <ul>
159 * <li>If <i>m</i> is infinity, it is represented by the characters
160 * {@code "Infinity"}; thus, positive infinity produces the result
161 * {@code "Infinity"} and negative infinity produces the result
162 * {@code "-Infinity"}.
163 *
164 * <li>If <i>m</i> is zero, it is represented by the characters
165 * {@code "0.0"}; thus, negative zero produces the result
166 * {@code "-0.0"} and positive zero produces the result
167 * {@code "0.0"}.
168 *
169 * <li>If <i>m</i> is greater than or equal to 10<sup>-3</sup> but less
170 * than 10<sup>7</sup>, then it is represented as the integer part of
171 * <i>m</i>, in decimal form with no leading zeroes, followed by
172 * '{@code .}' ({@code '\u005Cu002E'}), followed by one or
173 * more decimal digits representing the fractional part of <i>m</i>.
174 *
175 * <li>If <i>m</i> is less than 10<sup>-3</sup> or greater than or
176 * equal to 10<sup>7</sup>, then it is represented in so-called
177 * "computerized scientific notation." Let <i>n</i> be the unique
178 * integer such that 10<sup><i>n</i></sup> ≤ <i>m</i> {@literal <}
179 * 10<sup><i>n</i>+1</sup>; then let <i>a</i> be the
180 * mathematically exact quotient of <i>m</i> and
181 * 10<sup><i>n</i></sup> so that 1 ≤ <i>a</i> {@literal <} 10. The
182 * magnitude is then represented as the integer part of <i>a</i>,
183 * as a single decimal digit, followed by '{@code .}'
184 * ({@code '\u005Cu002E'}), followed by decimal digits
185 * representing the fractional part of <i>a</i>, followed by the
186 * letter '{@code E}' ({@code '\u005Cu0045'}), followed
187 * by a representation of <i>n</i> as a decimal integer, as
188 * produced by the method {@link Integer#toString(int)}.
189 * </ul>
190 * </ul>
191 * How many digits must be printed for the fractional part of
192 * <i>m</i> or <i>a</i>? There must be at least one digit to represent
193 * the fractional part, and beyond that as many, but only as many, more
194 * digits as are needed to uniquely distinguish the argument value from
195 * adjacent values of type {@code double}. That is, suppose that
196 * <i>x</i> is the exact mathematical value represented by the decimal
197 * representation produced by this method for a finite nonzero argument
198 * <i>d</i>. Then <i>d</i> must be the {@code double} value nearest
199 * to <i>x</i>; or if two {@code double} values are equally close
200 * to <i>x</i>, then <i>d</i> must be one of them and the least
201 * significant bit of the significand of <i>d</i> must be {@code 0}.
202 *
203 * <p>To create localized string representations of a floating-point
204 * value, use subclasses of {@link java.text.NumberFormat}.
205 *
206 * @param d the {@code double} to be converted.
207 * @return a string representation of the argument.
208 */
209 public static String toString(double d) {
210 return FloatingDecimal.toJavaFormatString(d);
211 }
212
213 /**
214 * Returns a hexadecimal string representation of the
215 * {@code double} argument. All characters mentioned below
216 * are ASCII characters.
217 *
218 * <ul>
219 * <li>If the argument is NaN, the result is the string
220 * "{@code NaN}".
221 * <li>Otherwise, the result is a string that represents the sign
222 * and magnitude of the argument. If the sign is negative, the
223 * first character of the result is '{@code -}'
224 * ({@code '\u005Cu002D'}); if the sign is positive, no sign
225 * character appears in the result. As for the magnitude <i>m</i>:
226 *
227 * <ul>
228 * <li>If <i>m</i> is infinity, it is represented by the string
229 * {@code "Infinity"}; thus, positive infinity produces the
230 * result {@code "Infinity"} and negative infinity produces
|
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import java.lang.invoke.MethodHandles;
29 import java.lang.constant.Constable;
30 import java.lang.constant.ConstantDesc;
31 import java.util.Optional;
32
33 import jdk.internal.math.FloatingDecimal;
34 import jdk.internal.math.DoubleConsts;
35 import jdk.internal.math.DoubleToDecimal;
36 import jdk.internal.HotSpotIntrinsicCandidate;
37
38 /**
39 * The {@code Double} class wraps a value of the primitive type
40 * {@code double} in an object. An object of type
41 * {@code Double} contains a single field whose type is
42 * {@code double}.
43 *
44 * <p>In addition, this class provides several methods for converting a
45 * {@code double} to a {@code String} and a
46 * {@code String} to a {@code double}, as well as other
47 * constants and methods useful when dealing with a
48 * {@code double}.
49 *
50 * @author Lee Boynton
51 * @author Arthur van Hoff
52 * @author Joseph D. Darcy
53 * @since 1.0
54 */
55 public final class Double extends Number
129 */
130 public static final int SIZE = 64;
131
132 /**
133 * The number of bytes used to represent a {@code double} value.
134 *
135 * @since 1.8
136 */
137 public static final int BYTES = SIZE / Byte.SIZE;
138
139 /**
140 * The {@code Class} instance representing the primitive type
141 * {@code double}.
142 *
143 * @since 1.1
144 */
145 @SuppressWarnings("unchecked")
146 public static final Class<Double> TYPE = (Class<Double>) Class.getPrimitiveClass("double");
147
148 /**
149 * Returns a string rendering of the {@code double} argument.
150 *
151 * <p>The characters of the result are all drawn from the ASCII set.
152 * <ul>
153 * <li> Any NaN, whether quiet or signaling, is rendered as
154 * {@code "NaN"}, regardless of the sign bit.
155 * <li> The infinities +∞ and -∞ are rendered as
156 * {@code "Infinity"} and {@code "-Infinity"}, respectively.
157 * <li> The positive and negative zeroes are rendered as
158 * {@code "0.0"} and {@code "-0.0"}, respectively.
159 * <li> A finite negative {@code v} is rendered as the sign
160 * '{@code -}' followed by the rendering of the magnitude -{@code v}.
161 * <li> A finite positive {@code v} is rendered in two stages:
162 * <ul>
163 * <li> <em>Selection of a decimal</em>: A well-defined
164 * decimal <i>d</i><sub><code>v</code></sub> is selected
165 * to represent {@code v}.
166 * <li> <em>Formatting as a string</em>: The decimal
167 * <i>d</i><sub><code>v</code></sub> is formatted as a string,
168 * either in plain or in computerized scientific notation,
169 * depending on its value.
170 * </ul>
171 * </ul>
172 *
173 * <p>A <em>decimal</em> is a number of the form
174 * <i>d</i>×10<sup><i>i</i></sup>
175 * for some (unique) integers <i>d</i> > 0 and <i>i</i> such that
176 * <i>d</i> is not a multiple of 10.
177 * These integers are the <em>significand</em> and
178 * the <em>exponent</em>, respectively, of the decimal.
179 * The <em>length</em> of the decimal is the (unique)
180 * integer <i>n</i> meeting
181 * 10<sup><i>n</i>-1</sup> ≤ <i>d</i> < 10<sup><i>n</i></sup>.
182 *
183 * <p>The decimal <i>d</i><sub><code>v</code></sub>
184 * for a finite positive {@code v} is defined as follows:
185 * <ul>
186 * <li>Let <i>R</i> be the set of all decimals that round to {@code v}
187 * according to the usual round-to-closest rule of
188 * IEEE 754 floating-point arithmetic.
189 * <li>Let <i>m</i> be the minimal length over all decimals in <i>R</i>.
190 * <li>When <i>m</i> ≥ 2, let <i>T</i> be the set of all decimals
191 * in <i>R</i> with length <i>m</i>.
192 * Otherwise, let <i>T</i> be the set of all decimals
193 * in <i>R</i> with length 1 or 2.
194 * <li>Define <i>d</i><sub><code>v</code></sub> as
195 * the decimal in <i>T</i> that is closest to {@code v}.
196 * Or if there are two such decimals in <i>T</i>,
197 * select the one with the even significand (there is exactly one).
198 * </ul>
199 *
200 * <p>The (uniquely) selected decimal <i>d</i><sub><code>v</code></sub>
201 * is then formatted.
202 *
203 * <p>Let <i>d</i>, <i>i</i> and <i>n</i> be the significand, exponent and
204 * length of <i>d</i><sub><code>v</code></sub>, respectively.
205 * Further, let <i>e</i> = <i>n</i> + <i>i</i> - 1 and let
206 * <i>d</i><sub>1</sub>…<i>d</i><sub><i>n</i></sub>
207 * be the usual decimal expansion of the significand.
208 * Note that <i>d</i><sub>1</sub> ≠ 0 ≠ <i>d</i><sub><i>n</i></sub>.
209 * <ul>
210 * <li>Case -3 ≤ <i>e</i> < 0:
211 * <i>d</i><sub><code>v</code></sub> is formatted as
212 * <code>0.0</code>…<code>0</code><!--
213 * --><i>d</i><sub>1</sub>…<i>d</i><sub><i>n</i></sub>,
214 * where there are exactly -(<i>n</i> + <i>i</i>) zeroes between
215 * the decimal point and <i>d</i><sub>1</sub>.
216 * For example, 123 × 10<sup>-4</sup> is formatted as
217 * {@code 0.0123}.
218 * <li>Case 0 ≤ <i>e</i> < 7:
219 * <ul>
220 * <li>Subcase <i>i</i> ≥ 0:
221 * <i>d</i><sub><code>v</code></sub> is formatted as
222 * <i>d</i><sub>1</sub>…<i>d</i><sub><i>n</i></sub><!--
223 * --><code>0</code>…<code>0.0</code>,
224 * where there are exactly <i>i</i> zeroes
225 * between <i>d</i><sub><i>n</i></sub> and the decimal point.
226 * For example, 123 × 10<sup>2</sup> is formatted as
227 * {@code 12300.0}.
228 * <li>Subcase <i>i</i> < 0:
229 * <i>d</i><sub><code>v</code></sub> is formatted as
230 * <i>d</i><sub>1</sub>…<!--
231 * --><i>d</i><sub><i>n</i>+<i>i</i></sub>.<!--
232 * --><i>d</i><sub><i>n</i>+<i>i</i>+1</sub>…<!--
233 * --><i>d</i><sub><i>n</i></sub>.
234 * There are exactly -<i>i</i> digits to the right of
235 * the decimal point.
236 * For example, 123 × 10<sup>-1</sup> is formatted as
237 * {@code 12.3}.
238 * </ul>
239 * <li>Case <i>e</i> < -3 or <i>e</i> ≥ 7:
240 * computerized scientific notation is used to format
241 * <i>d</i><sub><code>v</code></sub>.
242 * Here <i>e</i> is formatted as by {@link Integer#toString(int)}.
243 * <ul>
244 * <li>Subcase <i>n</i> = 1:
245 * <i>d</i><sub><code>v</code></sub> is formatted as
246 * <i>d</i><sub>1</sub><code>.0E</code><i>e</i>.
247 * For example, 1 × 10<sup>23</sup> is formatted as
248 * {@code 1.0E23}.
249 * <li>Subcase <i>n</i> > 1:
250 * <i>d</i><sub><code>v</code></sub> is formatted as
251 * <i>d</i><sub>1</sub><code>.</code><i>d</i><sub>2</sub><!--
252 * -->…<i>d</i><sub><i>n</i></sub><code>E</code><i>e</i>.
253 * For example, 123 × 10<sup>-21</sup> is formatted as
254 * {@code 1.23E-19}.
255 * </ul>
256 * </ul>
257 *
258 * @param v the {@code double} to be rendered.
259 * @return a string rendering of the argument.
260 */
261 public static String toString(double v) {
262 return DoubleToDecimal.toString(v);
263 }
264
265 /**
266 * Returns a hexadecimal string representation of the
267 * {@code double} argument. All characters mentioned below
268 * are ASCII characters.
269 *
270 * <ul>
271 * <li>If the argument is NaN, the result is the string
272 * "{@code NaN}".
273 * <li>Otherwise, the result is a string that represents the sign
274 * and magnitude of the argument. If the sign is negative, the
275 * first character of the result is '{@code -}'
276 * ({@code '\u005Cu002D'}); if the sign is positive, no sign
277 * character appears in the result. As for the magnitude <i>m</i>:
278 *
279 * <ul>
280 * <li>If <i>m</i> is infinity, it is represented by the string
281 * {@code "Infinity"}; thus, positive infinity produces the
282 * result {@code "Infinity"} and negative infinity produces
|