home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / lang / Float.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  13.6 KB  |  399 lines
  1. /*
  2.  * @(#)Float.java    1.43 98/03/18
  3.  *
  4.  * Copyright 1994-1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.lang;
  16.  
  17. /**
  18.  * The Float class wraps a value of primitive type <code>float</code> in 
  19.  * an object. An object of type <code>Float</code> contains a single 
  20.  * field whose type is <code>float</code>. 
  21.  * <p>
  22.  * In addition, this class provides several methods for converting a 
  23.  * <code>float</code> to a <code>String</code> and a 
  24.  * <code>String</code> to a <code>float</code>, as well as other 
  25.  * constants and methods useful when dealing with a 
  26.  * <code>float</code>. 
  27.  *
  28.  * @author  Lee Boynton
  29.  * @author  Arthur van Hoff
  30.  * @version 1.43, 03/18/98
  31.  * @since   JDK1.0
  32.  */
  33. public final class Float extends Number implements Comparable {
  34.     /**
  35.      * The positive infinity of type <code>float</code>. 
  36.      */
  37.     public static final float POSITIVE_INFINITY = 1.0f / 0.0f;
  38.  
  39.     /**
  40.      * The negative infinity of type <code>float</code>. 
  41.      */
  42.     public static final float NEGATIVE_INFINITY = -1.0f / 0.0f;
  43.  
  44.     /** 
  45.      * The NaN value of type <code>float</code>. 
  46.      */
  47.     public static final float NaN = 0.0f / 0.0f;
  48.  
  49.     /**
  50.      * The largest positive value of type <code>float</code>. 
  51.      */
  52.     public static final float MAX_VALUE = 3.40282346638528860e+38f;
  53.  
  54.     /**
  55.      * The smallest positive value of type <code>float</code>. 
  56.      */
  57.     public static final float MIN_VALUE = 1.40129846432481707e-45f;
  58.  
  59.     /**
  60.      * The Class object representing the primitive type float.
  61.      *
  62.      * @since   JDK1.1
  63.      */
  64.     public static final Class    TYPE = Class.getPrimitiveClass("float");
  65.  
  66.     /**
  67.      * Returns a String representation for the specified float value.
  68.      * <p>
  69.      * The values <code>NaN</code>, <code>NEGATIVE_INFINITY</code>, 
  70.      * <code>POSITIVE_INFINITY</code>, <code>-0.0</code>, and 
  71.      * <code>+0.0</code> are represented by the strings 
  72.      * <code>"NaN"</code>, <code>"-Infinity"</code>, 
  73.      * <code>"Infinity"</code>,<code> "-0.0"</code>, and 
  74.      * <code>"0.0"</code>, respectively. 
  75.      * <p>
  76.      * If <code>d</code> is in the range 
  77.      * <code>10<sup>-3</sup> <=
  78.      *   |d| <= 10<sup>7</sup></code>, 
  79.      * then it is converted to a <code>String</code> in the style 
  80.      * <code>[-]ddd.ddd</code>. Otherwise, it is converted to a 
  81.      * string in the style <code>[-]m.ddddE±xx</code>.
  82.      * <p>
  83.      * There is always a minimum of 1 digit after the decimal point. The 
  84.      * number of digits is the minimum needed to uniquely distinguish the 
  85.      * argument value from adjacent values of type <code>float</code>. 
  86.      *
  87.      * @param   d   the float to be converted.
  88.      * @return  a string representation of the argument.
  89.      */
  90.     public static String toString(float f){
  91.     return new FloatingDecimal(f).toJavaFormatString();
  92.     }
  93.  
  94.     /**
  95.      * Returns the floating point value represented by the specified String.
  96.      *
  97.      * @param      s   the string to be parsed.
  98.      * @return     a newly constructed <code>Float</code> initialized to the
  99.      *             value represented by the <code>String</code> argument.
  100.      * @exception  NumberFormatException  if the string does not contain a
  101.      *               parsable number.
  102.      */
  103.     public static Float valueOf(String s) throws NumberFormatException { 
  104.     return new Float(Double.valueOf0(s));
  105.     }
  106.  
  107.     /**
  108.      * Returns true if the specified number is the special Not-a-Number (NaN)
  109.      * value.
  110.      *
  111.      * @param   v   the value to be tested.
  112.      * @return  <code>true</code> if the argument is NaN;
  113.      *          <code>false</code> otherwise.
  114.      */
  115.     static public boolean isNaN(float v) {
  116.     return (v != v);
  117.     }
  118.  
  119.     /**
  120.      * Returns true if the specified number is infinitely large in magnitude.
  121.      *
  122.      * @param   v   the value to be tested.
  123.      * @return  <code>true</code> if the argument is positive infinity or
  124.      *          negative infinity; <code>false</code> otherwise.
  125.      */
  126.     static public boolean isInfinite(float v) {
  127.     return (v == POSITIVE_INFINITY) || (v == NEGATIVE_INFINITY);
  128.     }
  129.  
  130.     /**
  131.      * The value of the Float.
  132.      */
  133.     private float value;
  134.  
  135.     /**
  136.      * Constructs a newly allocated <code>Float</code> object that 
  137.      * represents the primitive <code>float</code> argument. 
  138.      *
  139.      * @param   value   the value to be represented by the <code>Float</code>.
  140.      */
  141.     public Float(float value) {
  142.     this.value = value;
  143.     }
  144.  
  145.     /**
  146.      * Constructs a newly allocated <code>Float</code>object that 
  147.      * represents the argument converted to type <code>float</code>.
  148.      *
  149.      * @param   value   the value to be represented by the <code>Float</code>.
  150.      */
  151.     public Float(double value) {
  152.     this.value = (float)value;
  153.     }
  154.  
  155.     /**
  156.      * Constructs a newly allocated <code>Float</code> object that 
  157.      * represents the floating- point value of type <code>float</code> 
  158.      * represented by the string. The string is converted to a 
  159.      * <code>float</code> value as if by the <code>valueOf</code> method. 
  160.      *
  161.      * @param      s   a string to be converted to a <code>Float</code>.
  162.      * @exception  NumberFormatException  if the string does not contain a
  163.      *               parsable number.
  164.      * @see        java.lang.Float#valueOf(java.lang.String)
  165.      */
  166.     public Float(String s) throws NumberFormatException {
  167.     // REMIND: this is inefficient
  168.     this(valueOf(s).floatValue());
  169.     }
  170.  
  171.     /**
  172.      * Returns true if this Float value is Not-a-Number (NaN).
  173.      *
  174.      * @return  <code>true</code> if the value represented by this object is
  175.      *          NaN; <code>false</code> otherwise.
  176.      */
  177.     public boolean isNaN() {
  178.     return isNaN(value);
  179.     }
  180.  
  181.     /**
  182.      * Returns true if this Float value is infinitely large in magnitude.
  183.      *
  184.      * @return  <code>true</code> if the value represented by this object is
  185.      *          positive infinity or negative infinity;
  186.      *          <code>false</code> otherwise.
  187.      */
  188.     public boolean isInfinite() {
  189.     return isInfinite(value);
  190.     }
  191.  
  192.     /**
  193.      * Returns a String representation of this Float object.
  194.      * The primitive <code>float</code> value represented by this object 
  195.      * is converted to a <code>String</code> exactly as if by the method 
  196.      * <code>toString</code> of one argument. 
  197.      *
  198.      * @return  a <code>String</code> representation of this object.
  199.      * @see     java.lang.Float#toString(float)
  200.      */
  201.     public String toString() {
  202.     return String.valueOf(value);
  203.     }
  204.  
  205.     /**
  206.      * Returns the value of this Float as a byte (by casting to a byte).
  207.      *
  208.      * @since   JDK1.1
  209.      */
  210.     public byte byteValue() {
  211.     return (byte)value;
  212.     }
  213.  
  214.     /**
  215.      * Returns the value of this Float as a short (by casting to a short).
  216.      *
  217.      * @since   JDK1.1
  218.      */
  219.     public short shortValue() {
  220.     return (short)value;
  221.     }
  222.  
  223.     /**
  224.      * Returns the integer value of this Float (by casting to an int).
  225.      *
  226.      * @return  the <code>float</code> value represented by this object
  227.      *          converted to type <code>int</code> and the result of the
  228.      *          conversion is returned.
  229.      */
  230.     public int intValue() {
  231.     return (int)value;
  232.     }
  233.  
  234.     /**
  235.      * Returns the long value of this Float (by casting to a long).
  236.      *
  237.      * @return  the <code>float</code> value represented by this object is
  238.      *          converted to type <code>long</code> and the result of the
  239.      *          conversion is returned.
  240.      */
  241.     public long longValue() {
  242.     return (long)value;
  243.     }
  244.  
  245.     /**
  246.      * Returns the float value of this Float object.
  247.      *
  248.      * @return  the <code>float</code> value represented by this object.
  249.      */
  250.     public float floatValue() {
  251.     return value;
  252.     }
  253.  
  254.     /**
  255.      * Returns the double value of this Float.
  256.      */
  257.     public double doubleValue() {
  258.     return (double)value;
  259.     }
  260.  
  261.     /**
  262.      * Returns a hashcode for this Float.
  263.      *
  264.      * @return  a hash code value for this object. 
  265.      */
  266.     public int hashCode() {
  267.     return floatToIntBits(value);
  268.     }
  269.  
  270.     /**
  271.      * Compares this object against some other object.
  272.      * The result is <code>true</code> if and only if the argument is 
  273.      * not <code>null</code> and is a <code>Float</code> object that 
  274.      * represents a <code>float</code> that has the identical bit pattern 
  275.      * to the bit pattern of the <code>float</code> represented by this 
  276.      * object. 
  277.      * <p>
  278.      * Note that in most cases, for two instances of class 
  279.      * <code>Float</code>, <code>f1</code> and <code>f2</code>, the value 
  280.      * of <code>f1.equals(f2)</code> is <code>true</code> if and only if 
  281.      * <blockquote><pre>
  282.      *   f1.floatValue() == f2.floatValue()
  283.      * </pre></blockquote>
  284.      * <p>
  285.      * also has the value <code>true</code>. However, there are two exceptions:
  286.      * <ul>
  287.      * <li>If <code>f1</code> and <code>f2</code> both represent 
  288.      *     <code>Float.NaN</code>, then the <code>equals</code> method returns 
  289.      *     <code>true</code>, even though <code>Float.NaN==Float.NaN</code> 
  290.      *     has the value <code>false</code>.
  291.      * <li>If <code>f1</code> represents <code>+0.0f</code> while
  292.      *     <code>f2</code> represents <code>-0.0f</code>, or vice versa,
  293.      *     the <code>equal</code> test has the value <code>false</code>,
  294.      *     even though <code>0.0f==-0.0f</code> has the value <code>true</code>.
  295.      * </ul>
  296.      *
  297.      * @return  <code>true</code> if the objects are the same;
  298.      *          <code>false</code> otherwise.
  299.      * @see     java.lang.Float#floatToIntBits(float)
  300.      */
  301.     public boolean equals(Object obj) {
  302.     return (obj != null)
  303.            && (obj instanceof Float) 
  304.            && (floatToIntBits(((Float)obj).value) == floatToIntBits(value));
  305.     }
  306.  
  307.     /**
  308.      * Returns the bit represention of a single-float value.
  309.      * The result is a representation of the floating-point argument 
  310.      * according to the IEEE 754 floating-point "single 
  311.      * precision" bit layout. 
  312.      * <p>
  313.      * Bit 31 represents the sign of the floating-point number. Bits 
  314.      * 30-23 represent the exponent. Bits 22-0 represent 
  315.      * the significand (sometimes called the mantissa) of the 
  316.      * floating-point number. 
  317.      * <p>
  318.      * If the argument is positive infinity, the result is 
  319.      * <code>0x7f800000</code>. 
  320.      * <p>
  321.      * If the argument is negative infinity, the result is 
  322.      * <code>0xff800000</code>. 
  323.      * <p>
  324.      * If the argument is NaN, the result is <code>0x7fc00000</code>. 
  325.      *
  326.      * @param   value   a floating-point number.
  327.      * @return  the bits that represent the floating-point number.
  328.      */
  329.     public static native int floatToIntBits(float value);
  330.  
  331.     /**
  332.      * Returns the single-float corresponding to a given bit represention.
  333.      * The argument is considered to be a representation of a 
  334.      * floating-point value according to the IEEE 754 floating-point 
  335.      * "single precision" bit layout.
  336.      * <p>
  337.      * If the argument is <code>0x7f800000</code>, the result is positive 
  338.      * infinity. 
  339.      * <p>
  340.      * If the argument is <code>0xff800000</code>, the result is negative 
  341.      * infinity. 
  342.      * <p>
  343.      * If the argument is any value in the range <code>0x7f800001</code> 
  344.      * through <code>0x7f8fffff</code> or in the range 
  345.      * <code>0xff800001</code> through <code>0xff8fffff</code>, the result is 
  346.      * NaN. All IEEE 754 NaN values are, in effect, lumped together by 
  347.      * the Java language into a single value. 
  348.      *
  349.      * @param   bits   an integer.
  350.      * @return  the single-format floating-point value with the same bit
  351.      *          pattern.
  352.      */
  353.     public static native float intBitsToFloat(int bits);
  354.  
  355.     /**
  356.      * Compares two Floats numerically.
  357.      *
  358.      * @param   anotherFloat   the <code>Float</code> to be compared.
  359.      * @return  the value <code>0</code> if the argument Float is equal to
  360.      *          this Float; a value less than <code>0</code> if this Float
  361.      *          is numerically less than the Float argument; and a
  362.      *          value greater than <code>0</code> if this Float is
  363.      *          numerically greater than the Float argument
  364.      *        (signed comparison).
  365.      * @since   JDK1.2
  366.      */
  367.     public int compareTo(Float anotherFloat) {
  368.     float thisVal = this.value;
  369.     float anotherVal = anotherFloat.value;
  370.     return (thisVal<anotherVal ? -1 : (thisVal==anotherVal ? 0 : 1));
  371.     }
  372.  
  373.  
  374.     /**
  375.      * Compares this Float to another Object.  If the Object is a Float,
  376.      * this function behaves like <code>compareTo(Float)</code>.  Otherwise,
  377.      * it throws a <code>ClassCastException</code> (as Floats are comparable
  378.      * only to other Floats).
  379.      *
  380.      * @param   o the <code>Object</code> to be compared.
  381.      * @return  the value <code>0</code> if the argument is a Float
  382.      *        numerically equal to this Float; a value less than
  383.      *        <code>0</code> if the argument is a Float numerically
  384.      *        greater than this Float; and a value greater than
  385.      *        <code>0</code> if the argument is a Float numerically
  386.      *        less than this Float.
  387.      * @exception <code>ClassCastException</code> if the argument is not a
  388.      *          <code>Float</code>. 
  389.      * @see     java.lang.Comparable
  390.      * @since   JDK1.2
  391.      */
  392.     public int compareTo(Object o) {
  393.     return compareTo((Float)o);
  394.     }
  395.  
  396.     /** use serialVersionUID from JDK 1.0.2 for interoperability */
  397.     private static final long serialVersionUID = -2671257302660747028L;
  398. }
  399.