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