home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / lang / Float.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  21.3 KB  |  537 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Float.java    1.48 98/07/23
  3.  *
  4.  * Copyright 1994-1998 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.48, 07/23/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>. It is equal 
  36.      * to the value returned by
  37.      * <code>Float.intBitsToFloat(0x7f800000)</code>.
  38.      */
  39.     public static final float POSITIVE_INFINITY = 1.0f / 0.0f;
  40.  
  41.     /**
  42.      * The negative infinity of type <code>float</code>. It is equal 
  43.      * to the value returned by
  44.      * <code>Float.intBitsToFloat(0xff800000)</code>.
  45.      */
  46.     public static final float NEGATIVE_INFINITY = -1.0f / 0.0f;
  47.  
  48.     /** 
  49.      * The Not-a-Number (NaN) value of type <code>float</code>. 
  50.      * It is equal to the value returned by
  51.      * <code>Float.intBitsToFloat(0x7fc00000)</code>. 
  52.      */
  53.     public static final float NaN = 0.0f / 0.0f;
  54.  
  55.     /**
  56.      * The largest positive value of type <code>float</code>. It is 
  57.      * equal to the value returned by 
  58.      * <code>Float.intBitsToFloat(0x7f7fffff)</code>.
  59.      */
  60.     public static final float MAX_VALUE = 3.40282346638528860e+38f;
  61.  
  62.     /**
  63.      * The smallest positive value of type <code>float</code>. It 
  64.      * is equal to the value returned by 
  65.      * <code>Float.intBitsToFloat(0x1)</code>.
  66.      */
  67.     public static final float MIN_VALUE = 1.40129846432481707e-45f;
  68.  
  69.     /**
  70.      * The Class object representing the primitive type float.
  71.      *
  72.      * @since   JDK1.1
  73.      */
  74.     public static final Class    TYPE = Class.getPrimitiveClass("float");
  75.  
  76.     /**
  77.      * Returns a String representation for the specified float value.
  78.      * The argument is converted to a readable string format as follows. 
  79.      * All characters and characters in strings mentioned below are ASCII 
  80.      * characters. 
  81.      * <ul>
  82.      * <li>If the argument is NaN, the result is the string <tt>"NaN"</tt>. 
  83.      * <li>Otherwise, the result is a string that represents the sign and 
  84.      *     magnitude (absolute value) of the argument. If the sign is 
  85.      *     negative, the first character of the result is <tt>'-'</tt> 
  86.      *     (<tt>'\u002d'</tt>); if the sign is positive, no sign character
  87.      *     appears in the result. As for the magnitude <var>m</var>: 
  88.      * <ul>
  89.      * <li>If <var>m</var> is infinity, it is represented by the characters 
  90.      *     <tt>"Infinity"</tt>; thus, positive infinity produces the result 
  91.      *     <tt>"Infinity"</tt> and negative infinity produces the result 
  92.      *     <tt>"-Infinity"</tt>. 
  93.      * <li>If <var>m</var> is zero, it is represented by the characters 
  94.      *     <tt>"0.0"</tt>; thus, negative zero produces the result 
  95.      *     <tt>"-0.0"</tt> and positive zero produces the result
  96.      *      <tt>"0.0"</tt>. 
  97.      * <li> If <var>m</var> is greater than or equal to 10<sup>-3</sup> but 
  98.      *      less than 10<sup>7</sup>, then it is represented as the integer 
  99.      *      part of <var>m</var>, in decimal form with no leading zeroes, 
  100.      *      followed by <tt>'.'</tt> (<tt>\u002E</tt>), followed by one or 
  101.      *      more decimal digits representing the fractional part of 
  102.      *      <var>m</var>. 
  103.      * <li> If <var>m</var> is less than 10<sup>-3</sup or not less than 
  104.      *      10<sup>7</sup>, then it is represented in so-called "computerized 
  105.      *      scientific notation." Let <var>n</var> be the unique integer 
  106.      *      such that 10<sup>n</sup><=<var>m</var><1; then let 
  107.      *      <var>a</var> be the mathematically exact quotient of <var>m</var> 
  108.      *      and 10<sup>n</sup> so that 1<<var>a</var><10. The magnitude 
  109.      *      is then represented as the integer part of <var>a</var>, as a 
  110.      *      single decimal digit, followed by <tt>'.'</tt> (<tt>\u002E</tt>), 
  111.      *      followed by decimal digits representing the fractional part of 
  112.      *      <var>a</var>, followed by the letter <tt>'E'</tt> 
  113.      *      (<tt>\u0045</tt>), followed by a representation of <var>n</var> 
  114.      *      as a decimal integer, as produced by the method
  115.      *      <tt>{@link java.lang.Integer#toString(int)}</tt> of one argument. 
  116.      * </ul>
  117.      * How many digits must be printed for the fractional part of 
  118.      * <var>m</var> or <var>a</var>? There must be at least one digit to 
  119.      * represent the fractional part, and beyond that as many, but only as 
  120.      * many, more digits as are needed to uniquely distinguish the argument
  121.      * value from adjacent values of type float. That is, suppose that 
  122.      * <var>x</var> is the exact mathematical value represented by the 
  123.      * decimal representation produced by this method for a finite nonzero 
  124.      * argument <var>f</var>. Then <var>f</var> must be the float value 
  125.      * nearest to <var>x</var>; or, if two float values are equally close to 
  126.      * <var>x</var>then <var>f</var> must be one of them and the least 
  127.      * significant bit of the significand of <var>f</var> must be <tt>0</tt>.
  128.      *
  129.      * @param   f   the float to be converted.
  130.      * @return  a string representation of the argument.
  131.      */
  132.     public static String toString(float f){
  133.     return new FloatingDecimal(f).toJavaFormatString();
  134.     }
  135.  
  136.     /**
  137.      * Returns the floating point value represented by the specified String. 
  138.      * The string <code>s</code> is interpreted as the representation of a 
  139.      * floating-point value and a <code>Float</code> object representing that 
  140.      * value is created and returned. 
  141.      * <p>
  142.      * If <code>s</code> is <code>null</code>, then a 
  143.      * <code>NullPointerException</code> is thrown. 
  144.      * <p>
  145.      * Leading and trailing whitespace characters in s are ignored. The rest 
  146.      * of <code>s</code> should constitute a <i>FloatValue</i> as described 
  147.      * by the lexical syntax rules:
  148.      * <blockquote><pre><i>
  149.      * FloatValue:
  150.      * 
  151.      *          Sign<sub>opt</sub> FloatingPointLiteral
  152.      * </i></pre></blockquote>          
  153.      * where <i>Sign</i>, <i>FloatingPointLiteral</i> are as defined in 
  154.      * ß3.10.2 of the 
  155.      * <a href="http://java.sun.com/docs/books/jls/html/">Java Language 
  156.      * Specification</a>. If it does not have the form of a <i>FloatValue</i>, 
  157.      * then a <code>NumberFormatException</code> is thrown. Otherwise, it is 
  158.      * regarded as representing an exact decimal value in the usual 
  159.      * "computerized scientific notation"; this exact decimal value is then
  160.      * conceptually converted to an "infinitely precise" binary value that 
  161.      * is then rounded to type float by the usual round-to-nearest rule of 
  162.      * IEEE 754 floating-point arithmetic.
  163.      *
  164.      * @param      s   the string to be parsed.
  165.      * @return     a newly constructed <code>Float</code> initialized to the
  166.      *             value represented by the <code>String</code> argument.
  167.      * @exception  NumberFormatException  if the string does not contain a
  168.      *               parsable number.
  169.      */
  170.     public static Float valueOf(String s) throws NumberFormatException {
  171.     return new Float(FloatingDecimal.readJavaFormatString(s).floatValue());
  172.     }
  173.  
  174.     /**
  175.      * Returns a new float initialized to the value represented by the 
  176.      * specified <code>String</code>, as performed by the <code>valueOf</code>
  177.      * method of class <code>Double</code>.
  178.      *
  179.      * @param      s   the string to be parsed.
  180.      * @return     the float value represented by the string argument.
  181.      * @exception  NumberFormatException  if the string does not contain a
  182.      *               parsable float.
  183.      * @see        java.lang.Double#valueOf(String)
  184.      * @since      JDK1.2
  185.      */
  186.     public static float parseFloat(String s) throws NumberFormatException {
  187.     return FloatingDecimal.readJavaFormatString(s).floatValue();
  188.     }
  189.  
  190.     /**
  191.      * Returns true if the specified number is the special Not-a-Number (NaN)
  192.      * value.
  193.      *
  194.      * @param   v   the value to be tested.
  195.      * @return  <code>true</code> if the argument is NaN;
  196.      *          <code>false</code> otherwise.
  197.      */
  198.     static public boolean isNaN(float v) {
  199.     return (v != v);
  200.     }
  201.  
  202.     /**
  203.      * Returns true if the specified number is infinitely large in magnitude.
  204.      *
  205.      * @param   v   the value to be tested.
  206.      * @return  <code>true</code> if the argument is positive infinity or
  207.      *          negative infinity; <code>false</code> otherwise.
  208.      */
  209.     static public boolean isInfinite(float v) {
  210.     return (v == POSITIVE_INFINITY) || (v == NEGATIVE_INFINITY);
  211.     }
  212.  
  213.     /**
  214.      * The value of the Float.
  215.      *
  216.      * @serial
  217.      */
  218.     private float value;
  219.  
  220.     /**
  221.      * Constructs a newly allocated <code>Float</code> object that
  222.      * represents the primitive <code>float</code> argument.
  223.      *
  224.      * @param   value   the value to be represented by the <code>Float</code>.
  225.      */
  226.     public Float(float value) {
  227.     this.value = value;
  228.     }
  229.  
  230.     /**
  231.      * Constructs a newly allocated <code>Float</code>object that
  232.      * represents the argument converted to type <code>float</code>.
  233.      *
  234.      * @param   value   the value to be represented by the <code>Float</code>.
  235.      */
  236.     public Float(double value) {
  237.     this.value = (float)value;
  238.     }
  239.  
  240.     /**
  241.      * Constructs a newly allocated <code>Float</code> object that 
  242.      * represents the floating-point value of type <code>float</code> 
  243.      * represented by the string. The string is converted to a 
  244.      * <code>float</code> value as if by the <code>valueOf</code> method. 
  245.      *
  246.      * @param      s   a string to be converted to a <code>Float</code>.
  247.      * @exception  NumberFormatException  if the string does not contain a
  248.      *               parsable number.
  249.      * @see        java.lang.Float#valueOf(java.lang.String)
  250.      */
  251.     public Float(String s) throws NumberFormatException {
  252.     // REMIND: this is inefficient
  253.     this(valueOf(s).floatValue());
  254.     }
  255.  
  256.     /**
  257.      * Returns true if this <code>Float</code> value is Not-a-Number (NaN).
  258.      *
  259.      * @return  <code>true</code> if the value represented by this object is
  260.      *          NaN; <code>false</code> otherwise.
  261.      */
  262.     public boolean isNaN() {
  263.     return isNaN(value);
  264.     }
  265.  
  266.     /**
  267.      * Returns true if this Float value is infinitely large in magnitude.
  268.      *
  269.      * @return  <code>true</code> if the value represented by this object is
  270.      *          positive infinity or negative infinity;
  271.      *          <code>false</code> otherwise.
  272.      */
  273.     public boolean isInfinite() {
  274.     return isInfinite(value);
  275.     }
  276.  
  277.     /**
  278.      * Returns a String representation of this Float object.
  279.      * The primitive <code>float</code> value represented by this object
  280.      * is converted to a <code>String</code> exactly as if by the method
  281.      * <code>toString</code> of one argument.
  282.      *
  283.      * @return  a <code>String</code> representation of this object.
  284.      * @see     java.lang.Float#toString(float)
  285.      */
  286.     public String toString() {
  287.     return String.valueOf(value);
  288.     }
  289.  
  290.     /**
  291.      * Returns the value of this Float as a byte (by casting to a byte).
  292.      *
  293.      * @since   JDK1.1
  294.      */
  295.     public byte byteValue() {
  296.     return (byte)value;
  297.     }
  298.  
  299.     /**
  300.      * Returns the value of this Float as a short (by casting to a short).
  301.      *
  302.      * @since   JDK1.1
  303.      */
  304.     public short shortValue() {
  305.     return (short)value;
  306.     }
  307.  
  308.     /**
  309.      * Returns the integer value of this Float (by casting to an int).
  310.      *
  311.      * @return  the <code>float</code> value represented by this object
  312.      *          converted to type <code>int</code> and the result of the
  313.      *          conversion is returned.
  314.      */
  315.     public int intValue() {
  316.     return (int)value;
  317.     }
  318.  
  319.     /**
  320.      * Returns the long value of this Float (by casting to a long).
  321.      *
  322.      * @return  the <code>float</code> value represented by this object is
  323.      *          converted to type <code>long</code> and the result of the
  324.      *          conversion is returned.
  325.      */
  326.     public long longValue() {
  327.     return (long)value;
  328.     }
  329.  
  330.     /**
  331.      * Returns the float value of this <tt>Float</tt> object.
  332.      *
  333.      * @return  the <code>float</code> value represented by this object.
  334.      */
  335.     public float floatValue() {
  336.     return value;
  337.     }
  338.  
  339.     /**
  340.      * Returns the double value of this <tt>Float</tt> object.
  341.      * 
  342.      * @return the <code>float</code> value represented by this 
  343.      *         object is converted to type <code>double</code> and the 
  344.      *         result of the conversion is returned.
  345.      */
  346.     public double doubleValue() {
  347.     return (double)value;
  348.     }
  349.  
  350.     /**
  351.      * Returns a hashcode for this <tt>Float</tt> object. The result 
  352.      * is the integer bit representation, exactly as produced
  353.      * by the method {@link #floatToIntBits(float)}, of the primitive float
  354.      * value represented by this <tt>Float</tt> object.
  355.      *
  356.      * @return  a hash code value for this object.
  357.      */
  358.     public int hashCode() {
  359.     return floatToIntBits(value);
  360.     }
  361.  
  362.     /**
  363.      * Compares this object against some other object.
  364.      * The result is <code>true</code> if and only if the argument is 
  365.      * not <code>null</code> and is a <code>Float</code> object that 
  366.      * represents a <code>float</code> that has the identical bit pattern 
  367.      * to the bit pattern of the <code>float</code> represented by this 
  368.      * object. For this purpose, two float values are considered to be
  369.      * the same if and only if the method {@link #floatToIntBits(float)} 
  370.      * returns the same int value when applied to each.
  371.      * <p>
  372.      * Note that in most cases, for two instances of class
  373.      * <code>Float</code>, <code>f1</code> and <code>f2</code>, the value
  374.      * of <code>f1.equals(f2)</code> is <code>true</code> if and only if
  375.      * <blockquote><pre>
  376.      *   f1.floatValue() == f2.floatValue()
  377.      * </pre></blockquote>
  378.      * <p>
  379.      * also has the value <code>true</code>. However, there are two exceptions:
  380.      * <ul>
  381.      * <li>If <code>f1</code> and <code>f2</code> both represent
  382.      *     <code>Float.NaN</code>, then the <code>equals</code> method returns
  383.      *     <code>true</code>, even though <code>Float.NaN==Float.NaN</code>
  384.      *     has the value <code>false</code>.
  385.      * <li>If <code>f1</code> represents <code>+0.0f</code> while
  386.      *     <code>f2</code> represents <code>-0.0f</code>, or vice versa,
  387.      *     the <code>equal</code> test has the value <code>false</code>,
  388.      *     even though <code>0.0f==-0.0f</code> has the value <code>true</code>.
  389.      * </ul>
  390.      * This definition allows hashtables to operate properly.
  391.      *
  392.      * @return  <code>true</code> if the objects are the same;
  393.      *          <code>false</code> otherwise.
  394.      * @see     java.lang.Float#floatToIntBits(float)
  395.      */
  396.     public boolean equals(Object obj) {
  397.     return (obj != null)
  398.            && (obj instanceof Float)
  399.            && (floatToIntBits(((Float)obj).value) == floatToIntBits(value));
  400.     }
  401.  
  402.     /**
  403.      * Returns the bit represention of a single-float value.
  404.      * The result is a representation of the floating-point argument 
  405.      * according to the IEEE 754 floating-point "single 
  406.      * precision" bit layout. 
  407.      * <ul>
  408.      * <li>Bit 31 (the bit that is selected by the mask 
  409.      * <code>0x80000000</code>) represents the sign of the floating-point 
  410.      * number. 
  411.      * <li>Bits 30-23 (the bits that are selected by the mask 
  412.      * <code>0x7f800000</code>) represent the exponent. 
  413.      * <li>Bits 22-0 (the bits that are selected by the mask 
  414.      * <code>0x007fffff</code>) represent the significand (sometimes called 
  415.      * the mantissa) of the floating-point number. 
  416.      * <li>If the argument is positive infinity, the result is 
  417.      * <code>0x7f800000</code>. 
  418.      * <li>If the argument is negative infinity, the result is 
  419.      * <code>0xff800000</code>. 
  420.      * <li>If the argument is NaN, the result is <code>0x7fc00000</code>. 
  421.      * </ul>
  422.      * In all cases, the result is an integer that, when given to the 
  423.      * {@link #intBitsToFloat(int)} method, will produce a floating-point 
  424.      * value equal to the argument to <code>floatToIntBits</code>.
  425.      * 
  426.      * @param   value   a floating-point number.
  427.      * @return  the bits that represent the floating-point number.
  428.      */
  429.     public static native int floatToIntBits(float value);
  430.  
  431.     /**
  432.      * Returns the single-float corresponding to a given bit represention.
  433.      * The argument is considered to be a representation of a
  434.      * floating-point value according to the IEEE 754 floating-point
  435.      * "single precision" bit layout.
  436.      * <p>
  437.      * If the argument is <code>0x7f800000</code>, the result is positive
  438.      * infinity.
  439.      * <p>
  440.      * If the argument is <code>0xff800000</code>, the result is negative
  441.      * infinity.
  442.      * <p>
  443.      * If the argument is any value in the range <code>0x7f800001</code> 
  444.      * through <code>0x7fffffff</code> or in the range 
  445.      * <code>0xff800001</code> through <code>0xffffffff</code>, the result is 
  446.      * NaN. All IEEE 754 NaN values are, in effect, lumped together by 
  447.      * the Java language into a single value called NaN. 
  448.      * <p>
  449.      * In all other cases, let <i>s</i>, <i>e</i>, and <i>m</i> be three 
  450.      * values that can be computed from the argument: 
  451.      * <blockquote><pre>
  452.      * int s = ((bits >> 31) == 0) ? 1 : -1;
  453.      * int e = ((bits >> 23) & 0xff);
  454.      * int m = (e == 0) ?
  455.      *                 (bits & 0x7fffff) << 1 :
  456.      *                 (bits & 0x7fffff) | 0x800000;
  457.      * </pre></blockquote>
  458.      * Then the floating-point result equals the value of the mathematical 
  459.      * expression <i>s·m·2<sup>e-150</sup></i>.
  460.      *
  461.      * @param   bits   an integer.
  462.      * @return  the single-format floating-point value with the same bit
  463.      *          pattern.
  464.      */
  465.     public static native float intBitsToFloat(int bits);
  466.  
  467.     /**
  468.      * Compares two Floats numerically.  There are two ways in which
  469.      * comparisons performed by this method differ from those performed
  470.      * by the Java language numerical comparison operators (<code><, <=,
  471.      * ==, >= ></code>) when applied to primitive floats:
  472.      * <ul><li>
  473.      *        <code>Float.NaN</code> is considered by this method to be
  474.      *        equal to itself and greater than all other float values
  475.      *        (including <code>Float.POSITIVE_INFINITY</code>).
  476.      * <li>
  477.      *        <code>0.0f</code> is considered by this method to be greater
  478.      *        than <code>-0.0f</code>.
  479.      * </ul>
  480.      * This ensures that Float.compareTo(Object) (which inherits its behavior
  481.      * from this method) obeys the general contract for Comparable.compareTo,
  482.      * and that the <i>natural order</i> on Floats is <i>total</i>.
  483.      *
  484.      * @param   anotherFloat   the <code>Float</code> to be compared.
  485.      * @return  the value <code>0</code> if <code>anotherFloat</code> is
  486.      *        numerically equal to this Float; a value less than
  487.      *          <code>0</code> if this Float is numerically less than
  488.      *        <code>anotherFloat</code>; and a value greater than
  489.      *        <code>0</code> if this Float is numerically greater than
  490.      *        <code>anotherFloat</code>.
  491.      *        
  492.      * @since   JDK1.2
  493.      * @see     Comparable#compareTo(Object)
  494.      */
  495.     public int compareTo(Float anotherFloat) {
  496.         float thisVal = value;
  497.         float anotherVal = anotherFloat.value;
  498.  
  499.         if (thisVal < anotherVal)
  500.             return -1;         // Neither val is NaN, thisVal is smaller
  501.         if (thisVal > anotherVal)
  502.             return 1;         // Neither val is NaN, thisVal is larger
  503.  
  504.         int thisBits = Float.floatToIntBits(thisVal);
  505.         int anotherBits = Float.floatToIntBits(anotherVal);
  506.  
  507.         return (thisBits == anotherBits ?  0 : // Values are equal
  508.                 (thisBits < anotherBits ? -1 : // (-0.0, 0.0) or (!NaN, NaN)
  509.                  1));                          // (0.0, -0.0) or (NaN, !NaN)
  510.     }
  511.  
  512.     /**
  513.      * Compares this Float to another Object.  If the Object is a Float,
  514.      * this function behaves like <code>compareTo(Float)</code>.  Otherwise,
  515.      * it throws a <code>ClassCastException</code> (as Floats are comparable
  516.      * only to other Floats).
  517.      *
  518.      * @param   o the <code>Object</code> to be compared.
  519.      * @return  the value <code>0</code> if the argument is a Float
  520.      *        numerically equal to this Float; a value less than
  521.      *        <code>0</code> if the argument is a Float numerically
  522.      *        greater than this Float; and a value greater than
  523.      *        <code>0</code> if the argument is a Float numerically
  524.      *        less than this Float.
  525.      * @exception <code>ClassCastException</code> if the argument is not a
  526.      *          <code>Float</code>.
  527.      * @see     java.lang.Comparable
  528.      * @since   JDK1.2
  529.      */
  530.     public int compareTo(Object o) {
  531.     return compareTo((Float)o);
  532.     }
  533.  
  534.     /** use serialVersionUID from JDK 1.0.2 for interoperability */
  535.     private static final long serialVersionUID = -2671257302660747028L;
  536. }
  537.