/* Float.java -- object wrapper for float Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version. */ package java.lang; import gnu.classpath.Configuration; /** * Instances of class Float represent primitive * float values. * * Additionally, this class provides various helper functions and variables * related to floats. * * @author Paul Fisher * @author Andrew Haley * @author Eric Blake * @since 1.0 * @status updated to 1.4 */ public final class Float extends Number implements Comparable { /** * Compatible with JDK 1.0+. */ private static final long serialVersionUID = -2671257302660747028L; /** * The maximum positive value a double may represent * is 3.4028235e+38f. */ public static final float MAX_VALUE = 3.4028235e+38f; /** * The minimum positive value a float may represent * is 1.4e-45. */ public static final float MIN_VALUE = 1.4e-45f; /** * The value of a float representation -1.0/0.0, negative infinity. */ public static final float NEGATIVE_INFINITY = -1.0f / 0.0f; /** * The value of a float representation 1.0/0.0, positive infinity. */ public static final float POSITIVE_INFINITY = 1.0f / 0.0f; /** * All IEEE 754 values of NaN have the same value in Java. */ public static final float NaN = 0.0f / 0.0f; /** * The primitive type float is represented by this * Class object. * @since 1.1 */ public static final Class TYPE = VMClassLoader.getPrimitiveClass('F'); /** * The immutable value of this Float. * * @serial the wrapped float */ private final float value; /** * Load native routines necessary for this class. */ static { if (Configuration.INIT_LOAD_LIBRARY) { System.loadLibrary("javalang"); } } /** * Create a Float from the primitive float * specified. * * @param value the float argument */ public Float(float value) { this.value = value; } /** * Create a Float from the primitive double * specified. * * @param value the double argument */ public Float(double value) { this.value = (float) value; } /** * Create a Float from the specified String. * This method calls Float.parseFloat(). * * @param s the String to convert * @throws NumberFormatException if s cannot be parsed as a * float * @throws NullPointerException if s is null * @see #parseFloat(String) */ public Float(String s) { value = parseFloat(s); } /** * Convert the float to a String. * Floating-point string representation is fairly complex: here is a * rundown of the possible values. "[-]" indicates that a * negative sign will be printed if the value (or exponent) is negative. * "<number>" means a string of digits ('0' to '9'). * "<digit>" means a single digit ('0' to '9').
* * * * * * * * * * *
Value of FloatString Representation
[+-] 0 [-]0.0
Between [+-] 10-3 and 107, exclusive[-]number.number
Other numeric value[-]<digit>.<number> * E[-]<number>
[+-] infinity [-]Infinity
NaN NaN
* * Yes, negative zero is a possible value. Note that there is * always a . and at least one digit printed after * it: even if the number is 3, it will be printed as 3.0. * After the ".", all digits will be printed except trailing zeros. The * result is rounded to the shortest decimal number which will parse back * to the same float. * *

To create other output formats, use {@link java.text.NumberFormat}. * * @XXX specify where we are not in accord with the spec. * * @param f the float to convert * @return the String representing the float */ public static String toString(float f) { return Double.toString(f, true); } /** * Creates a new Float object using the String. * * @param s the String to convert * @return the new Float * @throws NumberFormatException if s cannot be parsed as a * float * @throws NullPointerException if s is null * @see #parseFloat(String) */ public static Float valueOf(String s) { return new Float(parseFloat(s)); } /** * Parse the specified String as a float. The * extended BNF grammar is as follows:
*

   * DecodableString:
   *      ( [ - | + ] NaN )
   *    | ( [ - | + ] Infinity )
   *    | ( [ - | + ] FloatingPoint
   *              [ f | F | d
   *                | D] )
   * FloatingPoint:
   *      ( { Digit }+ [ . { Digit } ]
   *              [ Exponent ] )
   *    | ( . { Digit }+ [ Exponent ] )
   * Exponent:
   *      ( ( e | E )
   *              [ - | + ] { Digit }+ )
   * Digit: '0' through '9'
   * 
* *

NaN and infinity are special cases, to allow parsing of the output * of toString. Otherwise, the result is determined by calculating * n * 10exponent to infinite precision, then rounding * to the nearest float. Remember that many numbers cannot be precisely * represented in floating point. In case of overflow, infinity is used, * and in case of underflow, signed zero is used. Unlike Integer.parseInt, * this does not accept Unicode digits outside the ASCII range. * *

If an unexpected character is found in the String, a * NumberFormatException will be thrown. Leading and trailing * 'whitespace' is ignored via String.trim(), but spaces * internal to the actual number are not allowed. * *

To parse numbers according to another format, consider using * {@link java.text.NumberFormat}. * * @XXX specify where/how we are not in accord with the spec. * * @param str the String to convert * @return the float value of s * @throws NumberFormatException if s cannot be parsed as a * float * @throws NullPointerException if s is null * @see #MIN_VALUE * @see #MAX_VALUE * @see #POSITIVE_INFINITY * @see #NEGATIVE_INFINITY * @since 1.2 */ public static float parseFloat(String s) { // XXX Rounding parseDouble() causes some errors greater than 1 ulp from // the infinitely precise decimal. return (float) Double.parseDouble(s); } /** * Return true if the float has the same * value as NaN, otherwise return false. * * @param v the float to compare * @return whether the argument is NaN */ public static boolean isNaN(float v) { // This works since NaN != NaN is the only reflexive inequality // comparison which returns true. return v != v; } /** * Return true if the float has a value * equal to either NEGATIVE_INFINITY or * POSITIVE_INFINITY, otherwise return false. * * @param v the float to compare * @return whether the argument is (-/+) infinity */ public static boolean isInfinite(float v) { return v == POSITIVE_INFINITY || v == NEGATIVE_INFINITY; } /** * Return true if the value of this Float * is the same as NaN, otherwise return false. * * @return whether this Float is NaN */ public boolean isNaN() { return isNaN(value); } /** * Return true if the value of this Float * is the same as NEGATIVE_INFINITY or * POSITIVE_INFINITY, otherwise return false. * * @return whether this Float is (-/+) infinity */ public boolean isInfinite() { return isInfinite(value); } /** * Convert the float value of this Float * to a String. This method calls * Float.toString(float) to do its dirty work. * * @return the String representation * @see #toString(float) */ public String toString() { return toString(value); } /** * Return the value of this Float as a byte. * * @return the byte value * @since 1.1 */ public byte byteValue() { return (byte) value; } /** * Return the value of this Float as a short. * * @return the short value * @since 1.1 */ public short shortValue() { return (short) value; } /** * Return the value of this Integer as an int. * * @return the int value */ public int intValue() { return (int) value; } /** * Return the value of this Integer as a long. * * @return the long value */ public long longValue() { return (long) value; } /** * Return the value of this Float. * * @return the float value */ public float floatValue() { return value; } /** * Return the value of this Float as a double * * @return the double value */ public double doubleValue() { return value; } /** * Return a hashcode representing this Object. Float's hash * code is calculated by calling floatToIntBits(floatValue()). * * @return this Object's hash code * @see #floatToIntBits(float) */ public int hashCode() { return floatToIntBits(value); } /** * Returns true if obj is an instance of * Float and represents the same float value. Unlike comparing * two floats with ==, this treats two instances of * Float.NaN as equal, but treats 0.0 and * -0.0 as unequal. * *

Note that f1.equals(f2) is identical to * floatToIntBits(f1.floatValue()) == * floatToIntBits(f2.floatValue()). * * @param obj the object to compare * @return whether the objects are semantically equal */ public boolean equals(Object obj) { if (! (obj instanceof Float)) return false; float f = ((Float) obj).value; // Avoid call to native method. However, some implementations, like gcj, // are better off using floatToIntBits(value) == floatToIntBits(f). // Check common case first, then check NaN and 0. if (value == f) return (value != 0) || (1 / value == 1 / f); return isNaN(value) && isNaN(f); } /** * Convert the float to the IEEE 754 floating-point "single format" bit * layout. Bit 31 (the most significant) is the sign bit, bits 30-23 * (masked by 0x7f800000) represent the exponent, and bits 22-0 * (masked by 0x007fffff) are the mantissa. This function collapses all * versions of NaN to 0x7fc00000. The result of this function can be used * as the argument to Float.intBitsToFloat(int) to obtain the * original float value. * * @param value the float to convert * @return the bits of the float * @see #intBitsToFloat(int) */ public static native int floatToIntBits(float value); /** * Convert the float to the IEEE 754 floating-point "single format" bit * layout. Bit 31 (the most significant) is the sign bit, bits 30-23 * (masked by 0x7f800000) represent the exponent, and bits 22-0 * (masked by 0x007fffff) are the mantissa. This function leaves NaN alone, * rather than collapsing to a canonical value. The result of this function * can be used as the argument to Float.intBitsToFloat(int) to * obtain the original float value. * * @param value the float to convert * @return the bits of the float * @see #intBitsToFloat(int) */ public static native int floatToRawIntBits(float value); /** * Convert the argument in IEEE 754 floating-point "single format" bit * layout to the corresponding float. Bit 31 (the most significant) is the * sign bit, bits 30-23 (masked by 0x7f800000) represent the exponent, and * bits 22-0 (masked by 0x007fffff) are the mantissa. This function leaves * NaN alone, so that you can recover the bit pattern with * Float.floatToRawIntBits(float). * * @param bits the bits to convert * @return the float represented by the bits * @see #floatToIntBits(float) * @see #floatToRawIntBits(float) */ public static native float intBitsToFloat(int bits); /** * Compare two Floats numerically by comparing their float * values. The result is positive if the first is greater, negative if the * second is greater, and 0 if the two are equal. However, this special * cases NaN and signed zero as follows: NaN is considered greater than * all other floats, including POSITIVE_INFINITY, and positive * zero is considered greater than negative zero. * * @param f the Float to compare * @return the comparison * @since 1.2 */ public int compareTo(Float f) { return compare(value, f.value); } /** * Behaves like compareTo(Float) unless the Object * is not an Float. * * @param o the object to compare * @return the comparison * @throws ClassCastException if the argument is not a Float * @see #compareTo(Float) * @see Comparable * @since 1.2 */ public int compareTo(Object o) { return compare(value, ((Float) o).value); } /** * Behaves like new Float(x).compareTo(new Float(y)); in * other words this compares two floats, special casing NaN and zero, * without the overhead of objects. * * @param x the first float to compare * @param y the second float to compare * @return the comparison * @since 1.4 */ public static int compare(float x, float y) { if (isNaN(x)) return isNaN(y) ? 0 : 1; if (isNaN(y)) return -1; // recall that 0.0 == -0.0, so we convert to infinities and try again if (x == 0 && y == 0) return (int) (1 / x - 1 / y); if (x == y) return 0; return x > y ? 1 : -1; } }