1 /*
2 * Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
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.FloatToDecimal;
35 import jdk.internal.HotSpotIntrinsicCandidate;
36
37 /**
38 * The {@code Float} class wraps a value of primitive type
39 * {@code float} in an object. An object of type
40 * {@code Float} contains a single field whose type is
41 * {@code float}.
42 *
43 * <p>In addition, this class provides several methods for converting a
44 * {@code float} to a {@code String} and a
45 * {@code String} to a {@code float}, as well as other
46 * constants and methods useful when dealing with a
47 * {@code float}.
48 *
49 * @author Lee Boynton
50 * @author Arthur van Hoff
51 * @author Joseph D. Darcy
52 * @since 1.0
53 */
54 public final class Float extends Number
55 implements Comparable<Float>, Constable, ConstantDesc {
56 /**
57 * A constant holding the positive infinity of type
58 * {@code float}. It is equal to the value returned by
59 * {@code Float.intBitsToFloat(0x7f800000)}.
60 */
61 public static final float POSITIVE_INFINITY = 1.0f / 0.0f;
62
63 /**
64 * A constant holding the negative infinity of type
65 * {@code float}. It is equal to the value returned by
66 * {@code Float.intBitsToFloat(0xff800000)}.
67 */
68 public static final float NEGATIVE_INFINITY = -1.0f / 0.0f;
69
70 /**
71 * A constant holding a Not-a-Number (NaN) value of type
72 * {@code float}. It is equivalent to the value returned by
73 * {@code Float.intBitsToFloat(0x7fc00000)}.
74 */
75 public static final float NaN = 0.0f / 0.0f;
76
77 /**
78 * A constant holding the largest positive finite value of type
79 * {@code float}, (2-2<sup>-23</sup>)·2<sup>127</sup>.
80 * It is equal to the hexadecimal floating-point literal
81 * {@code 0x1.fffffeP+127f} and also equal to
82 * {@code Float.intBitsToFloat(0x7f7fffff)}.
83 */
84 public static final float MAX_VALUE = 0x1.fffffeP+127f; // 3.4028235e+38f
85
86 /**
87 * A constant holding the smallest positive normal value of type
88 * {@code float}, 2<sup>-126</sup>. It is equal to the
89 * hexadecimal floating-point literal {@code 0x1.0p-126f} and also
90 * equal to {@code Float.intBitsToFloat(0x00800000)}.
91 *
92 * @since 1.6
93 */
94 public static final float MIN_NORMAL = 0x1.0p-126f; // 1.17549435E-38f
95
96 /**
97 * A constant holding the smallest positive nonzero value of type
98 * {@code float}, 2<sup>-149</sup>. It is equal to the
99 * hexadecimal floating-point literal {@code 0x0.000002P-126f}
100 * and also equal to {@code Float.intBitsToFloat(0x1)}.
101 */
102 public static final float MIN_VALUE = 0x0.000002P-126f; // 1.4e-45f
103
104 /**
105 * Maximum exponent a finite {@code float} variable may have. It
106 * is equal to the value returned by {@code
107 * Math.getExponent(Float.MAX_VALUE)}.
108 *
109 * @since 1.6
110 */
111 public static final int MAX_EXPONENT = 127;
112
113 /**
114 * Minimum exponent a normalized {@code float} variable may have.
115 * It is equal to the value returned by {@code
116 * Math.getExponent(Float.MIN_NORMAL)}.
117 *
118 * @since 1.6
119 */
120 public static final int MIN_EXPONENT = -126;
121
122 /**
123 * The number of bits used to represent a {@code float} value.
124 *
125 * @since 1.5
126 */
127 public static final int SIZE = 32;
128
129 /**
130 * The number of bytes used to represent a {@code float} value.
131 *
132 * @since 1.8
133 */
134 public static final int BYTES = SIZE / Byte.SIZE;
135
136 /**
137 * The {@code Class} instance representing the primitive type
138 * {@code float}.
139 *
140 * @since 1.1
141 */
142 @SuppressWarnings("unchecked")
143 public static final Class<Float> TYPE = (Class<Float>) Class.getPrimitiveClass("float");
144
145 /**
146 * Returns a string rendering of the {@code float} argument.
147 *
148 * <p>The characters of the result are all drawn from the ASCII set.
149 * <ul>
150 * <li> Any NaN, whether quiet or signaling, is rendered as
151 * {@code "NaN"}, regardless of the sign bit.
152 * <li> The infinities +∞ and -∞ are rendered as
153 * {@code "Infinity"} and {@code "-Infinity"}, respectively.
154 * <li> The positive and negative zeroes are rendered as
155 * {@code "0.0"} and {@code "-0.0"}, respectively.
156 * <li> A finite negative {@code v} is rendered as the sign
157 * '{@code -}' followed by the rendering of the magnitude -{@code v}.
158 * <li> A finite positive {@code v} is rendered in two stages:
159 * <ul>
160 * <li> <em>Selection of a decimal</em>: A well-defined
161 * decimal <i>d</i><sub><code>v</code></sub> is selected
162 * to represent {@code v}.
163 * <li> <em>Formatting as a string</em>: The decimal
164 * <i>d</i><sub><code>v</code></sub> is formatted as a string,
165 * either in plain or in computerized scientific notation,
166 * depending on its value.
167 * </ul>
168 * </ul>
169 *
170 * <p>A <em>decimal</em> is a number of the form
171 * <i>d</i>×10<sup><i>i</i></sup>
172 * for some (unique) integers <i>d</i> > 0 and <i>i</i> such that
173 * <i>d</i> is not a multiple of 10.
174 * These integers are the <em>significand</em> and
175 * the <em>exponent</em>, respectively, of the decimal.
176 * The <em>length</em> of the decimal is the (unique)
177 * integer <i>n</i> meeting
178 * 10<sup><i>n</i>-1</sup> ≤ <i>d</i> < 10<sup><i>n</i></sup>.
179 *
180 * <p>The decimal <i>d</i><sub><code>v</code></sub>
181 * for a finite positive {@code v} is defined as follows:
182 * <ul>
183 * <li>Let <i>R</i> be the set of all decimals that round to {@code v}
184 * according to the usual round-to-closest rule of
185 * IEEE 754 floating-point arithmetic.
186 * <li>Let <i>m</i> be the minimal length over all decimals in <i>R</i>.
187 * <li>When <i>m</i> ≥ 2, let <i>T</i> be the set of all decimals
188 * in <i>R</i> with length <i>m</i>.
189 * Otherwise, let <i>T</i> be the set of all decimals
190 * in <i>R</i> with length 1 or 2.
191 * <li>Define <i>d</i><sub><code>v</code></sub> as
192 * the decimal in <i>T</i> that is closest to {@code v}.
193 * Or if there are two such decimals in <i>T</i>,
194 * select the one with the even significand (there is exactly one).
195 * </ul>
196 *
197 * <p>The (uniquely) selected decimal <i>d</i><sub><code>v</code></sub>
198 * is then formatted.
199 *
200 * <p>Let <i>d</i>, <i>i</i> and <i>n</i> be the significand, exponent and
201 * length of <i>d</i><sub><code>v</code></sub>, respectively.
202 * Further, let <i>e</i> = <i>n</i> + <i>i</i> - 1 and let
203 * <i>d</i><sub>1</sub>…<i>d</i><sub><i>n</i></sub>
204 * be the usual decimal expansion of the significand.
205 * Note that <i>d</i><sub>1</sub> ≠ 0 ≠ <i>d</i><sub><i>n</i></sub>.
206 * <ul>
207 * <li>Case -3 ≤ <i>e</i> < 0:
208 * <i>d</i><sub><code>v</code></sub> is formatted as
209 * <code>0.0</code>…<code>0</code><!--
210 * --><i>d</i><sub>1</sub>…<i>d</i><sub><i>n</i></sub>,
211 * where there are exactly -(<i>n</i> + <i>i</i>) zeroes between
212 * the decimal point and <i>d</i><sub>1</sub>.
213 * For example, 123 × 10<sup>-4</sup> is formatted as
214 * {@code 0.0123}.
215 * <li>Case 0 ≤ <i>e</i> < 7:
216 * <ul>
217 * <li>Subcase <i>i</i> ≥ 0:
218 * <i>d</i><sub><code>v</code></sub> is formatted as
219 * <i>d</i><sub>1</sub>…<i>d</i><sub><i>n</i></sub><!--
220 * --><code>0</code>…<code>0.0</code>,
221 * where there are exactly <i>i</i> zeroes
222 * between <i>d</i><sub><i>n</i></sub> and the decimal point.
223 * For example, 123 × 10<sup>2</sup> is formatted as
224 * {@code 12300.0}.
225 * <li>Subcase <i>i</i> < 0:
226 * <i>d</i><sub><code>v</code></sub> is formatted as
227 * <i>d</i><sub>1</sub>…<!--
228 * --><i>d</i><sub><i>n</i>+<i>i</i></sub>.<!--
229 * --><i>d</i><sub><i>n</i>+<i>i</i>+1</sub>…<!--
230 * --><i>d</i><sub><i>n</i></sub>.
231 * There are exactly -<i>i</i> digits to the right of
232 * the decimal point.
233 * For example, 123 × 10<sup>-1</sup> is formatted as
234 * {@code 12.3}.
235 * </ul>
236 * <li>Case <i>e</i> < -3 or <i>e</i> ≥ 7:
237 * computerized scientific notation is used to format
238 * <i>d</i><sub><code>v</code></sub>.
239 * Here <i>e</i> is formatted as by {@link Integer#toString(int)}.
240 * <ul>
241 * <li>Subcase <i>n</i> = 1:
242 * <i>d</i><sub><code>v</code></sub> is formatted as
243 * <i>d</i><sub>1</sub><code>.0E</code><i>e</i>.
244 * For example, 1 × 10<sup>23</sup> is formatted as
245 * {@code 1.0E23}.
246 * <li>Subcase <i>n</i> > 1:
247 * <i>d</i><sub><code>v</code></sub> is formatted as
248 * <i>d</i><sub>1</sub><code>.</code><i>d</i><sub>2</sub><!--
249 * -->…<i>d</i><sub><i>n</i></sub><code>E</code><i>e</i>.
250 * For example, 123 × 10<sup>-21</sup> is formatted as
251 * {@code 1.23E-19}.
252 * </ul>
253 * </ul>
254 *
255 * @param v the {@code float} to be rendered.
256 * @return a string rendering of the argument.
257 */
258 public static String toString(float v) {
259 return FloatToDecimal.toString(v);
260 }
261
262 /**
263 * Returns a hexadecimal string representation of the
264 * {@code float} argument. All characters mentioned below are
265 * ASCII characters.
266 *
267 * <ul>
268 * <li>If the argument is NaN, the result is the string
269 * "{@code NaN}".
270 * <li>Otherwise, the result is a string that represents the sign and
271 * magnitude (absolute value) of the argument. If the sign is negative,
272 * the first character of the result is '{@code -}'
273 * ({@code '\u005Cu002D'}); if the sign is positive, no sign character
274 * appears in the result. As for the magnitude <i>m</i>:
275 *
276 * <ul>
277 * <li>If <i>m</i> is infinity, it is represented by the string
278 * {@code "Infinity"}; thus, positive infinity produces the
279 * result {@code "Infinity"} and negative infinity produces
280 * the result {@code "-Infinity"}.
281 *
282 * <li>If <i>m</i> is zero, it is represented by the string
283 * {@code "0x0.0p0"}; thus, negative zero produces the result
284 * {@code "-0x0.0p0"} and positive zero produces the result
285 * {@code "0x0.0p0"}.
286 *
287 * <li>If <i>m</i> is a {@code float} value with a
288 * normalized representation, substrings are used to represent the
289 * significand and exponent fields. The significand is
290 * represented by the characters {@code "0x1."}
291 * followed by a lowercase hexadecimal representation of the rest
292 * of the significand as a fraction. Trailing zeros in the
293 * hexadecimal representation are removed unless all the digits
294 * are zero, in which case a single zero is used. Next, the
295 * exponent is represented by {@code "p"} followed
296 * by a decimal string of the unbiased exponent as if produced by
297 * a call to {@link Integer#toString(int) Integer.toString} on the
298 * exponent value.
299 *
300 * <li>If <i>m</i> is a {@code float} value with a subnormal
301 * representation, the significand is represented by the
302 * characters {@code "0x0."} followed by a
303 * hexadecimal representation of the rest of the significand as a
304 * fraction. Trailing zeros in the hexadecimal representation are
305 * removed. Next, the exponent is represented by
306 * {@code "p-126"}. Note that there must be at
307 * least one nonzero digit in a subnormal significand.
308 *
309 * </ul>
310 *
311 * </ul>
312 *
313 * <table class="striped">
314 * <caption>Examples</caption>
315 * <thead>
316 * <tr><th scope="col">Floating-point Value</th><th scope="col">Hexadecimal String</th>
317 * </thead>
318 * <tbody>
319 * <tr><th scope="row">{@code 1.0}</th> <td>{@code 0x1.0p0}</td>
320 * <tr><th scope="row">{@code -1.0}</th> <td>{@code -0x1.0p0}</td>
321 * <tr><th scope="row">{@code 2.0}</th> <td>{@code 0x1.0p1}</td>
322 * <tr><th scope="row">{@code 3.0}</th> <td>{@code 0x1.8p1}</td>
323 * <tr><th scope="row">{@code 0.5}</th> <td>{@code 0x1.0p-1}</td>
324 * <tr><th scope="row">{@code 0.25}</th> <td>{@code 0x1.0p-2}</td>
325 * <tr><th scope="row">{@code Float.MAX_VALUE}</th>
326 * <td>{@code 0x1.fffffep127}</td>
327 * <tr><th scope="row">{@code Minimum Normal Value}</th>
328 * <td>{@code 0x1.0p-126}</td>
329 * <tr><th scope="row">{@code Maximum Subnormal Value}</th>
330 * <td>{@code 0x0.fffffep-126}</td>
331 * <tr><th scope="row">{@code Float.MIN_VALUE}</th>
332 * <td>{@code 0x0.000002p-126}</td>
333 * </tbody>
334 * </table>
335 * @param f the {@code float} to be converted.
336 * @return a hex string representation of the argument.
337 * @since 1.5
338 * @author Joseph D. Darcy
339 */
340 public static String toHexString(float f) {
341 if (Math.abs(f) < Float.MIN_NORMAL
342 && f != 0.0f ) {// float subnormal
343 // Adjust exponent to create subnormal double, then
344 // replace subnormal double exponent with subnormal float
345 // exponent
346 String s = Double.toHexString(Math.scalb((double)f,
347 /* -1022+126 */
348 Double.MIN_EXPONENT-
349 Float.MIN_EXPONENT));
350 return s.replaceFirst("p-1022$", "p-126");
351 }
352 else // double string will be the same as float string
353 return Double.toHexString(f);
354 }
355
356 /**
357 * Returns a {@code Float} object holding the
358 * {@code float} value represented by the argument string
359 * {@code s}.
360 *
361 * <p>If {@code s} is {@code null}, then a
362 * {@code NullPointerException} is thrown.
363 *
364 * <p>Leading and trailing whitespace characters in {@code s}
365 * are ignored. Whitespace is removed as if by the {@link
366 * String#trim} method; that is, both ASCII space and control
367 * characters are removed. The rest of {@code s} should
368 * constitute a <i>FloatValue</i> as described by the lexical
369 * syntax rules:
370 *
371 * <blockquote>
372 * <dl>
373 * <dt><i>FloatValue:</i>
374 * <dd><i>Sign<sub>opt</sub></i> {@code NaN}
375 * <dd><i>Sign<sub>opt</sub></i> {@code Infinity}
376 * <dd><i>Sign<sub>opt</sub> FloatingPointLiteral</i>
377 * <dd><i>Sign<sub>opt</sub> HexFloatingPointLiteral</i>
378 * <dd><i>SignedInteger</i>
379 * </dl>
380 *
381 * <dl>
382 * <dt><i>HexFloatingPointLiteral</i>:
383 * <dd> <i>HexSignificand BinaryExponent FloatTypeSuffix<sub>opt</sub></i>
384 * </dl>
385 *
386 * <dl>
387 * <dt><i>HexSignificand:</i>
388 * <dd><i>HexNumeral</i>
389 * <dd><i>HexNumeral</i> {@code .}
390 * <dd>{@code 0x} <i>HexDigits<sub>opt</sub>
391 * </i>{@code .}<i> HexDigits</i>
392 * <dd>{@code 0X}<i> HexDigits<sub>opt</sub>
393 * </i>{@code .} <i>HexDigits</i>
394 * </dl>
395 *
396 * <dl>
397 * <dt><i>BinaryExponent:</i>
398 * <dd><i>BinaryExponentIndicator SignedInteger</i>
399 * </dl>
400 *
401 * <dl>
402 * <dt><i>BinaryExponentIndicator:</i>
403 * <dd>{@code p}
404 * <dd>{@code P}
405 * </dl>
406 *
407 * </blockquote>
408 *
409 * where <i>Sign</i>, <i>FloatingPointLiteral</i>,
410 * <i>HexNumeral</i>, <i>HexDigits</i>, <i>SignedInteger</i> and
411 * <i>FloatTypeSuffix</i> are as defined in the lexical structure
412 * sections of
413 * <cite>The Java™ Language Specification</cite>,
414 * except that underscores are not accepted between digits.
415 * If {@code s} does not have the form of
416 * a <i>FloatValue</i>, then a {@code NumberFormatException}
417 * is thrown. Otherwise, {@code s} is regarded as
418 * representing an exact decimal value in the usual
419 * "computerized scientific notation" or as an exact
420 * hexadecimal value; this exact numerical value is then
421 * conceptually converted to an "infinitely precise"
422 * binary value that is then rounded to type {@code float}
423 * by the usual round-to-nearest rule of IEEE 754 floating-point
424 * arithmetic, which includes preserving the sign of a zero
425 * value.
426 *
427 * Note that the round-to-nearest rule also implies overflow and
428 * underflow behaviour; if the exact value of {@code s} is large
429 * enough in magnitude (greater than or equal to ({@link
430 * #MAX_VALUE} + {@link Math#ulp(float) ulp(MAX_VALUE)}/2),
431 * rounding to {@code float} will result in an infinity and if the
432 * exact value of {@code s} is small enough in magnitude (less
433 * than or equal to {@link #MIN_VALUE}/2), rounding to float will
434 * result in a zero.
435 *
436 * Finally, after rounding a {@code Float} object representing
437 * this {@code float} value is returned.
438 *
439 * <p>To interpret localized string representations of a
440 * floating-point value, use subclasses of {@link
441 * java.text.NumberFormat}.
442 *
443 * <p>Note that trailing format specifiers, specifiers that
444 * determine the type of a floating-point literal
445 * ({@code 1.0f} is a {@code float} value;
446 * {@code 1.0d} is a {@code double} value), do
447 * <em>not</em> influence the results of this method. In other
448 * words, the numerical value of the input string is converted
449 * directly to the target floating-point type. In general, the
450 * two-step sequence of conversions, string to {@code double}
451 * followed by {@code double} to {@code float}, is
452 * <em>not</em> equivalent to converting a string directly to
453 * {@code float}. For example, if first converted to an
454 * intermediate {@code double} and then to
455 * {@code float}, the string<br>
456 * {@code "1.00000017881393421514957253748434595763683319091796875001d"}<br>
457 * results in the {@code float} value
458 * {@code 1.0000002f}; if the string is converted directly to
459 * {@code float}, <code>1.000000<b>1</b>f</code> results.
460 *
461 * <p>To avoid calling this method on an invalid string and having
462 * a {@code NumberFormatException} be thrown, the documentation
463 * for {@link Double#valueOf Double.valueOf} lists a regular
464 * expression which can be used to screen the input.
465 *
466 * @param s the string to be parsed.
467 * @return a {@code Float} object holding the value
468 * represented by the {@code String} argument.
469 * @throws NumberFormatException if the string does not contain a
470 * parsable number.
471 */
472 public static Float valueOf(String s) throws NumberFormatException {
473 return new Float(parseFloat(s));
474 }
475
476 /**
477 * Returns a {@code Float} instance representing the specified
478 * {@code float} value.
479 * If a new {@code Float} instance is not required, this method
480 * should generally be used in preference to the constructor
481 * {@link #Float(float)}, as this method is likely to yield
482 * significantly better space and time performance by caching
483 * frequently requested values.
484 *
485 * @param f a float value.
486 * @return a {@code Float} instance representing {@code f}.
487 * @since 1.5
488 */
489 @HotSpotIntrinsicCandidate
490 public static Float valueOf(float f) {
491 return new Float(f);
492 }
493
494 /**
495 * Returns a new {@code float} initialized to the value
496 * represented by the specified {@code String}, as performed
497 * by the {@code valueOf} method of class {@code Float}.
498 *
499 * @param s the string to be parsed.
500 * @return the {@code float} value represented by the string
501 * argument.
502 * @throws NullPointerException if the string is null
503 * @throws NumberFormatException if the string does not contain a
504 * parsable {@code float}.
505 * @see java.lang.Float#valueOf(String)
506 * @since 1.2
507 */
508 public static float parseFloat(String s) throws NumberFormatException {
509 return FloatingDecimal.parseFloat(s);
510 }
511
512 /**
513 * Returns {@code true} if the specified number is a
514 * Not-a-Number (NaN) value, {@code false} otherwise.
515 *
516 * @param v the value to be tested.
517 * @return {@code true} if the argument is NaN;
518 * {@code false} otherwise.
519 */
520 public static boolean isNaN(float v) {
521 return (v != v);
522 }
523
524 /**
525 * Returns {@code true} if the specified number is infinitely
526 * large in magnitude, {@code false} otherwise.
527 *
528 * @param v the value to be tested.
529 * @return {@code true} if the argument is positive infinity or
530 * negative infinity; {@code false} otherwise.
531 */
532 public static boolean isInfinite(float v) {
533 return (v == POSITIVE_INFINITY) || (v == NEGATIVE_INFINITY);
534 }
535
536
537 /**
538 * Returns {@code true} if the argument is a finite floating-point
539 * value; returns {@code false} otherwise (for NaN and infinity
540 * arguments).
541 *
542 * @param f the {@code float} value to be tested
543 * @return {@code true} if the argument is a finite
544 * floating-point value, {@code false} otherwise.
545 * @since 1.8
546 */
547 public static boolean isFinite(float f) {
548 return Math.abs(f) <= Float.MAX_VALUE;
549 }
550
551 /**
552 * The value of the Float.
553 *
554 * @serial
555 */
556 private final float value;
557
558 /**
559 * Constructs a newly allocated {@code Float} object that
560 * represents the primitive {@code float} argument.
561 *
562 * @param value the value to be represented by the {@code Float}.
563 *
564 * @deprecated
565 * It is rarely appropriate to use this constructor. The static factory
566 * {@link #valueOf(float)} is generally a better choice, as it is
567 * likely to yield significantly better space and time performance.
568 */
569 @Deprecated(since="9")
570 public Float(float value) {
571 this.value = value;
572 }
573
574 /**
575 * Constructs a newly allocated {@code Float} object that
576 * represents the argument converted to type {@code float}.
577 *
578 * @param value the value to be represented by the {@code Float}.
579 *
580 * @deprecated
581 * It is rarely appropriate to use this constructor. Instead, use the
582 * static factory method {@link #valueOf(float)} method as follows:
583 * {@code Float.valueOf((float)value)}.
584 */
585 @Deprecated(since="9")
586 public Float(double value) {
587 this.value = (float)value;
588 }
589
590 /**
591 * Constructs a newly allocated {@code Float} object that
592 * represents the floating-point value of type {@code float}
593 * represented by the string. The string is converted to a
594 * {@code float} value as if by the {@code valueOf} method.
595 *
596 * @param s a string to be converted to a {@code Float}.
597 * @throws NumberFormatException if the string does not contain a
598 * parsable number.
599 *
600 * @deprecated
601 * It is rarely appropriate to use this constructor.
602 * Use {@link #parseFloat(String)} to convert a string to a
603 * {@code float} primitive, or use {@link #valueOf(String)}
604 * to convert a string to a {@code Float} object.
605 */
606 @Deprecated(since="9")
607 public Float(String s) throws NumberFormatException {
608 value = parseFloat(s);
609 }
610
611 /**
612 * Returns {@code true} if this {@code Float} value is a
613 * Not-a-Number (NaN), {@code false} otherwise.
614 *
615 * @return {@code true} if the value represented by this object is
616 * NaN; {@code false} otherwise.
617 */
618 public boolean isNaN() {
619 return isNaN(value);
620 }
621
622 /**
623 * Returns {@code true} if this {@code Float} value is
624 * infinitely large in magnitude, {@code false} otherwise.
625 *
626 * @return {@code true} if the value represented by this object is
627 * positive infinity or negative infinity;
628 * {@code false} otherwise.
629 */
630 public boolean isInfinite() {
631 return isInfinite(value);
632 }
633
634 /**
635 * Returns a string representation of this {@code Float} object.
636 * The primitive {@code float} value represented by this object
637 * is converted to a {@code String} exactly as if by the method
638 * {@code toString} of one argument.
639 *
640 * @return a {@code String} representation of this object.
641 * @see java.lang.Float#toString(float)
642 */
643 public String toString() {
644 return Float.toString(value);
645 }
646
647 /**
648 * Returns the value of this {@code Float} as a {@code byte} after
649 * a narrowing primitive conversion.
650 *
651 * @return the {@code float} value represented by this object
652 * converted to type {@code byte}
653 * @jls 5.1.3 Narrowing Primitive Conversion
654 */
655 public byte byteValue() {
656 return (byte)value;
657 }
658
659 /**
660 * Returns the value of this {@code Float} as a {@code short}
661 * after a narrowing primitive conversion.
662 *
663 * @return the {@code float} value represented by this object
664 * converted to type {@code short}
665 * @jls 5.1.3 Narrowing Primitive Conversion
666 * @since 1.1
667 */
668 public short shortValue() {
669 return (short)value;
670 }
671
672 /**
673 * Returns the value of this {@code Float} as an {@code int} after
674 * a narrowing primitive conversion.
675 *
676 * @return the {@code float} value represented by this object
677 * converted to type {@code int}
678 * @jls 5.1.3 Narrowing Primitive Conversion
679 */
680 public int intValue() {
681 return (int)value;
682 }
683
684 /**
685 * Returns value of this {@code Float} as a {@code long} after a
686 * narrowing primitive conversion.
687 *
688 * @return the {@code float} value represented by this object
689 * converted to type {@code long}
690 * @jls 5.1.3 Narrowing Primitive Conversion
691 */
692 public long longValue() {
693 return (long)value;
694 }
695
696 /**
697 * Returns the {@code float} value of this {@code Float} object.
698 *
699 * @return the {@code float} value represented by this object
700 */
701 @HotSpotIntrinsicCandidate
702 public float floatValue() {
703 return value;
704 }
705
706 /**
707 * Returns the value of this {@code Float} as a {@code double}
708 * after a widening primitive conversion.
709 *
710 * @return the {@code float} value represented by this
711 * object converted to type {@code double}
712 * @jls 5.1.2 Widening Primitive Conversion
713 */
714 public double doubleValue() {
715 return (double)value;
716 }
717
718 /**
719 * Returns a hash code for this {@code Float} object. The
720 * result is the integer bit representation, exactly as produced
721 * by the method {@link #floatToIntBits(float)}, of the primitive
722 * {@code float} value represented by this {@code Float}
723 * object.
724 *
725 * @return a hash code value for this object.
726 */
727 @Override
728 public int hashCode() {
729 return Float.hashCode(value);
730 }
731
732 /**
733 * Returns a hash code for a {@code float} value; compatible with
734 * {@code Float.hashCode()}.
735 *
736 * @param value the value to hash
737 * @return a hash code value for a {@code float} value.
738 * @since 1.8
739 */
740 public static int hashCode(float value) {
741 return floatToIntBits(value);
742 }
743
744 /**
745
746 * Compares this object against the specified object. The result
747 * is {@code true} if and only if the argument is not
748 * {@code null} and is a {@code Float} object that
749 * represents a {@code float} with the same value as the
750 * {@code float} represented by this object. For this
751 * purpose, two {@code float} values are considered to be the
752 * same if and only if the method {@link #floatToIntBits(float)}
753 * returns the identical {@code int} value when applied to
754 * each.
755 *
756 * <p>Note that in most cases, for two instances of class
757 * {@code Float}, {@code f1} and {@code f2}, the value
758 * of {@code f1.equals(f2)} is {@code true} if and only if
759 *
760 * <blockquote><pre>
761 * f1.floatValue() == f2.floatValue()
762 * </pre></blockquote>
763 *
764 * <p>also has the value {@code true}. However, there are two exceptions:
765 * <ul>
766 * <li>If {@code f1} and {@code f2} both represent
767 * {@code Float.NaN}, then the {@code equals} method returns
768 * {@code true}, even though {@code Float.NaN==Float.NaN}
769 * has the value {@code false}.
770 * <li>If {@code f1} represents {@code +0.0f} while
771 * {@code f2} represents {@code -0.0f}, or vice
772 * versa, the {@code equal} test has the value
773 * {@code false}, even though {@code 0.0f==-0.0f}
774 * has the value {@code true}.
775 * </ul>
776 *
777 * This definition allows hash tables to operate properly.
778 *
779 * @param obj the object to be compared
780 * @return {@code true} if the objects are the same;
781 * {@code false} otherwise.
782 * @see java.lang.Float#floatToIntBits(float)
783 */
784 public boolean equals(Object obj) {
785 return (obj instanceof Float)
786 && (floatToIntBits(((Float)obj).value) == floatToIntBits(value));
787 }
788
789 /**
790 * Returns a representation of the specified floating-point value
791 * according to the IEEE 754 floating-point "single format" bit
792 * layout.
793 *
794 * <p>Bit 31 (the bit that is selected by the mask
795 * {@code 0x80000000}) represents the sign of the floating-point
796 * number.
797 * Bits 30-23 (the bits that are selected by the mask
798 * {@code 0x7f800000}) represent the exponent.
799 * Bits 22-0 (the bits that are selected by the mask
800 * {@code 0x007fffff}) represent the significand (sometimes called
801 * the mantissa) of the floating-point number.
802 *
803 * <p>If the argument is positive infinity, the result is
804 * {@code 0x7f800000}.
805 *
806 * <p>If the argument is negative infinity, the result is
807 * {@code 0xff800000}.
808 *
809 * <p>If the argument is NaN, the result is {@code 0x7fc00000}.
810 *
811 * <p>In all cases, the result is an integer that, when given to the
812 * {@link #intBitsToFloat(int)} method, will produce a floating-point
813 * value the same as the argument to {@code floatToIntBits}
814 * (except all NaN values are collapsed to a single
815 * "canonical" NaN value).
816 *
817 * @param value a floating-point number.
818 * @return the bits that represent the floating-point number.
819 */
820 @HotSpotIntrinsicCandidate
821 public static int floatToIntBits(float value) {
822 if (!isNaN(value)) {
823 return floatToRawIntBits(value);
824 }
825 return 0x7fc00000;
826 }
827
828 /**
829 * Returns a representation of the specified floating-point value
830 * according to the IEEE 754 floating-point "single format" bit
831 * layout, preserving Not-a-Number (NaN) values.
832 *
833 * <p>Bit 31 (the bit that is selected by the mask
834 * {@code 0x80000000}) represents the sign of the floating-point
835 * number.
836 * Bits 30-23 (the bits that are selected by the mask
837 * {@code 0x7f800000}) represent the exponent.
838 * Bits 22-0 (the bits that are selected by the mask
839 * {@code 0x007fffff}) represent the significand (sometimes called
840 * the mantissa) of the floating-point number.
841 *
842 * <p>If the argument is positive infinity, the result is
843 * {@code 0x7f800000}.
844 *
845 * <p>If the argument is negative infinity, the result is
846 * {@code 0xff800000}.
847 *
848 * <p>If the argument is NaN, the result is the integer representing
849 * the actual NaN value. Unlike the {@code floatToIntBits}
850 * method, {@code floatToRawIntBits} does not collapse all the
851 * bit patterns encoding a NaN to a single "canonical"
852 * NaN value.
853 *
854 * <p>In all cases, the result is an integer that, when given to the
855 * {@link #intBitsToFloat(int)} method, will produce a
856 * floating-point value the same as the argument to
857 * {@code floatToRawIntBits}.
858 *
859 * @param value a floating-point number.
860 * @return the bits that represent the floating-point number.
861 * @since 1.3
862 */
863 @HotSpotIntrinsicCandidate
864 public static native int floatToRawIntBits(float value);
865
866 /**
867 * Returns the {@code float} value corresponding to a given
868 * bit representation.
869 * The argument is considered to be a representation of a
870 * floating-point value according to the IEEE 754 floating-point
871 * "single format" bit layout.
872 *
873 * <p>If the argument is {@code 0x7f800000}, the result is positive
874 * infinity.
875 *
876 * <p>If the argument is {@code 0xff800000}, the result is negative
877 * infinity.
878 *
879 * <p>If the argument is any value in the range
880 * {@code 0x7f800001} through {@code 0x7fffffff} or in
881 * the range {@code 0xff800001} through
882 * {@code 0xffffffff}, the result is a NaN. No IEEE 754
883 * floating-point operation provided by Java can distinguish
884 * between two NaN values of the same type with different bit
885 * patterns. Distinct values of NaN are only distinguishable by
886 * use of the {@code Float.floatToRawIntBits} method.
887 *
888 * <p>In all other cases, let <i>s</i>, <i>e</i>, and <i>m</i> be three
889 * values that can be computed from the argument:
890 *
891 * <blockquote><pre>{@code
892 * int s = ((bits >> 31) == 0) ? 1 : -1;
893 * int e = ((bits >> 23) & 0xff);
894 * int m = (e == 0) ?
895 * (bits & 0x7fffff) << 1 :
896 * (bits & 0x7fffff) | 0x800000;
897 * }</pre></blockquote>
898 *
899 * Then the floating-point result equals the value of the mathematical
900 * expression <i>s</i>·<i>m</i>·2<sup><i>e</i>-150</sup>.
901 *
902 * <p>Note that this method may not be able to return a
903 * {@code float} NaN with exactly same bit pattern as the
904 * {@code int} argument. IEEE 754 distinguishes between two
905 * kinds of NaNs, quiet NaNs and <i>signaling NaNs</i>. The
906 * differences between the two kinds of NaN are generally not
907 * visible in Java. Arithmetic operations on signaling NaNs turn
908 * them into quiet NaNs with a different, but often similar, bit
909 * pattern. However, on some processors merely copying a
910 * signaling NaN also performs that conversion. In particular,
911 * copying a signaling NaN to return it to the calling method may
912 * perform this conversion. So {@code intBitsToFloat} may
913 * not be able to return a {@code float} with a signaling NaN
914 * bit pattern. Consequently, for some {@code int} values,
915 * {@code floatToRawIntBits(intBitsToFloat(start))} may
916 * <i>not</i> equal {@code start}. Moreover, which
917 * particular bit patterns represent signaling NaNs is platform
918 * dependent; although all NaN bit patterns, quiet or signaling,
919 * must be in the NaN range identified above.
920 *
921 * @param bits an integer.
922 * @return the {@code float} floating-point value with the same bit
923 * pattern.
924 */
925 @HotSpotIntrinsicCandidate
926 public static native float intBitsToFloat(int bits);
927
928 /**
929 * Compares two {@code Float} objects numerically. There are
930 * two ways in which comparisons performed by this method differ
931 * from those performed by the Java language numerical comparison
932 * operators ({@code <, <=, ==, >=, >}) when
933 * applied to primitive {@code float} values:
934 *
935 * <ul><li>
936 * {@code Float.NaN} is considered by this method to
937 * be equal to itself and greater than all other
938 * {@code float} values
939 * (including {@code Float.POSITIVE_INFINITY}).
940 * <li>
941 * {@code 0.0f} is considered by this method to be greater
942 * than {@code -0.0f}.
943 * </ul>
944 *
945 * This ensures that the <i>natural ordering</i> of {@code Float}
946 * objects imposed by this method is <i>consistent with equals</i>.
947 *
948 * @param anotherFloat the {@code Float} to be compared.
949 * @return the value {@code 0} if {@code anotherFloat} is
950 * numerically equal to this {@code Float}; a value
951 * less than {@code 0} if this {@code Float}
952 * is numerically less than {@code anotherFloat};
953 * and a value greater than {@code 0} if this
954 * {@code Float} is numerically greater than
955 * {@code anotherFloat}.
956 *
957 * @since 1.2
958 * @see Comparable#compareTo(Object)
959 */
960 public int compareTo(Float anotherFloat) {
961 return Float.compare(value, anotherFloat.value);
962 }
963
964 /**
965 * Compares the two specified {@code float} values. The sign
966 * of the integer value returned is the same as that of the
967 * integer that would be returned by the call:
968 * <pre>
969 * new Float(f1).compareTo(new Float(f2))
970 * </pre>
971 *
972 * @param f1 the first {@code float} to compare.
973 * @param f2 the second {@code float} to compare.
974 * @return the value {@code 0} if {@code f1} is
975 * numerically equal to {@code f2}; a value less than
976 * {@code 0} if {@code f1} is numerically less than
977 * {@code f2}; and a value greater than {@code 0}
978 * if {@code f1} is numerically greater than
979 * {@code f2}.
980 * @since 1.4
981 */
982 public static int compare(float f1, float f2) {
983 if (f1 < f2)
984 return -1; // Neither val is NaN, thisVal is smaller
985 if (f1 > f2)
986 return 1; // Neither val is NaN, thisVal is larger
987
988 // Cannot use floatToRawIntBits because of possibility of NaNs.
989 int thisBits = Float.floatToIntBits(f1);
990 int anotherBits = Float.floatToIntBits(f2);
991
992 return (thisBits == anotherBits ? 0 : // Values are equal
993 (thisBits < anotherBits ? -1 : // (-0.0, 0.0) or (!NaN, NaN)
994 1)); // (0.0, -0.0) or (NaN, !NaN)
995 }
996
997 /**
998 * Adds two {@code float} values together as per the + operator.
999 *
1000 * @param a the first operand
1001 * @param b the second operand
1002 * @return the sum of {@code a} and {@code b}
1003 * @jls 4.2.4 Floating-Point Operations
1004 * @see java.util.function.BinaryOperator
1005 * @since 1.8
1006 */
1007 public static float sum(float a, float b) {
1008 return a + b;
1009 }
1010
1011 /**
1012 * Returns the greater of two {@code float} values
1013 * as if by calling {@link Math#max(float, float) Math.max}.
1014 *
1015 * @param a the first operand
1016 * @param b the second operand
1017 * @return the greater of {@code a} and {@code b}
1018 * @see java.util.function.BinaryOperator
1019 * @since 1.8
1020 */
1021 public static float max(float a, float b) {
1022 return Math.max(a, b);
1023 }
1024
1025 /**
1026 * Returns the smaller of two {@code float} values
1027 * as if by calling {@link Math#min(float, float) Math.min}.
1028 *
1029 * @param a the first operand
1030 * @param b the second operand
1031 * @return the smaller of {@code a} and {@code b}
1032 * @see java.util.function.BinaryOperator
1033 * @since 1.8
1034 */
1035 public static float min(float a, float b) {
1036 return Math.min(a, b);
1037 }
1038
1039 /**
1040 * Returns an {@link Optional} containing the nominal descriptor for this
1041 * instance, which is the instance itself.
1042 *
1043 * @return an {@link Optional} describing the {@linkplain Float} instance
1044 * @since 12
1045 */
1046 @Override
1047 public Optional<Float> describeConstable() {
1048 return Optional.of(this);
1049 }
1050
1051 /**
1052 * Resolves this instance as a {@link ConstantDesc}, the result of which is
1053 * the instance itself.
1054 *
1055 * @param lookup ignored
1056 * @return the {@linkplain Float} instance
1057 * @since 12
1058 */
1059 @Override
1060 public Float resolveConstantDesc(MethodHandles.Lookup lookup) {
1061 return this;
1062 }
1063
1064 /** use serialVersionUID from JDK 1.0.2 for interoperability */
1065 @java.io.Serial
1066 private static final long serialVersionUID = -2671257302660747028L;
1067 }