001    /* java.lang.Math -- common mathematical functions, native allowed
002       Copyright (C) 1998, 2001, 2002, 2003, 2006 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath 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 for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.lang;
040    
041    import gnu.classpath.Configuration;
042    
043    import java.util.Random;
044    
045    /**
046     * Helper class containing useful mathematical functions and constants.
047     * <P>
048     *
049     * Note that angles are specified in radians.  Conversion functions are
050     * provided for your convenience.
051     *
052     * @author Paul Fisher
053     * @author John Keiser
054     * @author Eric Blake (ebb9@email.byu.edu)
055     * @since 1.0
056     */
057    public final class Math
058    {
059      /**
060       * Math is non-instantiable
061       */
062      private Math()
063      {
064      }
065    
066      static
067      {
068        if (Configuration.INIT_LOAD_LIBRARY)
069          {
070            System.loadLibrary("javalang");
071          }
072      }
073    
074      /**
075       * A random number generator, initialized on first use.
076       */
077      private static Random rand;
078    
079      /**
080       * The most accurate approximation to the mathematical constant <em>e</em>:
081       * <code>2.718281828459045</code>. Used in natural log and exp.
082       *
083       * @see #log(double)
084       * @see #exp(double)
085       */
086      public static final double E = 2.718281828459045;
087    
088      /**
089       * The most accurate approximation to the mathematical constant <em>pi</em>:
090       * <code>3.141592653589793</code>. This is the ratio of a circle's diameter
091       * to its circumference.
092       */
093      public static final double PI = 3.141592653589793;
094    
095      /**
096       * Take the absolute value of the argument.
097       * (Absolute value means make it positive.)
098       * <P>
099       *
100       * Note that the the largest negative value (Integer.MIN_VALUE) cannot
101       * be made positive.  In this case, because of the rules of negation in
102       * a computer, MIN_VALUE is what will be returned.
103       * This is a <em>negative</em> value.  You have been warned.
104       *
105       * @param i the number to take the absolute value of
106       * @return the absolute value
107       * @see Integer#MIN_VALUE
108       */
109      public static int abs(int i)
110      {
111        return (i < 0) ? -i : i;
112      }
113    
114      /**
115       * Take the absolute value of the argument.
116       * (Absolute value means make it positive.)
117       * <P>
118       *
119       * Note that the the largest negative value (Long.MIN_VALUE) cannot
120       * be made positive.  In this case, because of the rules of negation in
121       * a computer, MIN_VALUE is what will be returned.
122       * This is a <em>negative</em> value.  You have been warned.
123       *
124       * @param l the number to take the absolute value of
125       * @return the absolute value
126       * @see Long#MIN_VALUE
127       */
128      public static long abs(long l)
129      {
130        return (l < 0) ? -l : l;
131      }
132    
133      /**
134       * Take the absolute value of the argument.
135       * (Absolute value means make it positive.)
136       * <P>
137       *
138       * This is equivalent, but faster than, calling
139       * <code>Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))</code>.
140       *
141       * @param f the number to take the absolute value of
142       * @return the absolute value
143       */
144      public static float abs(float f)
145      {
146        return (f <= 0) ? 0 - f : f;
147      }
148    
149      /**
150       * Take the absolute value of the argument.
151       * (Absolute value means make it positive.)
152       *
153       * This is equivalent, but faster than, calling
154       * <code>Double.longBitsToDouble(Double.doubleToLongBits(a)
155       *       &lt;&lt; 1) &gt;&gt;&gt; 1);</code>.
156       *
157       * @param d the number to take the absolute value of
158       * @return the absolute value
159       */
160      public static double abs(double d)
161      {
162        return (d <= 0) ? 0 - d : d;
163      }
164    
165      /**
166       * Return whichever argument is smaller.
167       *
168       * @param a the first number
169       * @param b a second number
170       * @return the smaller of the two numbers
171       */
172      public static int min(int a, int b)
173      {
174        return (a < b) ? a : b;
175      }
176    
177      /**
178       * Return whichever argument is smaller.
179       *
180       * @param a the first number
181       * @param b a second number
182       * @return the smaller of the two numbers
183       */
184      public static long min(long a, long b)
185      {
186        return (a < b) ? a : b;
187      }
188    
189      /**
190       * Return whichever argument is smaller. If either argument is NaN, the
191       * result is NaN, and when comparing 0 and -0, -0 is always smaller.
192       *
193       * @param a the first number
194       * @param b a second number
195       * @return the smaller of the two numbers
196       */
197      public static float min(float a, float b)
198      {
199        // this check for NaN, from JLS 15.21.1, saves a method call
200        if (a != a)
201          return a;
202        // no need to check if b is NaN; < will work correctly
203        // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
204        if (a == 0 && b == 0)
205          return -(-a - b);
206        return (a < b) ? a : b;
207      }
208    
209      /**
210       * Return whichever argument is smaller. If either argument is NaN, the
211       * result is NaN, and when comparing 0 and -0, -0 is always smaller.
212       *
213       * @param a the first number
214       * @param b a second number
215       * @return the smaller of the two numbers
216       */
217      public static double min(double a, double b)
218      {
219        // this check for NaN, from JLS 15.21.1, saves a method call
220        if (a != a)
221          return a;
222        // no need to check if b is NaN; < will work correctly
223        // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
224        if (a == 0 && b == 0)
225          return -(-a - b);
226        return (a < b) ? a : b;
227      }
228    
229      /**
230       * Return whichever argument is larger.
231       *
232       * @param a the first number
233       * @param b a second number
234       * @return the larger of the two numbers
235       */
236      public static int max(int a, int b)
237      {
238        return (a > b) ? a : b;
239      }
240    
241      /**
242       * Return whichever argument is larger.
243       *
244       * @param a the first number
245       * @param b a second number
246       * @return the larger of the two numbers
247       */
248      public static long max(long a, long b)
249      {
250        return (a > b) ? a : b;
251      }
252    
253      /**
254       * Return whichever argument is larger. If either argument is NaN, the
255       * result is NaN, and when comparing 0 and -0, 0 is always larger.
256       *
257       * @param a the first number
258       * @param b a second number
259       * @return the larger of the two numbers
260       */
261      public static float max(float a, float b)
262      {
263        // this check for NaN, from JLS 15.21.1, saves a method call
264        if (a != a)
265          return a;
266        // no need to check if b is NaN; > will work correctly
267        // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
268        if (a == 0 && b == 0)
269          return a - -b;
270        return (a > b) ? a : b;
271      }
272    
273      /**
274       * Return whichever argument is larger. If either argument is NaN, the
275       * result is NaN, and when comparing 0 and -0, 0 is always larger.
276       *
277       * @param a the first number
278       * @param b a second number
279       * @return the larger of the two numbers
280       */
281      public static double max(double a, double b)
282      {
283        // this check for NaN, from JLS 15.21.1, saves a method call
284        if (a != a)
285          return a;
286        // no need to check if b is NaN; > will work correctly
287        // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
288        if (a == 0 && b == 0)
289          return a - -b;
290        return (a > b) ? a : b;
291      }
292    
293      /**
294       * The trigonometric function <em>sin</em>. The sine of NaN or infinity is
295       * NaN, and the sine of 0 retains its sign. This is accurate within 1 ulp,
296       * and is semi-monotonic.
297       *
298       * @param a the angle (in radians)
299       * @return sin(a)
300       */
301      public static native double sin(double a);
302    
303      /**
304       * The trigonometric function <em>cos</em>. The cosine of NaN or infinity is
305       * NaN. This is accurate within 1 ulp, and is semi-monotonic.
306       *
307       * @param a the angle (in radians)
308       * @return cos(a)
309       */
310      public static native double cos(double a);
311    
312      /**
313       * The trigonometric function <em>tan</em>. The tangent of NaN or infinity
314       * is NaN, and the tangent of 0 retains its sign. This is accurate within 1
315       * ulp, and is semi-monotonic.
316       *
317       * @param a the angle (in radians)
318       * @return tan(a)
319       */
320      public static native double tan(double a);
321    
322      /**
323       * The trigonometric function <em>arcsin</em>. The range of angles returned
324       * is -pi/2 to pi/2 radians (-90 to 90 degrees). If the argument is NaN or
325       * its absolute value is beyond 1, the result is NaN; and the arcsine of
326       * 0 retains its sign. This is accurate within 1 ulp, and is semi-monotonic.
327       *
328       * @param a the sin to turn back into an angle
329       * @return arcsin(a)
330       */
331      public static native double asin(double a);
332    
333      /**
334       * The trigonometric function <em>arccos</em>. The range of angles returned
335       * is 0 to pi radians (0 to 180 degrees). If the argument is NaN or
336       * its absolute value is beyond 1, the result is NaN. This is accurate
337       * within 1 ulp, and is semi-monotonic.
338       *
339       * @param a the cos to turn back into an angle
340       * @return arccos(a)
341       */
342      public static native double acos(double a);
343    
344      /**
345       * The trigonometric function <em>arcsin</em>. The range of angles returned
346       * is -pi/2 to pi/2 radians (-90 to 90 degrees). If the argument is NaN, the
347       * result is NaN; and the arctangent of 0 retains its sign. This is accurate
348       * within 1 ulp, and is semi-monotonic.
349       *
350       * @param a the tan to turn back into an angle
351       * @return arcsin(a)
352       * @see #atan2(double, double)
353       */
354      public static native double atan(double a);
355    
356      /**
357       * A special version of the trigonometric function <em>arctan</em>, for
358       * converting rectangular coordinates <em>(x, y)</em> to polar
359       * <em>(r, theta)</em>. This computes the arctangent of x/y in the range
360       * of -pi to pi radians (-180 to 180 degrees). Special cases:<ul>
361       * <li>If either argument is NaN, the result is NaN.</li>
362       * <li>If the first argument is positive zero and the second argument is
363       * positive, or the first argument is positive and finite and the second
364       * argument is positive infinity, then the result is positive zero.</li>
365       * <li>If the first argument is negative zero and the second argument is
366       * positive, or the first argument is negative and finite and the second
367       * argument is positive infinity, then the result is negative zero.</li>
368       * <li>If the first argument is positive zero and the second argument is
369       * negative, or the first argument is positive and finite and the second
370       * argument is negative infinity, then the result is the double value
371       * closest to pi.</li>
372       * <li>If the first argument is negative zero and the second argument is
373       * negative, or the first argument is negative and finite and the second
374       * argument is negative infinity, then the result is the double value
375       * closest to -pi.</li>
376       * <li>If the first argument is positive and the second argument is
377       * positive zero or negative zero, or the first argument is positive
378       * infinity and the second argument is finite, then the result is the
379       * double value closest to pi/2.</li>
380       * <li>If the first argument is negative and the second argument is
381       * positive zero or negative zero, or the first argument is negative
382       * infinity and the second argument is finite, then the result is the
383       * double value closest to -pi/2.</li>
384       * <li>If both arguments are positive infinity, then the result is the
385       * double value closest to pi/4.</li>
386       * <li>If the first argument is positive infinity and the second argument
387       * is negative infinity, then the result is the double value closest to
388       * 3*pi/4.</li>
389       * <li>If the first argument is negative infinity and the second argument
390       * is positive infinity, then the result is the double value closest to
391       * -pi/4.</li>
392       * <li>If both arguments are negative infinity, then the result is the
393       * double value closest to -3*pi/4.</li>
394       *
395       * </ul><p>This is accurate within 2 ulps, and is semi-monotonic. To get r,
396       * use sqrt(x*x+y*y).
397       *
398       * @param y the y position
399       * @param x the x position
400       * @return <em>theta</em> in the conversion of (x, y) to (r, theta)
401       * @see #atan(double)
402       */
403      public static native double atan2(double y, double x);
404    
405      /**
406       * Take <em>e</em><sup>a</sup>.  The opposite of <code>log()</code>. If the
407       * argument is NaN, the result is NaN; if the argument is positive infinity,
408       * the result is positive infinity; and if the argument is negative
409       * infinity, the result is positive zero. This is accurate within 1 ulp,
410       * and is semi-monotonic.
411       *
412       * @param a the number to raise to the power
413       * @return the number raised to the power of <em>e</em>
414       * @see #log(double)
415       * @see #pow(double, double)
416       */
417      public static native double exp(double a);
418    
419      /**
420       * Take ln(a) (the natural log).  The opposite of <code>exp()</code>. If the
421       * argument is NaN or negative, the result is NaN; if the argument is
422       * positive infinity, the result is positive infinity; and if the argument
423       * is either zero, the result is negative infinity. This is accurate within
424       * 1 ulp, and is semi-monotonic.
425       *
426       * <p>Note that the way to get log<sub>b</sub>(a) is to do this:
427       * <code>ln(a) / ln(b)</code>.
428       *
429       * @param a the number to take the natural log of
430       * @return the natural log of <code>a</code>
431       * @see #exp(double)
432       */
433      public static native double log(double a);
434    
435      /**
436       * Take a square root. If the argument is NaN or negative, the result is
437       * NaN; if the argument is positive infinity, the result is positive
438       * infinity; and if the result is either zero, the result is the same.
439       * This is accurate within the limits of doubles.
440       *
441       * <p>For other roots, use pow(a, 1 / rootNumber).
442       *
443       * @param a the numeric argument
444       * @return the square root of the argument
445       * @see #pow(double, double)
446       */
447      public static native double sqrt(double a);
448    
449      /**
450       * Raise a number to a power. Special cases:<ul>
451       * <li>If the second argument is positive or negative zero, then the result
452       * is 1.0.</li>
453       * <li>If the second argument is 1.0, then the result is the same as the
454       * first argument.</li>
455       * <li>If the second argument is NaN, then the result is NaN.</li>
456       * <li>If the first argument is NaN and the second argument is nonzero,
457       * then the result is NaN.</li>
458       * <li>If the absolute value of the first argument is greater than 1 and
459       * the second argument is positive infinity, or the absolute value of the
460       * first argument is less than 1 and the second argument is negative
461       * infinity, then the result is positive infinity.</li>
462       * <li>If the absolute value of the first argument is greater than 1 and
463       * the second argument is negative infinity, or the absolute value of the
464       * first argument is less than 1 and the second argument is positive
465       * infinity, then the result is positive zero.</li>
466       * <li>If the absolute value of the first argument equals 1 and the second
467       * argument is infinite, then the result is NaN.</li>
468       * <li>If the first argument is positive zero and the second argument is
469       * greater than zero, or the first argument is positive infinity and the
470       * second argument is less than zero, then the result is positive zero.</li>
471       * <li>If the first argument is positive zero and the second argument is
472       * less than zero, or the first argument is positive infinity and the
473       * second argument is greater than zero, then the result is positive
474       * infinity.</li>
475       * <li>If the first argument is negative zero and the second argument is
476       * greater than zero but not a finite odd integer, or the first argument is
477       * negative infinity and the second argument is less than zero but not a
478       * finite odd integer, then the result is positive zero.</li>
479       * <li>If the first argument is negative zero and the second argument is a
480       * positive finite odd integer, or the first argument is negative infinity
481       * and the second argument is a negative finite odd integer, then the result
482       * is negative zero.</li>
483       * <li>If the first argument is negative zero and the second argument is
484       * less than zero but not a finite odd integer, or the first argument is
485       * negative infinity and the second argument is greater than zero but not a
486       * finite odd integer, then the result is positive infinity.</li>
487       * <li>If the first argument is negative zero and the second argument is a
488       * negative finite odd integer, or the first argument is negative infinity
489       * and the second argument is a positive finite odd integer, then the result
490       * is negative infinity.</li>
491       * <li>If the first argument is less than zero and the second argument is a
492       * finite even integer, then the result is equal to the result of raising
493       * the absolute value of the first argument to the power of the second
494       * argument.</li>
495       * <li>If the first argument is less than zero and the second argument is a
496       * finite odd integer, then the result is equal to the negative of the
497       * result of raising the absolute value of the first argument to the power
498       * of the second argument.</li>
499       * <li>If the first argument is finite and less than zero and the second
500       * argument is finite and not an integer, then the result is NaN.</li>
501       * <li>If both arguments are integers, then the result is exactly equal to
502       * the mathematical result of raising the first argument to the power of
503       * the second argument if that result can in fact be represented exactly as
504       * a double value.</li>
505       *
506       * </ul><p>(In the foregoing descriptions, a floating-point value is
507       * considered to be an integer if and only if it is a fixed point of the
508       * method {@link #ceil(double)} or, equivalently, a fixed point of the
509       * method {@link #floor(double)}. A value is a fixed point of a one-argument
510       * method if and only if the result of applying the method to the value is
511       * equal to the value.) This is accurate within 1 ulp, and is semi-monotonic.
512       *
513       * @param a the number to raise
514       * @param b the power to raise it to
515       * @return a<sup>b</sup>
516       */
517      public static native double pow(double a, double b);
518    
519      /**
520       * Get the IEEE 754 floating point remainder on two numbers. This is the
521       * value of <code>x - y * <em>n</em></code>, where <em>n</em> is the closest
522       * double to <code>x / y</code> (ties go to the even n); for a zero
523       * remainder, the sign is that of <code>x</code>. If either argument is NaN,
524       * the first argument is infinite, or the second argument is zero, the result
525       * is NaN; if x is finite but y is infinite, the result is x. This is
526       * accurate within the limits of doubles.
527       *
528       * @param x the dividend (the top half)
529       * @param y the divisor (the bottom half)
530       * @return the IEEE 754-defined floating point remainder of x/y
531       * @see #rint(double)
532       */
533      public static native double IEEEremainder(double x, double y);
534    
535      /**
536       * Take the nearest integer that is that is greater than or equal to the
537       * argument. If the argument is NaN, infinite, or zero, the result is the
538       * same; if the argument is between -1 and 0, the result is negative zero.
539       * Note that <code>Math.ceil(x) == -Math.floor(-x)</code>.
540       *
541       * @param a the value to act upon
542       * @return the nearest integer &gt;= <code>a</code>
543       */
544      public static native double ceil(double a);
545    
546      /**
547       * Take the nearest integer that is that is less than or equal to the
548       * argument. If the argument is NaN, infinite, or zero, the result is the
549       * same. Note that <code>Math.ceil(x) == -Math.floor(-x)</code>.
550       *
551       * @param a the value to act upon
552       * @return the nearest integer &lt;= <code>a</code>
553       */
554      public static native double floor(double a);
555    
556      /**
557       * Take the nearest integer to the argument.  If it is exactly between
558       * two integers, the even integer is taken. If the argument is NaN,
559       * infinite, or zero, the result is the same.
560       *
561       * @param a the value to act upon
562       * @return the nearest integer to <code>a</code>
563       */
564      public static native double rint(double a);
565    
566      /**
567       * Take the nearest integer to the argument.  This is equivalent to
568       * <code>(int) Math.floor(a + 0.5f)</code>. If the argument is NaN, the result
569       * is 0; otherwise if the argument is outside the range of int, the result
570       * will be Integer.MIN_VALUE or Integer.MAX_VALUE, as appropriate.
571       *
572       * @param a the argument to round
573       * @return the nearest integer to the argument
574       * @see Integer#MIN_VALUE
575       * @see Integer#MAX_VALUE
576       */
577      public static int round(float a)
578      {
579        // this check for NaN, from JLS 15.21.1, saves a method call
580        if (a != a)
581          return 0;
582        return (int) floor(a + 0.5f);
583      }
584    
585      /**
586       * Take the nearest long to the argument.  This is equivalent to
587       * <code>(long) Math.floor(a + 0.5)</code>. If the argument is NaN, the
588       * result is 0; otherwise if the argument is outside the range of long, the
589       * result will be Long.MIN_VALUE or Long.MAX_VALUE, as appropriate.
590       *
591       * @param a the argument to round
592       * @return the nearest long to the argument
593       * @see Long#MIN_VALUE
594       * @see Long#MAX_VALUE
595       */
596      public static long round(double a)
597      {
598        // this check for NaN, from JLS 15.21.1, saves a method call
599        if (a != a)
600          return 0;
601        return (long) floor(a + 0.5d);
602      }
603    
604      /**
605       * Get a random number.  This behaves like Random.nextDouble(), seeded by
606       * System.currentTimeMillis() when first called. In other words, the number
607       * is from a pseudorandom sequence, and lies in the range [+0.0, 1.0).
608       * This random sequence is only used by this method, and is threadsafe,
609       * although you may want your own random number generator if it is shared
610       * among threads.
611       *
612       * @return a random number
613       * @see Random#nextDouble()
614       * @see System#currentTimeMillis()
615       */
616      public static synchronized double random()
617      {
618        if (rand == null)
619          rand = new Random();
620        return rand.nextDouble();
621      }
622    
623      /**
624       * Convert from degrees to radians. The formula for this is
625       * radians = degrees * (pi/180); however it is not always exact given the
626       * limitations of floating point numbers.
627       *
628       * @param degrees an angle in degrees
629       * @return the angle in radians
630       * @since 1.2
631       */
632      public static double toRadians(double degrees)
633      {
634        return (degrees * PI) / 180;
635      }
636    
637      /**
638       * Convert from radians to degrees. The formula for this is
639       * degrees = radians * (180/pi); however it is not always exact given the
640       * limitations of floating point numbers.
641       *
642       * @param rads an angle in radians
643       * @return the angle in degrees
644       * @since 1.2
645       */
646      public static double toDegrees(double rads)
647      {
648        return (rads * 180) / PI;
649      }
650    
651      /**
652       * <p>
653       * Take a cube root. If the argument is <code>NaN</code>, an infinity or
654       * zero, then the original value is returned.  The returned result is
655       * within 1 ulp of the exact result.  For a finite value, <code>x</code>,
656       * the cube root of <code>-x</code> is equal to the negation of the cube root
657       * of <code>x</code>. 
658       * </p>
659       * <p>
660       * For a square root, use <code>sqrt</code>.  For other roots, use
661       * <code>pow(a, 1 / rootNumber)</code>.
662       * </p>
663       *
664       * @param a the numeric argument
665       * @return the cube root of the argument
666       * @see #sqrt(double)
667       * @see #pow(double, double)
668       * @since 1.5
669       */
670      public static native double cbrt(double a);
671    
672      /**
673       * <p>
674       * Returns the hyperbolic cosine of the given value.  For a value,
675       * <code>x</code>, the hyperbolic cosine is <code>(e<sup>x</sup> + 
676       * e<sup>-x</sup>)/2</code>
677       * with <code>e</code> being <a href="#E">Euler's number</a>.  The returned
678       * result is within 2.5 ulps of the exact result.
679       * </p>
680       * <p>
681       * If the supplied value is <code>NaN</code>, then the original value is
682       * returned.  For either infinity, positive infinity is returned.
683       * The hyperbolic cosine of zero is 1.0.
684       * </p>
685       * 
686       * @param a the numeric argument
687       * @return the hyperbolic cosine of <code>a</code>.
688       * @since 1.5
689       */
690      public static native double cosh(double a);
691    
692      /**
693       * <p>
694       * Returns <code>e<sup>a</sup> - 1.  For values close to 0, the
695       * result of <code>expm1(a) + 1</code> tend to be much closer to the
696       * exact result than simply <code>exp(x)</code>.  The result is within
697       * 1 ulp of the exact result, and results are semi-monotonic.  For finite
698       * inputs, the returned value is greater than or equal to -1.0.  Once
699       * a result enters within half a ulp of this limit, the limit is returned.
700       * </p>   
701       * <p>
702       * For <code>NaN</code>, positive infinity and zero, the original value
703       * is returned.  Negative infinity returns a result of -1.0 (the limit).
704       * </p>
705       * 
706       * @param a the numeric argument
707       * @return <code>e<sup>a</sup> - 1</code>
708       * @since 1.5
709       */
710      public static native double expm1(double a);
711    
712      /**
713       * <p>
714       * Returns the hypotenuse, <code>a<sup>2</sup> + b<sup>2</sup></code>,
715       * without intermediate overflow or underflow.  The returned result is
716       * within 1 ulp of the exact result.  If one parameter is held constant,
717       * then the result in the other parameter is semi-monotonic.
718       * </p>
719       * <p>
720       * If either of the arguments is an infinity, then the returned result
721       * is positive infinity.  Otherwise, if either argument is <code>NaN</code>,
722       * then <code>NaN</code> is returned.
723       * </p>
724       * 
725       * @param a the first parameter.
726       * @param b the second parameter.
727       * @return the hypotenuse matching the supplied parameters.
728       * @since 1.5
729       */
730      public static native double hypot(double a, double b);
731    
732      /**
733       * <p>
734       * Returns the base 10 logarithm of the supplied value.  The returned
735       * result is within 1 ulp of the exact result, and the results are
736       * semi-monotonic.
737       * </p>
738       * <p>
739       * Arguments of either <code>NaN</code> or less than zero return
740       * <code>NaN</code>.  An argument of positive infinity returns positive
741       * infinity.  Negative infinity is returned if either positive or negative
742       * zero is supplied.  Where the argument is the result of
743       * <code>10<sup>n</sup</code>, then <code>n</code> is returned.
744       * </p>
745       *
746       * @param a the numeric argument.
747       * @return the base 10 logarithm of <code>a</code>.
748       * @since 1.5
749       */
750      public static native double log10(double a);
751    
752      /**
753       * <p>
754       * Returns the natural logarithm resulting from the sum of the argument,
755       * <code>a</code> and 1.  For values close to 0, the
756       * result of <code>log1p(a)</code> tend to be much closer to the
757       * exact result than simply <code>log(1.0+a)</code>.  The returned
758       * result is within 1 ulp of the exact result, and the results are
759       * semi-monotonic.
760       * </p>
761       * <p>
762       * Arguments of either <code>NaN</code> or less than -1 return
763       * <code>NaN</code>.  An argument of positive infinity or zero
764       * returns the original argument.  Negative infinity is returned from an
765       * argument of -1.
766       * </p>
767       *
768       * @param a the numeric argument.
769       * @return the natural logarithm of <code>a</code> + 1.
770       * @since 1.5
771       */
772      public static native double log1p(double a);
773    
774      /**
775       * <p>
776       * Returns the sign of the argument as follows:
777       * </p>
778       * <ul>
779       * <li>If <code>a</code> is greater than zero, the result is 1.0.</li>
780       * <li>If <code>a</code> is less than zero, the result is -1.0.</li>
781       * <li>If <code>a</code> is <code>NaN</code>, the result is <code>NaN</code>.
782       * <li>If <code>a</code> is positive or negative zero, the result is the
783       * same.</li>
784       * </ul>
785       *
786       * @param a the numeric argument.
787       * @return the sign of the argument.
788       * @since 1.5.
789       */
790      public static double signum(double a)
791      {
792        if (Double.isNaN(a))
793          return Double.NaN;
794        if (a > 0)
795          return 1.0;
796        if (a < 0)
797          return -1.0;
798        return a;
799      }
800    
801      /**
802       * <p>
803       * Returns the sign of the argument as follows:
804       * </p>
805       * <ul>
806       * <li>If <code>a</code> is greater than zero, the result is 1.0f.</li>
807       * <li>If <code>a</code> is less than zero, the result is -1.0f.</li>
808       * <li>If <code>a</code> is <code>NaN</code>, the result is <code>NaN</code>.
809       * <li>If <code>a</code> is positive or negative zero, the result is the
810       * same.</li>
811       * </ul>
812       *
813       * @param a the numeric argument.
814       * @return the sign of the argument.
815       * @since 1.5.
816       */
817      public static float signum(float a)
818      {
819        if (Float.isNaN(a))
820          return Float.NaN;
821        if (a > 0)
822          return 1.0f;
823        if (a < 0)
824          return -1.0f;
825        return a;
826      }
827    
828      /**
829       * <p>
830       * Returns the hyperbolic sine of the given value.  For a value,
831       * <code>x</code>, the hyperbolic sine is <code>(e<sup>x</sup> - 
832       * e<sup>-x</sup>)/2</code>
833       * with <code>e</code> being <a href="#E">Euler's number</a>.  The returned
834       * result is within 2.5 ulps of the exact result.
835       * </p>
836       * <p>
837       * If the supplied value is <code>NaN</code>, an infinity or a zero, then the
838       * original value is returned.
839       * </p>
840       * 
841       * @param a the numeric argument
842       * @return the hyperbolic sine of <code>a</code>.
843       * @since 1.5
844       */
845      public static native double sinh(double a);
846    
847      /**
848       * <p>
849       * Returns the hyperbolic tangent of the given value.  For a value,
850       * <code>x</code>, the hyperbolic tangent is <code>(e<sup>x</sup> - 
851       * e<sup>-x</sup>)/(e<sup>x</sup> + e<sup>-x</sup>)</code>
852       * (i.e. <code>sinh(a)/cosh(a)</code>)
853       * with <code>e</code> being <a href="#E">Euler's number</a>.  The returned
854       * result is within 2.5 ulps of the exact result.  The absolute value
855       * of the exact result is always less than 1.  Computed results are thus
856       * less than or equal to 1 for finite arguments, with results within
857       * half a ulp of either positive or negative 1 returning the appropriate
858       * limit value (i.e. as if the argument was an infinity).
859       * </p>
860       * <p>
861       * If the supplied value is <code>NaN</code> or zero, then the original
862       * value is returned.  Positive infinity returns +1.0 and negative infinity
863       * returns -1.0.
864       * </p>
865       * 
866       * @param a the numeric argument
867       * @return the hyperbolic tangent of <code>a</code>.
868       * @since 1.5
869       */
870      public static native double tanh(double a);
871    
872      /**
873       * Return the ulp for the given double argument.  The ulp is the
874       * difference between the argument and the next larger double.  Note
875       * that the sign of the double argument is ignored, that is,
876       * ulp(x) == ulp(-x).  If the argument is a NaN, then NaN is returned.
877       * If the argument is an infinity, then +Inf is returned.  If the
878       * argument is zero (either positive or negative), then
879       * {@link Double#MIN_VALUE} is returned.
880       * @param d the double whose ulp should be returned
881       * @return the difference between the argument and the next larger double
882       * @since 1.5
883       */
884      public static double ulp(double d)
885      {
886        if (Double.isNaN(d))
887          return d;
888        if (Double.isInfinite(d))
889          return Double.POSITIVE_INFINITY;
890        // This handles both +0.0 and -0.0.
891        if (d == 0.0)
892          return Double.MIN_VALUE;
893        long bits = Double.doubleToLongBits(d);
894        final int mantissaBits = 52;
895        final int exponentBits = 11;
896        final long mantMask = (1L << mantissaBits) - 1;
897        long mantissa = bits & mantMask;
898        final long expMask = (1L << exponentBits) - 1;
899        long exponent = (bits >>> mantissaBits) & expMask;
900    
901        // Denormal number, so the answer is easy.
902        if (exponent == 0)
903          {
904            long result = (exponent << mantissaBits) | 1L;
905            return Double.longBitsToDouble(result);
906          }
907    
908        // Conceptually we want to have '1' as the mantissa.  Then we would
909        // shift the mantissa over to make a normal number.  If this underflows
910        // the exponent, we will make a denormal result.
911        long newExponent = exponent - mantissaBits;
912        long newMantissa;
913        if (newExponent > 0)
914          newMantissa = 0;
915        else
916          {
917            newMantissa = 1L << -(newExponent - 1);
918            newExponent = 0;
919          }
920        return Double.longBitsToDouble((newExponent << mantissaBits) | newMantissa);
921      }
922    
923      /**
924       * Return the ulp for the given float argument.  The ulp is the
925       * difference between the argument and the next larger float.  Note
926       * that the sign of the float argument is ignored, that is,
927       * ulp(x) == ulp(-x).  If the argument is a NaN, then NaN is returned.
928       * If the argument is an infinity, then +Inf is returned.  If the
929       * argument is zero (either positive or negative), then
930       * {@link Float#MIN_VALUE} is returned.
931       * @param f the float whose ulp should be returned
932       * @return the difference between the argument and the next larger float
933       * @since 1.5
934       */
935      public static float ulp(float f)
936      {
937        if (Float.isNaN(f))
938          return f;
939        if (Float.isInfinite(f))
940          return Float.POSITIVE_INFINITY;
941        // This handles both +0.0 and -0.0.
942        if (f == 0.0)
943          return Float.MIN_VALUE;
944        int bits = Float.floatToIntBits(f);
945        final int mantissaBits = 23;
946        final int exponentBits = 8;
947        final int mantMask = (1 << mantissaBits) - 1;
948        int mantissa = bits & mantMask;
949        final int expMask = (1 << exponentBits) - 1;
950        int exponent = (bits >>> mantissaBits) & expMask;
951    
952        // Denormal number, so the answer is easy.
953        if (exponent == 0)
954          {
955            int result = (exponent << mantissaBits) | 1;
956            return Float.intBitsToFloat(result);
957          }
958    
959        // Conceptually we want to have '1' as the mantissa.  Then we would
960        // shift the mantissa over to make a normal number.  If this underflows
961        // the exponent, we will make a denormal result.
962        int newExponent = exponent - mantissaBits;
963        int newMantissa;
964        if (newExponent > 0)
965          newMantissa = 0;
966        else
967          {
968            newMantissa = 1 << -(newExponent - 1);
969            newExponent = 0;
970          }
971        return Float.intBitsToFloat((newExponent << mantissaBits) | newMantissa);
972      }
973    }