1 /*

     2  * Copyright 1994-2006 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.lang;

    27 

    28 import sun.misc.FloatingDecimal;

    29 import sun.misc.FpUtils;

    30 import sun.misc.FloatConsts;

    31 import sun.misc.DoubleConsts;

    32 

    33 /**

    34  * The {@code Float} class wraps a value of primitive type

    35  * {@code float} in an object. An object of type

    36  * {@code Float} contains a single field whose type is

    37  * {@code float}.

    38  *

    39  * <p>In addition, this class provides several methods for converting a

    40  * {@code float} to a {@code String} and a

    41  * {@code String} to a {@code float}, as well as other

    42  * constants and methods useful when dealing with a

    43  * {@code float}.

    44  *

    45  * @author  Lee Boynton

    46  * @author  Arthur van Hoff

    47  * @author  Joseph D. Darcy

    48  * @since JDK1.0

    49  */

    50 public final class Float extends Number implements Comparable<Float> {

    51     /**

    52      * A constant holding the positive infinity of type

    53      * {@code float}. It is equal to the value returned by

    54      * {@code Float.intBitsToFloat(0x7f800000)}.

    55      */

    56     public static final float POSITIVE_INFINITY = 1.0f / 0.0f;

    57 

    58     /**

    59      * A constant holding the negative infinity of type

    60      * {@code float}. It is equal to the value returned by

    61      * {@code Float.intBitsToFloat(0xff800000)}.

    62      */

    63     public static final float NEGATIVE_INFINITY = -1.0f / 0.0f;

    64 

    65     /**

    66      * A constant holding a Not-a-Number (NaN) value of type

    67      * {@code float}.  It is equivalent to the value returned by

    68      * {@code Float.intBitsToFloat(0x7fc00000)}.

    69      */

    70     public static final float NaN = 0.0f / 0.0f;

    71 

    72     /**

    73      * A constant holding the largest positive finite value of type

    74      * {@code float}, (2-2<sup>-23</sup>)&middot;2<sup>127</sup>.

    75      * It is equal to the hexadecimal floating-point literal

    76      * {@code 0x1.fffffeP+127f} and also equal to

    77      * {@code Float.intBitsToFloat(0x7f7fffff)}.

    78      */

    79     public static final float MAX_VALUE = 0x1.fffffeP+127f; // 3.4028235e+38f

    80 

    81     /**

    82      * A constant holding the smallest positive normal value of type

    83      * {@code float}, 2<sup>-126</sup>.  It is equal to the

    84      * hexadecimal floating-point literal {@code 0x1.0p-126f} and also

    85      * equal to {@code Float.intBitsToFloat(0x00800000)}.

    86      *

    87      * @since 1.6

    88      */

    89     public static final float MIN_NORMAL = 0x1.0p-126f; // 1.17549435E-38f

    90 

    91     /**

    92      * A constant holding the smallest positive nonzero value of type

    93      * {@code float}, 2<sup>-149</sup>. It is equal to the

    94      * hexadecimal floating-point literal {@code 0x0.000002P-126f}

    95      * and also equal to {@code Float.intBitsToFloat(0x1)}.

    96      */

    97     public static final float MIN_VALUE = 0x0.000002P-126f; // 1.4e-45f

    98 

    99     /**

   100      * Maximum exponent a finite {@code float} variable may have.  It

   101      * is equal to the value returned by {@code

   102      * Math.getExponent(Float.MAX_VALUE)}.

   103      *

   104      * @since 1.6

   105      */

   106     public static final int MAX_EXPONENT = 127;

   107 

   108     /**

   109      * Minimum exponent a normalized {@code float} variable may have.

   110      * It is equal to the value returned by {@code

   111      * Math.getExponent(Float.MIN_NORMAL)}.

   112      *

   113      * @since 1.6

   114      */

   115     public static final int MIN_EXPONENT = -126;

   116 

   117     /**

   118      * The number of bits used to represent a {@code float} value.

   119      *

   120      * @since 1.5

   121      */

   122     public static final int SIZE = 32;

   123 

   124     /**

   125      * The {@code Class} instance representing the primitive type

   126      * {@code float}.

   127      *

   128      * @since JDK1.1

   129      */

   130     public static final Class<Float> TYPE = Class.getPrimitiveClass("float");

   131 

   132     /**

   133      * Returns a string representation of the {@code float}

   134      * argument. All characters mentioned below are ASCII characters.

   135      * <ul>

   136      * <li>If the argument is NaN, the result is the string

   137      * "{@code NaN}".

   138      * <li>Otherwise, the result is a string that represents the sign and

   139      *     magnitude (absolute value) of the argument. If the sign is

   140      *     negative, the first character of the result is

   141      *     '{@code -}' (<code>'&#92;u002D'</code>); if the sign is

   142      *     positive, no sign character appears in the result. As for

   143      *     the magnitude <i>m</i>:

   144      * <ul>

   145      * <li>If <i>m</i> is infinity, it is represented by the characters

   146      *     {@code "Infinity"}; thus, positive infinity produces

   147      *     the result {@code "Infinity"} and negative infinity

   148      *     produces the result {@code "-Infinity"}.

   149      * <li>If <i>m</i> is zero, it is represented by the characters

   150      *     {@code "0.0"}; thus, negative zero produces the result

   151      *     {@code "-0.0"} and positive zero produces the result

   152      *     {@code "0.0"}.

   153      * <li> If <i>m</i> is greater than or equal to 10<sup>-3</sup> but

   154      *      less than 10<sup>7</sup>, then it is represented as the

   155      *      integer part of <i>m</i>, in decimal form with no leading

   156      *      zeroes, followed by '{@code .}'

   157      *      (<code>'&#92;u002E'</code>), followed by one or more

   158      *      decimal digits representing the fractional part of

   159      *      <i>m</i>.

   160      * <li> If <i>m</i> is less than 10<sup>-3</sup> or greater than or

   161      *      equal to 10<sup>7</sup>, then it is represented in

   162      *      so-called "computerized scientific notation." Let <i>n</i>

   163      *      be the unique integer such that 10<sup><i>n</i> </sup>&le;

   164      *      <i>m</i> {@literal <} 10<sup><i>n</i>+1</sup>; then let <i>a</i>

   165      *      be the mathematically exact quotient of <i>m</i> and

   166      *      10<sup><i>n</i></sup> so that 1 &le; <i>a</i> {@literal <} 10.

   167      *      The magnitude is then represented as the integer part of

   168      *      <i>a</i>, as a single decimal digit, followed by

   169      *      '{@code .}' (<code>'&#92;u002E'</code>), followed by

   170      *      decimal digits representing the fractional part of

   171      *      <i>a</i>, followed by the letter '{@code E}'

   172      *      (<code>'&#92;u0045'</code>), followed by a representation

   173      *      of <i>n</i> as a decimal integer, as produced by the

   174      *      method {@link java.lang.Integer#toString(int)}.

   175      *

   176      * </ul>

   177      * </ul>

   178      * How many digits must be printed for the fractional part of

   179      * <i>m</i> or <i>a</i>? There must be at least one digit

   180      * to represent the fractional part, and beyond that as many, but

   181      * only as many, more digits as are needed to uniquely distinguish

   182      * the argument value from adjacent values of type

   183      * {@code float}. That is, suppose that <i>x</i> is the

   184      * exact mathematical value represented by the decimal

   185      * representation produced by this method for a finite nonzero

   186      * argument <i>f</i>. Then <i>f</i> must be the {@code float}

   187      * value nearest to <i>x</i>; or, if two {@code float} values are

   188      * equally close to <i>x</i>, then <i>f</i> must be one of

   189      * them and the least significant bit of the significand of

   190      * <i>f</i> must be {@code 0}.

   191      *

   192      * <p>To create localized string representations of a floating-point

   193      * value, use subclasses of {@link java.text.NumberFormat}.

   194      *

   195      * @param   f   the float to be converted.

   196      * @return a string representation of the argument.

   197      */

   198     public static String toString(float f) {

   199         return new FloatingDecimal(f).toJavaFormatString();

   200     }

   201 

   202     /**

   203      * Returns a hexadecimal string representation of the

   204      * {@code float} argument. All characters mentioned below are

   205      * ASCII characters.

   206      *

   207      * <ul>

   208      * <li>If the argument is NaN, the result is the string

   209      *     "{@code NaN}".

   210      * <li>Otherwise, the result is a string that represents the sign and

   211      * magnitude (absolute value) of the argument. If the sign is negative,

   212      * the first character of the result is '{@code -}'

   213      * (<code>'&#92;u002D'</code>); if the sign is positive, no sign character

   214      * appears in the result. As for the magnitude <i>m</i>:

   215      *

   216      * <ul>

   217      * <li>If <i>m</i> is infinity, it is represented by the string

   218      * {@code "Infinity"}; thus, positive infinity produces the

   219      * result {@code "Infinity"} and negative infinity produces

   220      * the result {@code "-Infinity"}.

   221      *

   222      * <li>If <i>m</i> is zero, it is represented by the string

   223      * {@code "0x0.0p0"}; thus, negative zero produces the result

   224      * {@code "-0x0.0p0"} and positive zero produces the result

   225      * {@code "0x0.0p0"}.

   226      *

   227      * <li>If <i>m</i> is a {@code float} value with a

   228      * normalized representation, substrings are used to represent the

   229      * significand and exponent fields.  The significand is

   230      * represented by the characters {@code "0x1."}

   231      * followed by a lowercase hexadecimal representation of the rest

   232      * of the significand as a fraction.  Trailing zeros in the

   233      * hexadecimal representation are removed unless all the digits

   234      * are zero, in which case a single zero is used. Next, the

   235      * exponent is represented by {@code "p"} followed

   236      * by a decimal string of the unbiased exponent as if produced by

   237      * a call to {@link Integer#toString(int) Integer.toString} on the

   238      * exponent value.

   239      *

   240      * <li>If <i>m</i> is a {@code float} value with a subnormal

   241      * representation, the significand is represented by the

   242      * characters {@code "0x0."} followed by a

   243      * hexadecimal representation of the rest of the significand as a

   244      * fraction.  Trailing zeros in the hexadecimal representation are

   245      * removed. Next, the exponent is represented by

   246      * {@code "p-126"}.  Note that there must be at

   247      * least one nonzero digit in a subnormal significand.

   248      *

   249      * </ul>

   250      *

   251      * </ul>

   252      *

   253      * <table border>

   254      * <caption><h3>Examples</h3></caption>

   255      * <tr><th>Floating-point Value</th><th>Hexadecimal String</th>

   256      * <tr><td>{@code 1.0}</td> <td>{@code 0x1.0p0}</td>

   257      * <tr><td>{@code -1.0}</td>        <td>{@code -0x1.0p0}</td>

   258      * <tr><td>{@code 2.0}</td> <td>{@code 0x1.0p1}</td>

   259      * <tr><td>{@code 3.0}</td> <td>{@code 0x1.8p1}</td>

   260      * <tr><td>{@code 0.5}</td> <td>{@code 0x1.0p-1}</td>

   261      * <tr><td>{@code 0.25}</td>        <td>{@code 0x1.0p-2}</td>

   262      * <tr><td>{@code Float.MAX_VALUE}</td>

   263      *     <td>{@code 0x1.fffffep127}</td>

   264      * <tr><td>{@code Minimum Normal Value}</td>

   265      *     <td>{@code 0x1.0p-126}</td>

   266      * <tr><td>{@code Maximum Subnormal Value}</td>

   267      *     <td>{@code 0x0.fffffep-126}</td>

   268      * <tr><td>{@code Float.MIN_VALUE}</td>

   269      *     <td>{@code 0x0.000002p-126}</td>

   270      * </table>

   271      * @param   f   the {@code float} to be converted.

   272      * @return a hex string representation of the argument.

   273      * @since 1.5

   274      * @author Joseph D. Darcy

   275      */

   276     public static String toHexString(float f) {

   277         if (Math.abs(f) < FloatConsts.MIN_NORMAL

   278             &&  f != 0.0f ) {// float subnormal

   279             // Adjust exponent to create subnormal double, then

   280             // replace subnormal double exponent with subnormal float

   281             // exponent

   282             String s = Double.toHexString(FpUtils.scalb((double)f,

   283                                                         /* -1022+126 */

   284                                                         DoubleConsts.MIN_EXPONENT-

   285                                                         FloatConsts.MIN_EXPONENT));

   286             return s.replaceFirst("p-1022$", "p-126");

   287         }

   288         else // double string will be the same as float string

   289             return Double.toHexString(f);

   290     }

   291 

   292     /**

   293      * Returns a {@code Float} object holding the

   294      * {@code float} value represented by the argument string

   295      * {@code s}.

   296      *

   297      * <p>If {@code s} is {@code null}, then a

   298      * {@code NullPointerException} is thrown.

   299      *

   300      * <p>Leading and trailing whitespace characters in {@code s}

   301      * are ignored.  Whitespace is removed as if by the {@link

   302      * String#trim} method; that is, both ASCII space and control

   303      * characters are removed. The rest of {@code s} should

   304      * constitute a <i>FloatValue</i> as described by the lexical

   305      * syntax rules:

   306      *

   307      * <blockquote>

   308      * <dl>

   309      * <dt><i>FloatValue:</i>

   310      * <dd><i>Sign<sub>opt</sub></i> {@code NaN}

   311      * <dd><i>Sign<sub>opt</sub></i> {@code Infinity}

   312      * <dd><i>Sign<sub>opt</sub> FloatingPointLiteral</i>

   313      * <dd><i>Sign<sub>opt</sub> HexFloatingPointLiteral</i>

   314      * <dd><i>SignedInteger</i>

   315      * </dl>

   316      *

   317      * <p>

   318      *

   319      * <dl>

   320      * <dt><i>HexFloatingPointLiteral</i>:

   321      * <dd> <i>HexSignificand BinaryExponent FloatTypeSuffix<sub>opt</sub></i>

   322      * </dl>

   323      *

   324      * <p>

   325      *

   326      * <dl>

   327      * <dt><i>HexSignificand:</i>

   328      * <dd><i>HexNumeral</i>

   329      * <dd><i>HexNumeral</i> {@code .}

   330      * <dd>{@code 0x} <i>HexDigits<sub>opt</sub>

   331      *     </i>{@code .}<i> HexDigits</i>

   332      * <dd>{@code 0X}<i> HexDigits<sub>opt</sub>

   333      *     </i>{@code .} <i>HexDigits</i>

   334      * </dl>

   335      *

   336      * <p>

   337      *

   338      * <dl>

   339      * <dt><i>BinaryExponent:</i>

   340      * <dd><i>BinaryExponentIndicator SignedInteger</i>

   341      * </dl>

   342      *

   343      * <p>

   344      *

   345      * <dl>

   346      * <dt><i>BinaryExponentIndicator:</i>

   347      * <dd>{@code p}

   348      * <dd>{@code P}

   349      * </dl>

   350      *

   351      * </blockquote>

   352      *

   353      * where <i>Sign</i>, <i>FloatingPointLiteral</i>,

   354      * <i>HexNumeral</i>, <i>HexDigits</i>, <i>SignedInteger</i> and

   355      * <i>FloatTypeSuffix</i> are as defined in the lexical structure

   356      * sections of the <a

   357      * href="http://java.sun.com/docs/books/jls/html/">Java Language

   358      * Specification</a>. If {@code s} does not have the form of

   359      * a <i>FloatValue</i>, then a {@code NumberFormatException}

   360      * is thrown. Otherwise, {@code s} is regarded as

   361      * representing an exact decimal value in the usual

   362      * "computerized scientific notation" or as an exact

   363      * hexadecimal value; this exact numerical value is then

   364      * conceptually converted to an "infinitely precise"

   365      * binary value that is then rounded to type {@code float}

   366      * by the usual round-to-nearest rule of IEEE 754 floating-point

   367      * arithmetic, which includes preserving the sign of a zero

   368      * value. Finally, a {@code Float} object representing this

   369      * {@code float} value is returned.

   370      *

   371      * <p>To interpret localized string representations of a

   372      * floating-point value, use subclasses of {@link

   373      * java.text.NumberFormat}.

   374      *

   375      * <p>Note that trailing format specifiers, specifiers that

   376      * determine the type of a floating-point literal

   377      * ({@code 1.0f} is a {@code float} value;

   378      * {@code 1.0d} is a {@code double} value), do

   379      * <em>not</em> influence the results of this method.  In other

   380      * words, the numerical value of the input string is converted

   381      * directly to the target floating-point type.  In general, the

   382      * two-step sequence of conversions, string to {@code double}

   383      * followed by {@code double} to {@code float}, is

   384      * <em>not</em> equivalent to converting a string directly to

   385      * {@code float}.  For example, if first converted to an

   386      * intermediate {@code double} and then to

   387      * {@code float}, the string<br>

   388      * {@code "1.00000017881393421514957253748434595763683319091796875001d"}<br>

   389      * results in the {@code float} value

   390      * {@code 1.0000002f}; if the string is converted directly to

   391      * {@code float}, <code>1.000000<b>1</b>f</code> results.

   392      *

   393      * <p>To avoid calling this method on an invalid string and having

   394      * a {@code NumberFormatException} be thrown, the documentation

   395      * for {@link Double#valueOf Double.valueOf} lists a regular

   396      * expression which can be used to screen the input.

   397      *

   398      * @param   s   the string to be parsed.

   399      * @return  a {@code Float} object holding the value

   400      *          represented by the {@code String} argument.

   401      * @throws  NumberFormatException  if the string does not contain a

   402      *          parsable number.

   403      */

   404     public static Float valueOf(String s) throws NumberFormatException {

   405         return new Float(FloatingDecimal.readJavaFormatString(s).floatValue());

   406     }

   407 

   408     /**

   409      * Returns a {@code Float} instance representing the specified

   410      * {@code float} value.

   411      * If a new {@code Float} instance is not required, this method

   412      * should generally be used in preference to the constructor

   413      * {@link #Float(float)}, as this method is likely to yield

   414      * significantly better space and time performance by caching

   415      * frequently requested values.

   416      *

   417      * @param  f a float value.

   418      * @return a {@code Float} instance representing {@code f}.

   419      * @since  1.5

   420      */

   421     public static Float valueOf(float f) {

   422         return new Float(f);

   423     }

   424 

   425     /**

   426      * Returns a new {@code float} initialized to the value

   427      * represented by the specified {@code String}, as performed

   428      * by the {@code valueOf} method of class {@code Float}.

   429      *

   430      * @param      s   the string to be parsed.

   431      * @return the {@code float} value represented by the string

   432      *         argument.

   433      * @throws  NumberFormatException  if the string does not contain a

   434      *               parsable {@code float}.

   435      * @see        java.lang.Float#valueOf(String)

   436      * @since 1.2

   437      */

   438     public static float parseFloat(String s) throws NumberFormatException {

   439         return FloatingDecimal.readJavaFormatString(s).floatValue();

   440     }

   441 

   442     /**

   443      * Returns {@code true} if the specified number is a

   444      * Not-a-Number (NaN) value, {@code false} otherwise.

   445      *

   446      * @param   v   the value to be tested.

   447      * @return  {@code true} if the argument is NaN;

   448      *          {@code false} otherwise.

   449      */

   450     static public boolean isNaN(float v) {

   451         return (v != v);

   452     }

   453 

   454     /**

   455      * Returns {@code true} if the specified number is infinitely

   456      * large in magnitude, {@code false} otherwise.

   457      *

   458      * @param   v   the value to be tested.

   459      * @return  {@code true} if the argument is positive infinity or

   460      *          negative infinity; {@code false} otherwise.

   461      */

   462     static public boolean isInfinite(float v) {

   463         return (v == POSITIVE_INFINITY) || (v == NEGATIVE_INFINITY);

   464     }

   465 

   466     /**

   467      * The value of the Float.

   468      *

   469      * @serial

   470      */

   471     private final float value;

   472 

   473     /**

   474      * Constructs a newly allocated {@code Float} object that

   475      * represents the primitive {@code float} argument.

   476      *

   477      * @param   value   the value to be represented by the {@code Float}.

   478      */

   479     public Float(float value) {

   480         this.value = value;

   481     }

   482 

   483     /**

   484      * Constructs a newly allocated {@code Float} object that

   485      * represents the argument converted to type {@code float}.

   486      *

   487      * @param   value   the value to be represented by the {@code Float}.

   488      */

   489     public Float(double value) {

   490         this.value = (float)value;

   491     }

   492 

   493     /**

   494      * Constructs a newly allocated {@code Float} object that

   495      * represents the floating-point value of type {@code float}

   496      * represented by the string. The string is converted to a

   497      * {@code float} value as if by the {@code valueOf} method.

   498      *

   499      * @param      s   a string to be converted to a {@code Float}.

   500      * @throws  NumberFormatException  if the string does not contain a

   501      *               parsable number.

   502      * @see        java.lang.Float#valueOf(java.lang.String)

   503      */

   504     public Float(String s) throws NumberFormatException {

   505         // REMIND: this is inefficient

   506         this(valueOf(s).floatValue());

   507     }

   508 

   509     /**

   510      * Returns {@code true} if this {@code Float} value is a

   511      * Not-a-Number (NaN), {@code false} otherwise.

   512      *

   513      * @return  {@code true} if the value represented by this object is

   514      *          NaN; {@code false} otherwise.

   515      */

   516     public boolean isNaN() {

   517         return isNaN(value);

   518     }

   519 

   520     /**

   521      * Returns {@code true} if this {@code Float} value is

   522      * infinitely large in magnitude, {@code false} otherwise.

   523      *

   524      * @return  {@code true} if the value represented by this object is

   525      *          positive infinity or negative infinity;

   526      *          {@code false} otherwise.

   527      */

   528     public boolean isInfinite() {

   529         return isInfinite(value);

   530     }

   531 

   532     /**

   533      * Returns a string representation of this {@code Float} object.

   534      * The primitive {@code float} value represented by this object

   535      * is converted to a {@code String} exactly as if by the method

   536      * {@code toString} of one argument.

   537      *

   538      * @return  a {@code String} representation of this object.

   539      * @see java.lang.Float#toString(float)

   540      */

   541     public String toString() {

   542         return String.valueOf(value);

   543     }

   544 

   545     /**

   546      * Returns the value of this {@code Float} as a {@code byte} (by

   547      * casting to a {@code byte}).

   548      *

   549      * @return  the {@code float} value represented by this object

   550      *          converted to type {@code byte}

   551      */

   552     public byte byteValue() {

   553         return (byte)value;

   554     }

   555 

   556     /**

   557      * Returns the value of this {@code Float} as a {@code short} (by

   558      * casting to a {@code short}).

   559      *

   560      * @return  the {@code float} value represented by this object

   561      *          converted to type {@code short}

   562      * @since JDK1.1

   563      */

   564     public short shortValue() {

   565         return (short)value;

   566     }

   567 

   568     /**

   569      * Returns the value of this {@code Float} as an {@code int} (by

   570      * casting to type {@code int}).

   571      *

   572      * @return  the {@code float} value represented by this object

   573      *          converted to type {@code int}

   574      */

   575     public int intValue() {

   576         return (int)value;

   577     }

   578 

   579     /**

   580      * Returns value of this {@code Float} as a {@code long} (by

   581      * casting to type {@code long}).

   582      *

   583      * @return  the {@code float} value represented by this object

   584      *          converted to type {@code long}

   585      */

   586     public long longValue() {

   587         return (long)value;

   588     }

   589 

   590     /**

   591      * Returns the {@code float} value of this {@code Float} object.

   592      *

   593      * @return the {@code float} value represented by this object

   594      */

   595     public float floatValue() {

   596         return value;

   597     }

   598 

   599     /**

   600      * Returns the {@code double} value of this {@code Float} object.

   601      *

   602      * @return the {@code float} value represented by this

   603      *         object is converted to type {@code double} and the

   604      *         result of the conversion is returned.

   605      */

   606     public double doubleValue() {

   607         return (double)value;

   608     }

   609 

   610     /**

   611      * Returns a hash code for this {@code Float} object. The

   612      * result is the integer bit representation, exactly as produced

   613      * by the method {@link #floatToIntBits(float)}, of the primitive

   614      * {@code float} value represented by this {@code Float}

   615      * object.

   616      *

   617      * @return a hash code value for this object.

   618      */

   619     public int hashCode() {

   620         return floatToIntBits(value);

   621     }

   622 

   623     /**

   624 

   625      * Compares this object against the specified object.  The result

   626      * is {@code true} if and only if the argument is not

   627      * {@code null} and is a {@code Float} object that

   628      * represents a {@code float} with the same value as the

   629      * {@code float} represented by this object. For this

   630      * purpose, two {@code float} values are considered to be the

   631      * same if and only if the method {@link #floatToIntBits(float)}

   632      * returns the identical {@code int} value when applied to

   633      * each.

   634      *

   635      * <p>Note that in most cases, for two instances of class

   636      * {@code Float}, {@code f1} and {@code f2}, the value

   637      * of {@code f1.equals(f2)} is {@code true} if and only if

   638      *

   639      * <blockquote><pre>

   640      *   f1.floatValue() == f2.floatValue()

   641      * </pre></blockquote>

   642      *

   643      * <p>also has the value {@code true}. However, there are two exceptions:

   644      * <ul>

   645      * <li>If {@code f1} and {@code f2} both represent

   646      *     {@code Float.NaN}, then the {@code equals} method returns

   647      *     {@code true}, even though {@code Float.NaN==Float.NaN}

   648      *     has the value {@code false}.

   649      * <li>If {@code f1} represents {@code +0.0f} while

   650      *     {@code f2} represents {@code -0.0f}, or vice

   651      *     versa, the {@code equal} test has the value

   652      *     {@code false}, even though {@code 0.0f==-0.0f}

   653      *     has the value {@code true}.

   654      * </ul>

   655      *

   656      * This definition allows hash tables to operate properly.

   657      *

   658      * @param obj the object to be compared

   659      * @return  {@code true} if the objects are the same;

   660      *          {@code false} otherwise.

   661      * @see java.lang.Float#floatToIntBits(float)

   662      */

   663     public boolean equals(Object obj) {

   664         return (obj instanceof Float)

   665                && (floatToIntBits(((Float)obj).value) == floatToIntBits(value));

   666     }

   667 

   668     /**

   669      * Returns a representation of the specified floating-point value

   670      * according to the IEEE 754 floating-point "single format" bit

   671      * layout.

   672      *

   673      * <p>Bit 31 (the bit that is selected by the mask

   674      * {@code 0x80000000}) represents the sign of the floating-point

   675      * number.

   676      * Bits 30-23 (the bits that are selected by the mask

   677      * {@code 0x7f800000}) represent the exponent.

   678      * Bits 22-0 (the bits that are selected by the mask

   679      * {@code 0x007fffff}) represent the significand (sometimes called

   680      * the mantissa) of the floating-point number.

   681      *

   682      * <p>If the argument is positive infinity, the result is

   683      * {@code 0x7f800000}.

   684      *

   685      * <p>If the argument is negative infinity, the result is

   686      * {@code 0xff800000}.

   687      *

   688      * <p>If the argument is NaN, the result is {@code 0x7fc00000}.

   689      *

   690      * <p>In all cases, the result is an integer that, when given to the

   691      * {@link #intBitsToFloat(int)} method, will produce a floating-point

   692      * value the same as the argument to {@code floatToIntBits}

   693      * (except all NaN values are collapsed to a single

   694      * "canonical" NaN value).

   695      *

   696      * @param   value   a floating-point number.

   697      * @return the bits that represent the floating-point number.

   698      */

   699     public static int floatToIntBits(float value) {

   700         int result = floatToRawIntBits(value);

   701         // Check for NaN based on values of bit fields, maximum

   702         // exponent and nonzero significand.

   703         if ( ((result & FloatConsts.EXP_BIT_MASK) ==

   704               FloatConsts.EXP_BIT_MASK) &&

   705              (result & FloatConsts.SIGNIF_BIT_MASK) != 0)

   706             result = 0x7fc00000;

   707         return result;

   708     }

   709 

   710     /**

   711      * Returns a representation of the specified floating-point value

   712      * according to the IEEE 754 floating-point "single format" bit

   713      * layout, preserving Not-a-Number (NaN) values.

   714      *

   715      * <p>Bit 31 (the bit that is selected by the mask

   716      * {@code 0x80000000}) represents the sign of the floating-point

   717      * number.

   718      * Bits 30-23 (the bits that are selected by the mask

   719      * {@code 0x7f800000}) represent the exponent.

   720      * Bits 22-0 (the bits that are selected by the mask

   721      * {@code 0x007fffff}) represent the significand (sometimes called

   722      * the mantissa) of the floating-point number.

   723      *

   724      * <p>If the argument is positive infinity, the result is

   725      * {@code 0x7f800000}.

   726      *

   727      * <p>If the argument is negative infinity, the result is

   728      * {@code 0xff800000}.

   729      *

   730      * <p>If the argument is NaN, the result is the integer representing

   731      * the actual NaN value.  Unlike the {@code floatToIntBits}

   732      * method, {@code floatToRawIntBits} does not collapse all the

   733      * bit patterns encoding a NaN to a single "canonical"

   734      * NaN value.

   735      *

   736      * <p>In all cases, the result is an integer that, when given to the

   737      * {@link #intBitsToFloat(int)} method, will produce a

   738      * floating-point value the same as the argument to

   739      * {@code floatToRawIntBits}.

   740      *

   741      * @param   value   a floating-point number.

   742      * @return the bits that represent the floating-point number.

   743      * @since 1.3

   744      */

   745     public static native int floatToRawIntBits(float value);

   746 

   747     /**

   748      * Returns the {@code float} value corresponding to a given

   749      * bit representation.

   750      * The argument is considered to be a representation of a

   751      * floating-point value according to the IEEE 754 floating-point

   752      * "single format" bit layout.

   753      *

   754      * <p>If the argument is {@code 0x7f800000}, the result is positive

   755      * infinity.

   756      *

   757      * <p>If the argument is {@code 0xff800000}, the result is negative

   758      * infinity.

   759      *

   760      * <p>If the argument is any value in the range

   761      * {@code 0x7f800001} through {@code 0x7fffffff} or in

   762      * the range {@code 0xff800001} through

   763      * {@code 0xffffffff}, the result is a NaN.  No IEEE 754

   764      * floating-point operation provided by Java can distinguish

   765      * between two NaN values of the same type with different bit

   766      * patterns.  Distinct values of NaN are only distinguishable by

   767      * use of the {@code Float.floatToRawIntBits} method.

   768      *

   769      * <p>In all other cases, let <i>s</i>, <i>e</i>, and <i>m</i> be three

   770      * values that can be computed from the argument:

   771      *

   772      * <blockquote><pre>

   773      * int s = ((bits >> 31) == 0) ? 1 : -1;

   774      * int e = ((bits >> 23) & 0xff);

   775      * int m = (e == 0) ?

   776      *                 (bits & 0x7fffff) << 1 :

   777      *                 (bits & 0x7fffff) | 0x800000;

   778      * </pre></blockquote>

   779      *

   780      * Then the floating-point result equals the value of the mathematical

   781      * expression <i>s</i>&middot;<i>m</i>&middot;2<sup><i>e</i>-150</sup>.

   782      *

   783      * <p>Note that this method may not be able to return a

   784      * {@code float} NaN with exactly same bit pattern as the

   785      * {@code int} argument.  IEEE 754 distinguishes between two

   786      * kinds of NaNs, quiet NaNs and <i>signaling NaNs</i>.  The

   787      * differences between the two kinds of NaN are generally not

   788      * visible in Java.  Arithmetic operations on signaling NaNs turn

   789      * them into quiet NaNs with a different, but often similar, bit

   790      * pattern.  However, on some processors merely copying a

   791      * signaling NaN also performs that conversion.  In particular,

   792      * copying a signaling NaN to return it to the calling method may

   793      * perform this conversion.  So {@code intBitsToFloat} may

   794      * not be able to return a {@code float} with a signaling NaN

   795      * bit pattern.  Consequently, for some {@code int} values,

   796      * {@code floatToRawIntBits(intBitsToFloat(start))} may

   797      * <i>not</i> equal {@code start}.  Moreover, which

   798      * particular bit patterns represent signaling NaNs is platform

   799      * dependent; although all NaN bit patterns, quiet or signaling,

   800      * must be in the NaN range identified above.

   801      *

   802      * @param   bits   an integer.

   803      * @return  the {@code float} floating-point value with the same bit

   804      *          pattern.

   805      */

   806     public static native float intBitsToFloat(int bits);

   807 

   808     /**

   809      * Compares two {@code Float} objects numerically.  There are

   810      * two ways in which comparisons performed by this method differ

   811      * from those performed by the Java language numerical comparison

   812      * operators ({@code <, <=, ==, >=, >}) when

   813      * applied to primitive {@code float} values:

   814      *

   815      * <ul><li>

   816      *          {@code Float.NaN} is considered by this method to

   817      *          be equal to itself and greater than all other

   818      *          {@code float} values

   819      *          (including {@code Float.POSITIVE_INFINITY}).

   820      * <li>

   821      *          {@code 0.0f} is considered by this method to be greater

   822      *          than {@code -0.0f}.

   823      * </ul>

   824      *

   825      * This ensures that the <i>natural ordering</i> of {@code Float}

   826      * objects imposed by this method is <i>consistent with equals</i>.

   827      *

   828      * @param   anotherFloat   the {@code Float} to be compared.

   829      * @return  the value {@code 0} if {@code anotherFloat} is

   830      *          numerically equal to this {@code Float}; a value

   831      *          less than {@code 0} if this {@code Float}

   832      *          is numerically less than {@code anotherFloat};

   833      *          and a value greater than {@code 0} if this

   834      *          {@code Float} is numerically greater than

   835      *          {@code anotherFloat}.

   836      *

   837      * @since   1.2

   838      * @see Comparable#compareTo(Object)

   839      */

   840     public int compareTo(Float anotherFloat) {

   841         return Float.compare(value, anotherFloat.value);

   842     }

   843 

   844     /**

   845      * Compares the two specified {@code float} values. The sign

   846      * of the integer value returned is the same as that of the

   847      * integer that would be returned by the call:

   848      * <pre>

   849      *    new Float(f1).compareTo(new Float(f2))

   850      * </pre>

   851      *

   852      * @param   f1        the first {@code float} to compare.

   853      * @param   f2        the second {@code float} to compare.

   854      * @return  the value {@code 0} if {@code f1} is

   855      *          numerically equal to {@code f2}; a value less than

   856      *          {@code 0} if {@code f1} is numerically less than

   857      *          {@code f2}; and a value greater than {@code 0}

   858      *          if {@code f1} is numerically greater than

   859      *          {@code f2}.

   860      * @since 1.4

   861      */

   862     public static int compare(float f1, float f2) {

   863        if (f1 < f2)

   864             return -1;           // Neither val is NaN, thisVal is smaller

   865         if (f1 > f2)

   866             return 1;            // Neither val is NaN, thisVal is larger

   867 

   868         int thisBits = Float.floatToIntBits(f1);

   869         int anotherBits = Float.floatToIntBits(f2);

   870 

   871         return (thisBits == anotherBits ?  0 : // Values are equal

   872                 (thisBits < anotherBits ? -1 : // (-0.0, 0.0) or (!NaN, NaN)

   873                  1));                          // (0.0, -0.0) or (NaN, !NaN)

   874     }

   875 

   876     /** use serialVersionUID from JDK 1.0.2 for interoperability */

   877     private static final long serialVersionUID = -2671257302660747028L;

   878 }