001/* java.lang.Math -- common mathematical functions, native allowed
002   Copyright (C) 1998, 2001, 2002, 2003, 2006 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.lang;
040
041import gnu.classpath.Configuration;
042
043import 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 */
057public 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}