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