001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.lang;
028:
029: /**
030: * The Double class wraps a value of the primitive type
031: * <code>double</code> in an object. An object of type
032: * <code>Double</code> contains a single field whose type is
033: * <code>double</code>.
034: * <p>
035: * In addition, this class provides several methods for converting a
036: * <code>double</code> to a <code>String</code> and a
037: * <code>String</code> to a <code>double</code>, as well as other
038: * constants and methods useful when dealing with a
039: * <code>double</code>.
040: *
041: * @version 12/17/01 (CLDC 1.1)
042: * @since JDK1.0, CLDC 1.1
043: */
044: public final class Double {
045:
046: /**
047: * The positive infinity of type <code>double</code>.
048: * It is equal to the value returned by
049: * <code>Double.longBitsToDouble(0x7ff0000000000000L)</code>.
050: */
051: public static final double POSITIVE_INFINITY = 1.0 / 0.0;
052:
053: /**
054: * The negative infinity of type <code>double</code>.
055: * It is equal to the value returned by
056: * <code>Double.longBitsToDouble(0xfff0000000000000L)</code>.
057: */
058: public static final double NEGATIVE_INFINITY = -1.0 / 0.0;
059:
060: /**
061: * A Not-a-Number (NaN) value of type <code>double</code>.
062: * It is equal to the value returned by
063: * <code>Double.longBitsToDouble(0x7ff8000000000000L)</code>.
064: */
065: public static final double NaN = 0.0d / 0.0;
066:
067: /**
068: * The largest positive finite value of type <code>double</code>.
069: * It is equal to the value returned by
070: * <blockquote><pre>
071: * <code>Double.longBitsToDouble(0x7fefffffffffffffL)</code>
072: * </pre></blockquote>
073: */
074: public static final double MAX_VALUE = 1.79769313486231570e+308;
075:
076: /**
077: * The smallest positive value of type <code>double</code>.
078: * It is equal to the value returned by
079: * <code>Double.longBitsToDouble(0x1L)</code>.
080: */
081: public static final double MIN_VALUE = 4.94065645841246544e-324;
082:
083: /**
084: * Creates a string representation of the <code>double</code>
085: * argument. All characters mentioned below are ASCII characters.
086: * <ul>
087: * <li>If the argument is NaN, the result is the string "NaN".
088: * <li>Otherwise, the result is a string that represents the sign and
089: * magnitude (absolute value) of the argument. If the sign is negative,
090: * the first character of the result is '<code>-</code>'
091: * ('<code>\u002d</code>'); if the sign is positive, no sign character
092: * appears in the result. As for the magnitude <i>m</i>:
093: * <li>If <i>m</i> is infinity, it is represented by the characters
094: * <code>"Infinity"</code>; thus, positive infinity produces the result
095: * <code>"Infinity"</code> and negative infinity produces the result
096: * <code>"-Infinity"</code>.
097: * <li>If <i>m</i> is zero, it is represented by the characters
098: * <code>"0.0"</code>; thus, negative zero produces the result
099: * <code>"-0.0"</code> and positive zero produces the result
100: * <code>"0.0"</code>.
101: * <li>If <i>m</i> is greater than or equal to 10<sup>-3</sup> but less
102: * than 10<sup>7</sup>, then it is represented as the integer part of
103: * <i>m</i>, in decimal form with no leading zeroes, followed by
104: * <code>'.'</code> (<code>\u002E</code>), followed by one or more decimal
105: * digits representing the fractional part of <i>m</i>.
106: * <li>If <i>m</i> is less than 10<sup>-3</sup> or not less than
107: * 10<sup>7</sup>, then it is represented in so-called "computerized
108: * scientific notation." Let <i>n</i> be the unique integer such that
109: * 10<sup>n</sup><=<i>m</i><10<sup>n+1</sup>; then let <i>a</i> be
110: * the mathematically exact quotient of <i>m</i> and 10<sup>n</sup> so
111: * that 1<=<i>a</i><10. The magnitude is then represented as the
112: * integer part of <i>a</i>, as a single decimal digit, followed
113: * by <code>'.'</code> (<code>\u002E</code>), followed by decimal digits
114: * representing the fractional part of <i>a</i>, followed by the letter
115: * <code>'E'</code> (<code>\u0045</code>), followed by a representation
116: * of <i>n</i> as a decimal integer, as produced by the method
117: * {@link Integer#toString(int)}.
118: * </ul><p>
119: * How many digits must be printed for the fractional part of
120: * <i>m</i> or <i>a</i>? There must be at least one digit to represent
121: * the fractional part, and beyond that as many, but only as many, more
122: * digits as are needed to uniquely distinguish the argument value from
123: * adjacent values of type <code>double</code>. That is, suppose that
124: * <i>x</i> is the exact mathematical value represented by the decimal
125: * representation produced by this method for a finite nonzero argument
126: * <i>d</i>. Then <i>d</i> must be the <code>double</code> value nearest
127: * to <i>x</i>; or if two <code>double</code> values are equally close
128: * to <i>x</i>, then <i>d</i> must be one of them and the least
129: * significant bit of the significand of <i>d</i> must be <code>0</code>.
130: *
131: * @param d the <code>double</code> to be converted.
132: * @return a string representation of the argument.
133: */
134: public static String toString(double d) {
135: return new FloatingDecimal(d).toJavaFormatString();
136: }
137:
138: /**
139: * Returns a new <code>Double</code> object initialized to the value
140: * represented by the specified string. The string <code>s</code> is
141: * interpreted as the representation of a floating-point value and a
142: * <code>Double</code> object representing that value is created and
143: * returned.
144: * <p>
145: * If <code>s</code> is <code>null</code>, then a
146: * <code>NullPointerException</code> is thrown.
147: * <p>
148: * Leading and trailing whitespace characters in s are ignored. The rest
149: * of <code>s</code> should constitute a <i>FloatValue</i> as described
150: * by the lexical rule:
151: * <blockquote><pre><i>
152: * FloatValue:
153: *
154: * Sign<sub>opt</sub> FloatingPointLiteral
155: * </i></pre></blockquote>
156: * where <i>Sign</i> and <i>FloatingPointLiteral</i> are as defined in
157: * Section 3.10.2 of the <a href="http://java.sun.com/docs/books/jls/html/">Java
158: * Language Specification</a>. If it does not have the form of a
159: * <i>FloatValue</i>, then a <code>NumberFormatException</code> is
160: * thrown. Otherwise, it is regarded as representing an exact decimal
161: * value in the usual "computerized scientific notation"; this exact
162: * decimal value is then conceptually converted to an "infinitely
163: * precise" binary value that is then rounded to type <code>double</code>
164: * by the usual round-to-nearest rule of IEEE 754 floating-point
165: * arithmetic. Finally, a new object of class <code>Double</code> is
166: * created to represent the <code>double</code> value.
167: *
168: * @param s the string to be parsed.
169: * @return a newly constructed <code>Double</code> initialized to the
170: * value represented by the string argument.
171: * @exception NumberFormatException if the string does not contain a
172: * parsable number.
173: */
174: public static Double valueOf(String s) throws NumberFormatException {
175: return new Double(FloatingDecimal.readJavaFormatString(s)
176: .doubleValue());
177: }
178:
179: /**
180: * Returns a new double initialized to the value represented by the
181: * specified <code>String</code>, as performed by the <code>valueOf</code>
182: * method of class <code>Double</code>.
183: *
184: * @param s the string to be parsed.
185: * @return the double value represented by the string argument.
186: * @exception NumberFormatException if the string does not contain a
187: * parsable double.
188: * @see java.lang.Double#valueOf(String)
189: * @since JDK1.2
190: */
191: public static double parseDouble(String s)
192: throws NumberFormatException {
193: return FloatingDecimal.readJavaFormatString(s).doubleValue();
194: }
195:
196: /**
197: * Returns true if the specified number is the special Not-a-Number (NaN)
198: * value.
199: *
200: * @param v the value to be tested.
201: * @return <code>true</code> if the value of the argument is NaN;
202: * <code>false</code> otherwise.
203: */
204: static public boolean isNaN(double v) {
205: return (v != v);
206: }
207:
208: /**
209: * Returns true if the specified number is infinitely large in magnitude.
210: *
211: * @param v the value to be tested.
212: * @return <code>true</code> if the value of the argument is positive
213: * infinity or negative infinity; <code>false</code> otherwise.
214: */
215: static public boolean isInfinite(double v) {
216: return (v == POSITIVE_INFINITY) || (v == NEGATIVE_INFINITY);
217: }
218:
219: /**
220: * The value of the Double.
221: */
222: private double value;
223:
224: /**
225: * Constructs a newly allocated <code>Double</code> object that
226: * represents the primitive <code>double</code> argument.
227: *
228: * @param value the value to be represented by the <code>Double</code>.
229: */
230: public Double(double value) {
231: this .value = value;
232: }
233:
234: /**
235: * Constructs a newly allocated <code>Double</code> object that
236: * represents the floating- point value of type <code>double</code>
237: * represented by the string. The string is converted to a
238: * <code>double</code> value as if by the <code>valueOf</code> method.
239: *
240: * @param s a string to be converted to a <code>Double</code>.
241: * @exception NumberFormatException if the string does not contain a
242: * parsable number.
243: * @see java.lang.Double#valueOf(java.lang.String)
244: */
245: /* REMOVED from CLDC
246: public Double(String s) throws NumberFormatException {
247: // IMPL_NOTE: this is inefficient
248: this(valueOf(s).doubleValue());
249: }
250: */
251:
252: /**
253: * Returns true if this Double value is the special Not-a-Number (NaN)
254: * value.
255: *
256: * @return <code>true</code> if the value represented by this object is
257: * NaN; <code>false</code> otherwise.
258: */
259: public boolean isNaN() {
260: return isNaN(value);
261: }
262:
263: /**
264: * Returns true if this Double value is infinitely large in magnitude.
265: *
266: * @return <code>true</code> if the value represented by this object is
267: * positive infinity or negative infinity;
268: * <code>false</code> otherwise.
269: */
270: public boolean isInfinite() {
271: return isInfinite(value);
272: }
273:
274: /**
275: * Returns a String representation of this Double object.
276: * The primitive <code>double</code> value represented by this
277: * object is converted to a string exactly as if by the method
278: * <code>toString</code> of one argument.
279: *
280: * @return a <code>String</code> representation of this object.
281: * @see java.lang.Double#toString(double)
282: */
283: public String toString() {
284: return String.valueOf(value);
285: }
286:
287: /**
288: * Returns the value of this Double as a byte (by casting to a byte).
289: *
290: * @since JDK1.1
291: */
292: public byte byteValue() {
293: return (byte) value;
294: }
295:
296: /**
297: * Returns the value of this Double as a short (by casting to a short).
298: *
299: * @since JDK1.1
300: */
301: public short shortValue() {
302: return (short) value;
303: }
304:
305: /**
306: * Returns the integer value of this Double (by casting to an int).
307: *
308: * @return the <code>double</code> value represented by this object is
309: * converted to type <code>int</code> and the result of the
310: * conversion is returned.
311: */
312: public int intValue() {
313: return (int) value;
314: }
315:
316: /**
317: * Returns the long value of this Double (by casting to a long).
318: *
319: * @return the <code>double</code> value represented by this object is
320: * converted to type <code>long</code> and the result of the
321: * conversion is returned.
322: */
323: public long longValue() {
324: return (long) value;
325: }
326:
327: /**
328: * Returns the float value of this Double.
329: *
330: * @return the <code>double</code> value represented by this object is
331: * converted to type <code>float</code> and the result of the
332: * conversion is returned.
333: * @since JDK1.0
334: */
335: public float floatValue() {
336: return (float) value;
337: }
338:
339: /**
340: * Returns the double value of this Double.
341: *
342: * @return the <code>double</code> value represented by this object.
343: */
344: public double doubleValue() {
345: return (double) value;
346: }
347:
348: /**
349: * Returns a hashcode for this <code>Double</code> object. The result
350: * is the exclusive OR of the two halves of the long integer bit
351: * representation, exactly as produced by the method
352: * {@link #doubleToLongBits(double)}, of the primitive
353: * <code>double</code> value represented by this <code>Double</code>
354: * object. That is, the hashcode is the value of the expression:
355: * <blockquote><pre>
356: * (int)(v^(v>>>32))
357: * </pre></blockquote>
358: * where <code>v</code> is defined by:
359: * <blockquote><pre>
360: * long v = Double.doubleToLongBits(this.doubleValue());
361: * </pre></blockquote>
362: *
363: * @return a <code>hash code</code> value for this object.
364: */
365: public int hashCode() {
366: long bits = doubleToLongBits(value);
367: return (int) (bits ^ (bits >>> 32));
368: }
369:
370: /**
371: * Compares this object against the specified object.
372: * The result is <code>true</code> if and only if the argument is
373: * not <code>null</code> and is a <code>Double</code> object that
374: * represents a double that has the identical bit pattern to the bit
375: * pattern of the double represented by this object. For this purpose,
376: * two <code>double</code> values are considered to be the same if and
377: * only if the method {@link #doubleToLongBits(double)} returns the same
378: * long value when applied to each.
379: * <p>
380: * Note that in most cases, for two instances of class
381: * <code>Double</code>, <code>d1</code> and <code>d2</code>, the
382: * value of <code>d1.equals(d2)</code> is <code>true</code> if and
383: * only if
384: * <blockquote><pre>
385: * d1.doubleValue() == d2.doubleValue()
386: * </pre></blockquote>
387: * <p>
388: * also has the value <code>true</code>. However, there are two
389: * exceptions:
390: * <ul>
391: * <li>If <code>d1</code> and <code>d2</code> both represent
392: * <code>Double.NaN</code>, then the <code>equals</code> method
393: * returns <code>true</code>, even though
394: * <code>Double.NaN==Double.NaN</code> has the value
395: * <code>false</code>.
396: * <li>If <code>d1</code> represents <code>+0.0</code> while
397: * <code>d2</code> represents <code>-0.0</code>, or vice versa,
398: * the <code>equals</code> test has the value <code>false</code>,
399: * even though <code>+0.0==-0.0</code> has the value <code>true</code>.
400: * This allows hashtables to operate properly.
401: * </ul>
402: *
403: * @param obj the object to compare with.
404: * @return <code>true</code> if the objects are the same;
405: * <code>false</code> otherwise.
406: */
407: public boolean equals(Object obj) {
408: return (obj instanceof Double)
409: && (doubleToLongBits(((Double) obj).value) == doubleToLongBits(value));
410: }
411:
412: /**
413: * Returns a representation of the specified floating-point value
414: * according to the IEEE 754 floating-point "double
415: * format" bit layout.
416: * <p>
417: * Bit 63 (the bit that is selected by the mask
418: * <code>0x8000000000000000L</code>) represents the sign of the
419: * floating-point number. Bits
420: * 62-52 (the bits that are selected by the mask
421: * <code>0x7ff0000000000000L</code>) represent the exponent. Bits 51-0
422: * (the bits that are selected by the mask
423: * <code>0x000fffffffffffffL</code>) represent the significand
424: * (sometimes called the mantissa) of the floating-point number.
425: * <p>
426: * If the argument is positive infinity, the result is
427: * <code>0x7ff0000000000000L</code>.
428: * <p>
429: * If the argument is negative infinity, the result is
430: * <code>0xfff0000000000000L</code>.
431: * <p>
432: * If the argument is NaN, the result is
433: * <code>0x7ff8000000000000L</code>.
434: * <p>
435: * In all cases, the result is a <code>long</code> integer that, when
436: * given to the {@link #longBitsToDouble(long)} method, will produce a
437: * floating-point value equal to the argument to
438: * <code>doubleToLongBits</code>.
439: *
440: * @param value a double precision floating-point number.
441: * @return the bits that represent the floating-point number.
442: */
443: public static native long doubleToLongBits(double value);
444:
445: /**
446: * Returns a representation of the specified floating-point value
447: * according to the IEEE 754 floating-point "double
448: * format" bit layout.
449: * <p>
450: * Bit 63 (the bit that is selected by the mask
451: * <code>0x8000000000000000L</code>) represents the sign of the
452: * floating-point number. Bits
453: * 62-52 (the bits that are selected by the mask
454: * <code>0x7ff0000000000000L</code>) represent the exponent. Bits 51-0
455: * (the bits that are selected by the mask
456: * <code>0x000fffffffffffffL</code>) represent the significand
457: * (sometimes called the mantissa) of the floating-point number.
458: * <p>
459: * If the argument is positive infinity, the result is
460: * <code>0x7ff0000000000000L</code>.
461: * <p>
462: * If the argument is negative infinity, the result is
463: * <code>0xfff0000000000000L</code>.
464: * <p>
465: * If the argument is NaN, the result is the <code>long</code> integer
466: * representing the actual NaN value. Unlike the <code>doubleToLongBits</code>
467: * method, <code>doubleToRawLongBits</code> does not collapse NaN values.
468: * <p>
469: * In all cases, the result is a <code>long</code> integer that, when
470: * given to the {@link #longBitsToDouble(long)} method, will produce a
471: * floating-point value equal to the argument to
472: * <code>doubleToRawLongBits</code>.
473: *
474: * @param value a double precision floating-point number.
475: * @return the bits that represent the floating-point number.
476: */
477: /* REMOVED from CLDC
478: public static native long doubleToRawLongBits(double value);
479: */
480:
481: /**
482: * Returns the double-float corresponding to a given bit representation.
483: * The argument is considered to be a representation of a
484: * floating-point value according to the IEEE 754 floating-point
485: * "double precision" bit layout. That floating-point
486: * value is returned as the result.
487: * <p>
488: * If the argument is <code>0x7ff0000000000000L</code>, the result
489: * is positive infinity.
490: * <p>
491: * If the argument is <code>0xfff0000000000000L</code>, the result
492: * is negative infinity.
493: * <p>
494: * If the argument is any value in the range
495: * <code>0x7ff0000000000001L</code> through
496: * <code>0x7fffffffffffffffL</code> or in the range
497: * <code>0xfff0000000000001L</code> through
498: * <code>0xffffffffffffffffL</code>, the result is NaN. All IEEE 754
499: * NaN values of type <code>double</code> are, in effect, lumped together
500: * by the Java programming language into a single value called NaN.
501: * <p>
502: * In all other cases, let <i>s</i>, <i>e</i>, and <i>m</i> be three
503: * values that can be computed from the argument:
504: * <blockquote><pre>
505: * int s = ((bits >> 63) == 0) ? 1 : -1;
506: * int e = (int)((bits >> 52) & 0x7ffL);
507: * long m = (e == 0) ?
508: * (bits & 0xfffffffffffffL) << 1 :
509: * (bits & 0xfffffffffffffL) | 0x10000000000000L;
510: * </pre></blockquote>
511: * Then the floating-point result equals the value of the mathematical
512: * expression <i>s</i>·<i>m</i>·2<sup>e-1075</sup>.
513: *
514: * @param bits any <code>long</code> integer.
515: * @return the <code>double</code> floating-point value with the same
516: * bit pattern.
517: */
518: public static native double longBitsToDouble(long bits);
519:
520: /**
521: * Compares two Doubles numerically. There are two ways in which
522: * comparisons performed by this method differ from those performed
523: * by the Java language numerical comparison operators (<code><, <=,
524: * ==, >= ></code>) when applied to primitive doubles:
525: * <ul><li>
526: * <code>Double.NaN</code> is considered by this method to be
527: * equal to itself and greater than all other double values
528: * (including <code>Double.POSITIVE_INFINITY</code>).
529: * <li>
530: * <code>0.0d</code> is considered by this method to be greater
531: * than <code>-0.0d</code>.
532: * </ul>
533: * This ensures that Double.compareTo(Object) (which inherits its behavior
534: * from this method) obeys the general contract for Comparable.compareTo,
535: * and that the <i>natural order</i> on Doubles is <i>total</i>.
536: *
537: * @param anotherDouble the <code>Double</code> to be compared.
538: * @return the value <code>0</code> if <code>anotherDouble</code> is
539: * numerically equal to this Double; a value less than
540: * <code>0</code> if this Double is numerically less than
541: * <code>anotherDouble</code>; and a value greater than
542: * <code>0</code> if this Double is numerically greater than
543: * <code>anotherDouble</code>.
544: *
545: * @since JDK1.2
546: * @see Comparable#compareTo(Object)
547: */
548: /* REMOVED from CLDC
549: public int compareTo(Double anotherDouble) {
550: double thisVal = value;
551: double anotherVal = anotherDouble.value;
552:
553: if (thisVal < anotherVal)
554: return -1; // Neither val is NaN, thisVal is smaller
555: if (thisVal > anotherVal)
556: return 1; // Neither val is NaN, thisVal is larger
557:
558: long thisBits = Double.doubleToLongBits(thisVal);
559: long anotherBits = Double.doubleToLongBits(anotherVal);
560:
561: return (thisBits == anotherBits ? 0 : // Values are equal
562: (thisBits < anotherBits ? -1 : // (-0.0, 0.0) or (!NaN, NaN)
563: 1)); // (0.0, -0.0) or (NaN, !NaN)
564: }
565: */
566:
567: /**
568: * Compares this Double to another Object. If the Object is a Double,
569: * this function behaves like <code>compareTo(Double)</code>. Otherwise,
570: * it throws a <code>ClassCastException</code> (as Doubles are comparable
571: * only to other Doubles).
572: *
573: * @param o the <code>Object</code> to be compared.
574: * @return the value <code>0</code> if the argument is a Double
575: * numerically equal to this Double; a value less than
576: * <code>0</code> if the argument is a Double numerically
577: * greater than this Double; and a value greater than
578: * <code>0</code> if the argument is a Double numerically
579: * less than this Double.
580: * @exception <code>ClassCastException</code> if the argument is not a
581: * <code>Double</code>.
582: * @see java.lang.Comparable
583: * @since JDK1.2
584: */
585: /* REMOVED from CLDC
586: public int compareTo(Object o) {
587: return compareTo((Double)o);
588: }
589: */
590:
591: }
|