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