In addition, this class provides several methods for converting a * {@code float} to a {@code String} and a * {@code String} to a {@code float}, as well as other * constants and methods useful when dealing with a * {@code float}. * * * *
To create localized string representations of a floating-point * value, use subclasses of {@link java.text.NumberFormat}. * * @param f the float to be converted. * @return a string representation of the argument. */ public static String toString(float f) { return FloatingDecimal.toJavaFormatString(f); } /** * Returns a hexadecimal string representation of the * {@code float} argument. All characters mentioned below are * ASCII characters. * *
| Floating-point Value | Hexadecimal String | *
|---|---|
| {@code 1.0} | {@code 0x1.0p0} | *
| {@code -1.0} | {@code -0x1.0p0} | *
| {@code 2.0} | {@code 0x1.0p1} | *
| {@code 3.0} | {@code 0x1.8p1} | *
| {@code 0.5} | {@code 0x1.0p-1} | *
| {@code 0.25} | {@code 0x1.0p-2} | *
| {@code Float.MAX_VALUE} | *{@code 0x1.fffffep127} | *
| {@code Minimum Normal Value} | *{@code 0x1.0p-126} | *
| {@code Maximum Subnormal Value} | *{@code 0x0.fffffep-126} | *
| {@code Float.MIN_VALUE} | *{@code 0x0.000002p-126} | *
If {@code s} is {@code null}, then a * {@code NullPointerException} is thrown. * *
Leading and trailing whitespace characters in {@code s} * are ignored. Whitespace is removed as if by the {@link * String#trim} method; that is, both ASCII space and control * characters are removed. The rest of {@code s} should * constitute a FloatValue as described by the lexical * syntax rules: * *
** * where Sign, FloatingPointLiteral, * HexNumeral, HexDigits, SignedInteger and * FloatTypeSuffix are as defined in the lexical structure * sections of * The Java Language Specification, * except that underscores are not accepted between digits. * If {@code s} does not have the form of * a FloatValue, then a {@code NumberFormatException} * is thrown. Otherwise, {@code s} is regarded as * representing an exact decimal value in the usual * "computerized scientific notation" or as an exact * hexadecimal value; this exact numerical value is then * conceptually converted to an "infinitely precise" * binary value that is then rounded to type {@code float} * by the usual round-to-nearest rule of IEEE 754 floating-point * arithmetic, which includes preserving the sign of a zero * value. * * Note that the round-to-nearest rule also implies overflow and * underflow behaviour; if the exact value of {@code s} is large * enough in magnitude (greater than or equal to ({@link * #MAX_VALUE} + {@link Math#ulp(float) ulp(MAX_VALUE)}/2), * rounding to {@code float} will result in an infinity and if the * exact value of {@code s} is small enough in magnitude (less * than or equal to {@link #MIN_VALUE}/2), rounding to float will * result in a zero. * * Finally, after rounding a {@code Float} object representing * this {@code float} value is returned. * **
* *- FloatValue: *
- Signopt {@code NaN} *
- Signopt {@code Infinity} *
- Signopt FloatingPointLiteral *
- Signopt HexFloatingPointLiteral *
- SignedInteger *
*
* *- HexFloatingPointLiteral: *
- HexSignificand BinaryExponent FloatTypeSuffixopt *
*
* *- HexSignificand: *
- HexNumeral *
- HexNumeral {@code .} *
- {@code 0x} HexDigitsopt * {@code .} HexDigits *
- {@code 0X} HexDigitsopt * {@code .} HexDigits *
*
* *- BinaryExponent: *
- BinaryExponentIndicator SignedInteger *
*
* *- BinaryExponentIndicator: *
- {@code p} *
- {@code P} *
To interpret localized string representations of a * floating-point value, use subclasses of {@link * java.text.NumberFormat}. * *
Note that trailing format specifiers, specifiers that
* determine the type of a floating-point literal
* ({@code 1.0f} is a {@code float} value;
* {@code 1.0d} is a {@code double} value), do
* not influence the results of this method. In other
* words, the numerical value of the input string is converted
* directly to the target floating-point type. In general, the
* two-step sequence of conversions, string to {@code double}
* followed by {@code double} to {@code float}, is
* not equivalent to converting a string directly to
* {@code float}. For example, if first converted to an
* intermediate {@code double} and then to
* {@code float}, the string
* {@code "1.00000017881393421514957253748434595763683319091796875001d"}
* results in the {@code float} value
* {@code 1.0000002f}; if the string is converted directly to
* {@code float}, 1.0000001f results.
*
*
To avoid calling this method on an invalid string and having * a {@code NumberFormatException} be thrown, the documentation * for {@link Double#valueOf Double.valueOf} lists a regular * expression which can be used to screen the input. * * @param s the string to be parsed. * @return a {@code Float} object holding the value * represented by the {@code String} argument. * @throws NumberFormatException if the string does not contain a * parsable number. */ public static Float valueOf(String s) throws NumberFormatException { return new Float(parseFloat(s)); } /** * Returns a {@code Float} instance representing the specified * {@code float} value. * If a new {@code Float} instance is not required, this method * should generally be used in preference to the constructor * {@link #Float(float)}, as this method is likely to yield * significantly better space and time performance by caching * frequently requested values. * * @param f a float value. * @return a {@code Float} instance representing {@code f}. * @since 1.5 */ @IntrinsicCandidate public static Float valueOf(float f) { return new Float(f); } /** * Returns a new {@code float} initialized to the value * represented by the specified {@code String}, as performed * by the {@code valueOf} method of class {@code Float}. * * @param s the string to be parsed. * @return the {@code float} value represented by the string * argument. * @throws NullPointerException if the string is null * @throws NumberFormatException if the string does not contain a * parsable {@code float}. * @see java.lang.Float#valueOf(String) * @since 1.2 */ public static float parseFloat(String s) throws NumberFormatException { return FloatingDecimal.parseFloat(s); } /** * Returns {@code true} if the specified number is a * Not-a-Number (NaN) value, {@code false} otherwise. * * @param v the value to be tested. * @return {@code true} if the argument is NaN; * {@code false} otherwise. */ public static boolean isNaN(float v) { return (v != v); } /** * Returns {@code true} if the specified number is infinitely * large in magnitude, {@code false} otherwise. * * @param v the value to be tested. * @return {@code true} if the argument is positive infinity or * negative infinity; {@code false} otherwise. */ public static boolean isInfinite(float v) { return (v == POSITIVE_INFINITY) || (v == NEGATIVE_INFINITY); } /** * Returns {@code true} if the argument is a finite floating-point * value; returns {@code false} otherwise (for NaN and infinity * arguments). * * @param f the {@code float} value to be tested * @return {@code true} if the argument is a finite * floating-point value, {@code false} otherwise. * @since 1.8 */ public static boolean isFinite(float f) { return Math.abs(f) <= Float.MAX_VALUE; } /** * The value of the Float. * * @serial */ private final float value; /** * Constructs a newly allocated {@code Float} object that * represents the primitive {@code float} argument. * * @param value the value to be represented by the {@code Float}. * * @deprecated * It is rarely appropriate to use this constructor. The static factory * {@link #valueOf(float)} is generally a better choice, as it is * likely to yield significantly better space and time performance. */ // Android-changed: not yet forRemoval on Android. @Deprecated(since="9"/*, forRemoval = true*/) public Float(float value) { this.value = value; } /** * Constructs a newly allocated {@code Float} object that * represents the argument converted to type {@code float}. * * @param value the value to be represented by the {@code Float}. * * @deprecated * It is rarely appropriate to use this constructor. Instead, use the * static factory method {@link #valueOf(float)} method as follows: * {@code Float.valueOf((float)value)}. */ // Android-changed: not yet forRemoval on Android. @Deprecated(since="9"/*, forRemoval = true*/) public Float(double value) { this.value = (float)value; } /** * Constructs a newly allocated {@code Float} object that * represents the floating-point value of type {@code float} * represented by the string. The string is converted to a * {@code float} value as if by the {@code valueOf} method. * * @param s a string to be converted to a {@code Float}. * @throws NumberFormatException if the string does not contain a * parsable number. * * @deprecated * It is rarely appropriate to use this constructor. * Use {@link #parseFloat(String)} to convert a string to a * {@code float} primitive, or use {@link #valueOf(String)} * to convert a string to a {@code Float} object. */ // Android-changed: not yet forRemoval on Android. @Deprecated(since="9"/*, forRemoval = true*/) public Float(String s) throws NumberFormatException { value = parseFloat(s); } /** * Returns {@code true} if this {@code Float} value is a * Not-a-Number (NaN), {@code false} otherwise. * * @return {@code true} if the value represented by this object is * NaN; {@code false} otherwise. */ public boolean isNaN() { return isNaN(value); } /** * Returns {@code true} if this {@code Float} value is * infinitely large in magnitude, {@code false} otherwise. * * @return {@code true} if the value represented by this object is * positive infinity or negative infinity; * {@code false} otherwise. */ public boolean isInfinite() { return isInfinite(value); } /** * Returns a string representation of this {@code Float} object. * The primitive {@code float} value represented by this object * is converted to a {@code String} exactly as if by the method * {@code toString} of one argument. * * @return a {@code String} representation of this object. * @see java.lang.Float#toString(float) */ public String toString() { return Float.toString(value); } /** * Returns the value of this {@code Float} as a {@code byte} after * a narrowing primitive conversion. * * @return the {@code float} value represented by this object * converted to type {@code byte} * @jls 5.1.3 Narrowing Primitive Conversion */ public byte byteValue() { return (byte)value; } /** * Returns the value of this {@code Float} as a {@code short} * after a narrowing primitive conversion. * * @return the {@code float} value represented by this object * converted to type {@code short} * @jls 5.1.3 Narrowing Primitive Conversion * @since 1.1 */ public short shortValue() { return (short)value; } /** * Returns the value of this {@code Float} as an {@code int} after * a narrowing primitive conversion. * * @return the {@code float} value represented by this object * converted to type {@code int} * @jls 5.1.3 Narrowing Primitive Conversion */ public int intValue() { return (int)value; } /** * Returns value of this {@code Float} as a {@code long} after a * narrowing primitive conversion. * * @return the {@code float} value represented by this object * converted to type {@code long} * @jls 5.1.3 Narrowing Primitive Conversion */ public long longValue() { return (long)value; } /** * Returns the {@code float} value of this {@code Float} object. * * @return the {@code float} value represented by this object */ @IntrinsicCandidate public float floatValue() { return value; } /** * Returns the value of this {@code Float} as a {@code double} * after a widening primitive conversion. * * @return the {@code float} value represented by this * object converted to type {@code double} * @jls 5.1.2 Widening Primitive Conversion */ public double doubleValue() { return (double)value; } /** * Returns a hash code for this {@code Float} object. The * result is the integer bit representation, exactly as produced * by the method {@link #floatToIntBits(float)}, of the primitive * {@code float} value represented by this {@code Float} * object. * * @return a hash code value for this object. */ @Override public int hashCode() { return Float.hashCode(value); } /** * Returns a hash code for a {@code float} value; compatible with * {@code Float.hashCode()}. * * @param value the value to hash * @return a hash code value for a {@code float} value. * @since 1.8 */ public static int hashCode(float value) { return floatToIntBits(value); } /** * Compares this object against the specified object. The result * is {@code true} if and only if the argument is not * {@code null} and is a {@code Float} object that * represents a {@code float} with the same value as the * {@code float} represented by this object. For this * purpose, two {@code float} values are considered to be the * same if and only if the method {@link #floatToIntBits(float)} * returns the identical {@code int} value when applied to * each. * * @apiNote * This method is defined in terms of {@link * #floatToIntBits(float)} rather than the {@code ==} operator on * {@code float} values since the {@code ==} operator does * not define an equivalence relation and to satisfy the * {@linkplain Object#equals equals contract} an equivalence * relation must be implemented; see this discussion for * details of floating-point equality and equivalence. * * @param obj the object to be compared * @return {@code true} if the objects are the same; * {@code false} otherwise. * @see java.lang.Float#floatToIntBits(float) * @jls 15.21.1 Numerical Equality Operators == and != */ public boolean equals(Object obj) { return (obj instanceof Float) && (floatToIntBits(((Float)obj).value) == floatToIntBits(value)); } /** * Returns a representation of the specified floating-point value * according to the IEEE 754 floating-point "single format" bit * layout. * *
Bit 31 (the bit that is selected by the mask * {@code 0x80000000}) represents the sign of the floating-point * number. * Bits 30-23 (the bits that are selected by the mask * {@code 0x7f800000}) represent the exponent. * Bits 22-0 (the bits that are selected by the mask * {@code 0x007fffff}) represent the significand (sometimes called * the mantissa) of the floating-point number. * *
If the argument is positive infinity, the result is * {@code 0x7f800000}. * *
If the argument is negative infinity, the result is * {@code 0xff800000}. * *
If the argument is NaN, the result is {@code 0x7fc00000}. * *
In all cases, the result is an integer that, when given to the * {@link #intBitsToFloat(int)} method, will produce a floating-point * value the same as the argument to {@code floatToIntBits} * (except all NaN values are collapsed to a single * "canonical" NaN value). * * @param value a floating-point number. * @return the bits that represent the floating-point number. */ @IntrinsicCandidate public static int floatToIntBits(float value) { if (!isNaN(value)) { return floatToRawIntBits(value); } return 0x7fc00000; } /** * Returns a representation of the specified floating-point value * according to the IEEE 754 floating-point "single format" bit * layout, preserving Not-a-Number (NaN) values. * *
Bit 31 (the bit that is selected by the mask * {@code 0x80000000}) represents the sign of the floating-point * number. * Bits 30-23 (the bits that are selected by the mask * {@code 0x7f800000}) represent the exponent. * Bits 22-0 (the bits that are selected by the mask * {@code 0x007fffff}) represent the significand (sometimes called * the mantissa) of the floating-point number. * *
If the argument is positive infinity, the result is * {@code 0x7f800000}. * *
If the argument is negative infinity, the result is * {@code 0xff800000}. * *
If the argument is NaN, the result is the integer representing * the actual NaN value. Unlike the {@code floatToIntBits} * method, {@code floatToRawIntBits} does not collapse all the * bit patterns encoding a NaN to a single "canonical" * NaN value. * *
In all cases, the result is an integer that, when given to the * {@link #intBitsToFloat(int)} method, will produce a * floating-point value the same as the argument to * {@code floatToRawIntBits}. * * @param value a floating-point number. * @return the bits that represent the floating-point number. * @since 1.3 */ @IntrinsicCandidate public static native int floatToRawIntBits(float value); /** * Returns the {@code float} value corresponding to a given * bit representation. * The argument is considered to be a representation of a * floating-point value according to the IEEE 754 floating-point * "single format" bit layout. * *
If the argument is {@code 0x7f800000}, the result is positive * infinity. * *
If the argument is {@code 0xff800000}, the result is negative * infinity. * *
If the argument is any value in the range * {@code 0x7f800001} through {@code 0x7fffffff} or in * the range {@code 0xff800001} through * {@code 0xffffffff}, the result is a NaN. No IEEE 754 * floating-point operation provided by Java can distinguish * between two NaN values of the same type with different bit * patterns. Distinct values of NaN are only distinguishable by * use of the {@code Float.floatToRawIntBits} method. * *
In all other cases, let s, e, and m be three * values that can be computed from the argument: * *
{@code
* int s = ((bits >> 31) == 0) ? 1 : -1;
* int e = ((bits >> 23) & 0xff);
* int m = (e == 0) ?
* (bits & 0x7fffff) << 1 :
* (bits & 0x7fffff) | 0x800000;
* }Note that this method may not be able to return a * {@code float} NaN with exactly same bit pattern as the * {@code int} argument. IEEE 754 distinguishes between two * kinds of NaNs, quiet NaNs and signaling NaNs. The * differences between the two kinds of NaN are generally not * visible in Java. Arithmetic operations on signaling NaNs turn * them into quiet NaNs with a different, but often similar, bit * pattern. However, on some processors merely copying a * signaling NaN also performs that conversion. In particular, * copying a signaling NaN to return it to the calling method may * perform this conversion. So {@code intBitsToFloat} may * not be able to return a {@code float} with a signaling NaN * bit pattern. Consequently, for some {@code int} values, * {@code floatToRawIntBits(intBitsToFloat(start))} may * not equal {@code start}. Moreover, which * particular bit patterns represent signaling NaNs is platform * dependent; although all NaN bit patterns, quiet or signaling, * must be in the NaN range identified above. * * @param bits an integer. * @return the {@code float} floating-point value with the same bit * pattern. */ @IntrinsicCandidate public static native float intBitsToFloat(int bits); /** * Compares two {@code Float} objects numerically. * * This method imposes a total order on {@code Float} objects * with two differences compared to the incomplete order defined by * the Java language numerical comparison operators ({@code <, <=, * ==, >=, >}) on {@code float} values. * *
* new Float(f1).compareTo(new Float(f2))
*
*
* @param f1 the first {@code float} to compare.
* @param f2 the second {@code float} to compare.
* @return the value {@code 0} if {@code f1} is
* numerically equal to {@code f2}; a value less than
* {@code 0} if {@code f1} is numerically less than
* {@code f2}; and a value greater than {@code 0}
* if {@code f1} is numerically greater than
* {@code f2}.
* @since 1.4
*/
public static int compare(float f1, float f2) {
if (f1 < f2)
return -1; // Neither val is NaN, thisVal is smaller
if (f1 > f2)
return 1; // Neither val is NaN, thisVal is larger
// Cannot use floatToRawIntBits because of possibility of NaNs.
int thisBits = Float.floatToIntBits(f1);
int anotherBits = Float.floatToIntBits(f2);
return (thisBits == anotherBits ? 0 : // Values are equal
(thisBits < anotherBits ? -1 : // (-0.0, 0.0) or (!NaN, NaN)
1)); // (0.0, -0.0) or (NaN, !NaN)
}
/**
* Adds two {@code float} values together as per the + operator.
*
* @param a the first operand
* @param b the second operand
* @return the sum of {@code a} and {@code b}
* @jls 4.2.4 Floating-Point Operations
* @see java.util.function.BinaryOperator
* @since 1.8
*/
public static float sum(float a, float b) {
return a + b;
}
/**
* Returns the greater of two {@code float} values
* as if by calling {@link Math#max(float, float) Math.max}.
*
* @param a the first operand
* @param b the second operand
* @return the greater of {@code a} and {@code b}
* @see java.util.function.BinaryOperator
* @since 1.8
*/
public static float max(float a, float b) {
return Math.max(a, b);
}
/**
* Returns the smaller of two {@code float} values
* as if by calling {@link Math#min(float, float) Math.min}.
*
* @param a the first operand
* @param b the second operand
* @return the smaller of {@code a} and {@code b}
* @see java.util.function.BinaryOperator
* @since 1.8
*/
public static float min(float a, float b) {
return Math.min(a, b);
}
/**
* Returns an {@link Optional} containing the nominal descriptor for this
* instance, which is the instance itself.
*
* @return an {@link Optional} describing the {@linkplain Float} instance
* @since 12
* @hide
*/
@Override
public Optional