libjava/java/lang/Math.java

   1 /* java.lang.Math -- common mathematical functions, native allowed
   2    Copyright (C) 1998, 2001, 2002, 2003 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.lang;
  40
  41 import java.util.Random;
  42 import gnu.classpath.Configuration;
  43
  44 /**
  45  * Helper class containing useful mathematical functions and constants.
  46  * <P>
  47  *
  48  * Note that angles are specified in radians.  Conversion functions are
  49  * provided for your convenience.
  50  *
  51  * @author Paul Fisher
  52  * @author John Keiser
  53  * @author Eric Blake <ebb9@email.byu.edu>
  54  * @since 1.0
  55  */
  56 public final class Math
  57 {
  58   /**
  59    * Math is non-instantiable
  60    */
  61   private Math()
  62   {
  63   }
  64
  65   static
  66   {
  67     if (Configuration.INIT_LOAD_LIBRARY)
  68       {
  69         System.loadLibrary("javalang");
  70       }
  71   }
  72
  73   /**
  74    * A random number generator, initialized on first use.
  75    */
  76   private static Random rand;
  77
  78   /**
  79    * The most accurate approximation to the mathematical constant <em>e</em>:
  80    * <code>2.718281828459045</code>. Used in natural log and exp.
  81    *
  82    * @see #log(double)
  83    * @see #exp(double)
  84    */
  85   public static final double E = 2.718281828459045;
  86
  87   /**
  88    * The most accurate approximation to the mathematical constant <em>pi</em>:
  89    * <code>3.141592653589793</code>. This is the ratio of a circle's diameter
  90    * to its circumference.
  91    */
  92   public static final double PI = 3.141592653589793;
  93
  94   /**
  95    * Take the absolute value of the argument.
  96    * (Absolute value means make it positive.)
  97    * <P>
  98    *
  99    * Note that the the largest negative value (Integer.MIN_VALUE) cannot
 100    * be made positive.  In this case, because of the rules of negation in
 101    * a computer, MIN_VALUE is what will be returned.
 102    * This is a <em>negative</em> value.  You have been warned.
 103    *
 104    * @param i the number to take the absolute value of
 105    * @return the absolute value
 106    * @see Integer#MIN_VALUE
 107    */
 108   public static int abs(int i)
 109   {
 110     return (i < 0) ? -i : i;
 111   }
 112
 113   /**
 114    * Take the absolute value of the argument.
 115    * (Absolute value means make it positive.)
 116    * <P>
 117    *
 118    * Note that the the largest negative value (Long.MIN_VALUE) cannot
 119    * be made positive.  In this case, because of the rules of negation in
 120    * a computer, MIN_VALUE is what will be returned.
 121    * This is a <em>negative</em> value.  You have been warned.
 122    *
 123    * @param l the number to take the absolute value of
 124    * @return the absolute value
 125    * @see Long#MIN_VALUE
 126    */
 127   public static long abs(long l)
 128   {
 129     return (l < 0) ? -l : l;
 130   }
 131
 132   /**
 133    * Take the absolute value of the argument.
 134    * (Absolute value means make it positive.)
 135    * <P>
 136    *
 137    * This is equivalent, but faster than, calling
 138    * <code>Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))</code>.
 139    *
 140    * @param f the number to take the absolute value of
 141    * @return the absolute value
 142    */
 143   public static float abs(float f)
 144   {
 145     return (f <= 0) ? 0 - f : f;
 146   }
 147
 148   /**
 149    * Take the absolute value of the argument.
 150    * (Absolute value means make it positive.)
 151    *
 152    * This is equivalent, but faster than, calling
 153    * <code>Double.longBitsToDouble(Double.doubleToLongBits(a)
 154    *       &lt;&lt; 1) &gt;&gt;&gt; 1);</code>.
 155    *
 156    * @param d the number to take the absolute value of
 157    * @return the absolute value
 158    */
 159   public static double abs(double d)
 160   {
 161     return (d <= 0) ? 0 - d : d;
 162   }
 163
 164   /**
 165    * Return whichever argument is smaller.
 166    *
 167    * @param a the first number
 168    * @param b a second number
 169    * @return the smaller of the two numbers
 170    */
 171   public static int min(int a, int b)
 172   {
 173     return (a < b) ? a : b;
 174   }
 175
 176   /**
 177    * Return whichever argument is smaller.
 178    *
 179    * @param a the first number
 180    * @param b a second number
 181    * @return the smaller of the two numbers
 182    */
 183   public static long min(long a, long b)
 184   {
 185     return (a < b) ? a : b;
 186   }
 187
 188   /**
 189    * Return whichever argument is smaller. If either argument is NaN, the
 190    * result is NaN, and when comparing 0 and -0, -0 is always smaller.
 191    *
 192    * @param a the first number
 193    * @param b a second number
 194    * @return the smaller of the two numbers
 195    */
 196   public static float min(float a, float b)
 197   {
 198     // this check for NaN, from JLS 15.21.1, saves a method call
 199     if (a != a)
 200       return a;
 201     // no need to check if b is NaN; < will work correctly
 202     // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
 203     if (a == 0 && b == 0)
 204       return -(-a - b);
 205     return (a < b) ? a : b;
 206   }
 207
 208   /**
 209    * Return whichever argument is smaller. If either argument is NaN, the
 210    * result is NaN, and when comparing 0 and -0, -0 is always smaller.
 211    *
 212    * @param a the first number
 213    * @param b a second number
 214    * @return the smaller of the two numbers
 215    */
 216   public static double min(double a, double b)
 217   {
 218     // this check for NaN, from JLS 15.21.1, saves a method call
 219     if (a != a)
 220       return a;
 221     // no need to check if b is NaN; < will work correctly
 222     // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
 223     if (a == 0 && b == 0)
 224       return -(-a - b);
 225     return (a < b) ? a : b;
 226   }
 227
 228   /**
 229    * Return whichever argument is larger.
 230    *
 231    * @param a the first number
 232    * @param b a second number
 233    * @return the larger of the two numbers
 234    */
 235   public static int max(int a, int b)
 236   {
 237     return (a > b) ? a : b;
 238   }
 239
 240   /**
 241    * Return whichever argument is larger.
 242    *
 243    * @param a the first number
 244    * @param b a second number
 245    * @return the larger of the two numbers
 246    */
 247   public static long max(long a, long b)
 248   {
 249     return (a > b) ? a : b;
 250   }
 251
 252   /**
 253    * Return whichever argument is larger. If either argument is NaN, the
 254    * result is NaN, and when comparing 0 and -0, 0 is always larger.
 255    *
 256    * @param a the first number
 257    * @param b a second number
 258    * @return the larger of the two numbers
 259    */
 260   public static float max(float a, float b)
 261   {
 262     // this check for NaN, from JLS 15.21.1, saves a method call
 263     if (a != a)
 264       return a;
 265     // no need to check if b is NaN; > will work correctly
 266     // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
 267     if (a == 0 && b == 0)
 268       return a - -b;
 269     return (a > b) ? a : b;
 270   }
 271
 272   /**
 273    * Return whichever argument is larger. If either argument is NaN, the
 274    * result is NaN, and when comparing 0 and -0, 0 is always larger.
 275    *
 276    * @param a the first number
 277    * @param b a second number
 278    * @return the larger of the two numbers
 279    */
 280   public static double max(double a, double b)
 281   {
 282     // this check for NaN, from JLS 15.21.1, saves a method call
 283     if (a != a)
 284       return a;
 285     // no need to check if b is NaN; > will work correctly
 286     // recall that -0.0 == 0.0, but [+-]0.0 - [+-]0.0 behaves special
 287     if (a == 0 && b == 0)
 288       return a - -b;
 289     return (a > b) ? a : b;
 290   }
 291
 292   /**
 293    * The trigonometric function <em>sin</em>. The sine of NaN or infinity is
 294    * NaN, and the sine of 0 retains its sign. This is accurate within 1 ulp,
 295    * and is semi-monotonic.
 296    *
 297    * @param a the angle (in radians)
 298    * @return sin(a)
 299    */
 300   public native static double sin(double a);
 301
 302   /**
 303    * The trigonometric function <em>cos</em>. The cosine of NaN or infinity is
 304    * NaN. This is accurate within 1 ulp, and is semi-monotonic.
 305    *
 306    * @param a the angle (in radians)
 307    * @return cos(a)
 308    */
 309   public native static double cos(double a);
 310
 311   /**
 312    * The trigonometric function <em>tan</em>. The tangent of NaN or infinity
 313    * is NaN, and the tangent of 0 retains its sign. This is accurate within 1
 314    * ulp, and is semi-monotonic.
 315    *
 316    * @param a the angle (in radians)
 317    * @return tan(a)
 318    */
 319   public native static double tan(double a);
 320
 321   /**
 322    * The trigonometric function <em>arcsin</em>. The range of angles returned
 323    * is -pi/2 to pi/2 radians (-90 to 90 degrees). If the argument is NaN or
 324    * its absolute value is beyond 1, the result is NaN; and the arcsine of
 325    * 0 retains its sign. This is accurate within 1 ulp, and is semi-monotonic.
 326    *
 327    * @param a the sin to turn back into an angle
 328    * @return arcsin(a)
 329    */
 330   public native static double asin(double a);
 331
 332   /**
 333    * The trigonometric function <em>arccos</em>. The range of angles returned
 334    * is 0 to pi radians (0 to 180 degrees). If the argument is NaN or
 335    * its absolute value is beyond 1, the result is NaN. This is accurate
 336    * within 1 ulp, and is semi-monotonic.
 337    *
 338    * @param a the cos to turn back into an angle
 339    * @return arccos(a)
 340    */
 341   public native static double acos(double a);
 342
 343   /**
 344    * The trigonometric function <em>arcsin</em>. The range of angles returned
 345    * is -pi/2 to pi/2 radians (-90 to 90 degrees). If the argument is NaN, the
 346    * result is NaN; and the arctangent of 0 retains its sign. This is accurate
 347    * within 1 ulp, and is semi-monotonic.
 348    *
 349    * @param a the tan to turn back into an angle
 350    * @return arcsin(a)
 351    * @see #atan2(double, double)
 352    */
 353   public native static double atan(double a);
 354
 355   /**
 356    * A special version of the trigonometric function <em>arctan</em>, for
 357    * converting rectangular coordinates <em>(x, y)</em> to polar
 358    * <em>(r, theta)</em>. This computes the arctangent of x/y in the range
 359    * of -pi to pi radians (-180 to 180 degrees). Special cases:<ul>
 360    * <li>If either argument is NaN, the result is NaN.</li>
 361    * <li>If the first argument is positive zero and the second argument is
 362    * positive, or the first argument is positive and finite and the second
 363    * argument is positive infinity, then the result is positive zero.</li>
 364    * <li>If the first argument is negative zero and the second argument is
 365    * positive, or the first argument is negative and finite and the second
 366    * argument is positive infinity, then the result is negative zero.</li>
 367    * <li>If the first argument is positive zero and the second argument is
 368    * negative, or the first argument is positive and finite and the second
 369    * argument is negative infinity, then the result is the double value
 370    * closest to pi.</li>
 371    * <li>If the first argument is negative zero and the second argument is
 372    * negative, or the first argument is negative and finite and the second
 373    * argument is negative infinity, then the result is the double value
 374    * closest to -pi.</li>
 375    * <li>If the first argument is positive and the second argument is
 376    * positive zero or negative zero, or the first argument is positive
 377    * infinity and the second argument is finite, then the result is the
 378    * double value closest to pi/2.</li>
 379    * <li>If the first argument is negative and the second argument is
 380    * positive zero or negative zero, or the first argument is negative
 381    * infinity and the second argument is finite, then the result is the
 382    * double value closest to -pi/2.</li>
 383    * <li>If both arguments are positive infinity, then the result is the
 384    * double value closest to pi/4.</li>
 385    * <li>If the first argument is positive infinity and the second argument
 386    * is negative infinity, then the result is the double value closest to
 387    * 3*pi/4.</li>
 388    * <li>If the first argument is negative infinity and the second argument
 389    * is positive infinity, then the result is the double value closest to
 390    * -pi/4.</li>
 391    * <li>If both arguments are negative infinity, then the result is the
 392    * double value closest to -3*pi/4.</li>
 393    *
 394    * </ul><p>This is accurate within 2 ulps, and is semi-monotonic. To get r,
 395    * use sqrt(x*x+y*y).
 396    *
 397    * @param y the y position
 398    * @param x the x position
 399    * @return <em>theta</em> in the conversion of (x, y) to (r, theta)
 400    * @see #atan(double)
 401    */
 402   public native static double atan2(double y, double x);
 403
 404   /**
 405    * Take <em>e</em><sup>a</sup>.  The opposite of <code>log()</code>. If the
 406    * argument is NaN, the result is NaN; if the argument is positive infinity,
 407    * the result is positive infinity; and if the argument is negative
 408    * infinity, the result is positive zero. This is accurate within 1 ulp,
 409    * and is semi-monotonic.
 410    *
 411    * @param a the number to raise to the power
 412    * @return the number raised to the power of <em>e</em>
 413    * @see #log(double)
 414    * @see #pow(double, double)
 415    */
 416   public native static double exp(double a);
 417
 418   /**
 419    * Take ln(a) (the natural log).  The opposite of <code>exp()</code>. If the
 420    * argument is NaN or negative, the result is NaN; if the argument is
 421    * positive infinity, the result is positive infinity; and if the argument
 422    * is either zero, the result is negative infinity. This is accurate within
 423    * 1 ulp, and is semi-monotonic.
 424    *
 425    * <p>Note that the way to get log<sub>b</sub>(a) is to do this:
 426    * <code>ln(a) / ln(b)</code>.
 427    *
 428    * @param a the number to take the natural log of
 429    * @return the natural log of <code>a</code>
 430    * @see #exp(double)
 431    */
 432   public native static double log(double a);
 433
 434   /**
 435    * Take a square root. If the argument is NaN or negative, the result is
 436    * NaN; if the argument is positive infinity, the result is positive
 437    * infinity; and if the result is either zero, the result is the same.
 438    * This is accurate within the limits of doubles.
 439    *
 440    * <p>For other roots, use pow(a, 1 / rootNumber).
 441    *
 442    * @param a the numeric argument
 443    * @return the square root of the argument
 444    * @see #pow(double, double)
 445    */
 446   public native static double sqrt(double a);
 447
 448   /**
 449    * Raise a number to a power. Special cases:<ul>
 450    * <li>If the second argument is positive or negative zero, then the result
 451    * is 1.0.</li>
 452    * <li>If the second argument is 1.0, then the result is the same as the
 453    * first argument.</li>
 454    * <li>If the second argument is NaN, then the result is NaN.</li>
 455    * <li>If the first argument is NaN and the second argument is nonzero,
 456    * then the result is NaN.</li>
 457    * <li>If the absolute value of the first argument is greater than 1 and
 458    * the second argument is positive infinity, or the absolute value of the
 459    * first argument is less than 1 and the second argument is negative
 460    * infinity, then the result is positive infinity.</li>
 461    * <li>If the absolute value of the first argument is greater than 1 and
 462    * the second argument is negative infinity, or the absolute value of the
 463    * first argument is less than 1 and the second argument is positive
 464    * infinity, then the result is positive zero.</li>
 465    * <li>If the absolute value of the first argument equals 1 and the second
 466    * argument is infinite, then the result is NaN.</li>
 467    * <li>If the first argument is positive zero and the second argument is
 468    * greater than zero, or the first argument is positive infinity and the
 469    * second argument is less than zero, then the result is positive zero.</li>
 470    * <li>If the first argument is positive zero and the second argument is
 471    * less than zero, or the first argument is positive infinity and the
 472    * second argument is greater than zero, then the result is positive
 473    * infinity.</li>
 474    * <li>If the first argument is negative zero and the second argument is
 475    * greater than zero but not a finite odd integer, or the first argument is
 476    * negative infinity and the second argument is less than zero but not a
 477    * finite odd integer, then the result is positive zero.</li>
 478    * <li>If the first argument is negative zero and the second argument is a
 479    * positive finite odd integer, or the first argument is negative infinity
 480    * and the second argument is a negative finite odd integer, then the result
 481    * is negative zero.</li>
 482    * <li>If the first argument is negative zero and the second argument is
 483    * less than zero but not a finite odd integer, or the first argument is
 484    * negative infinity and the second argument is greater than zero but not a
 485    * finite odd integer, then the result is positive infinity.</li>
 486    * <li>If the first argument is negative zero and the second argument is a
 487    * negative finite odd integer, or the first argument is negative infinity
 488    * and the second argument is a positive finite odd integer, then the result
 489    * is negative infinity.</li>
 490    * <li>If the first argument is less than zero and the second argument is a
 491    * finite even integer, then the result is equal to the result of raising
 492    * the absolute value of the first argument to the power of the second
 493    * argument.</li>
 494    * <li>If the first argument is less than zero and the second argument is a
 495    * finite odd integer, then the result is equal to the negative of the
 496    * result of raising the absolute value of the first argument to the power
 497    * of the second argument.</li>
 498    * <li>If the first argument is finite and less than zero and the second
 499    * argument is finite and not an integer, then the result is NaN.</li>
 500    * <li>If both arguments are integers, then the result is exactly equal to
 501    * the mathematical result of raising the first argument to the power of
 502    * the second argument if that result can in fact be represented exactly as
 503    * a double value.</li>
 504    *
 505    * </ul><p>(In the foregoing descriptions, a floating-point value is
 506    * considered to be an integer if and only if it is a fixed point of the
 507    * method {@link #ceil(double)} or, equivalently, a fixed point of the
 508    * method {@link #floor(double)}. A value is a fixed point of a one-argument
 509    * method if and only if the result of applying the method to the value is
 510    * equal to the value.) This is accurate within 1 ulp, and is semi-monotonic.
 511    *
 512    * @param a the number to raise
 513    * @param b the power to raise it to
 514    * @return a<sup>b</sup>
 515    */
 516   public native static double pow(double a, double b);
 517
 518   /**
 519    * Get the IEEE 754 floating point remainder on two numbers. This is the
 520    * value of <code>x - y * <em>n</em></code>, where <em>n</em> is the closest
 521    * double to <code>x / y</code> (ties go to the even n); for a zero
 522    * remainder, the sign is that of <code>x</code>. If either argument is NaN,
 523    * the first argument is infinite, or the second argument is zero, the result
 524    * is NaN; if x is finite but y is infinite, the result is x. This is
 525    * accurate within the limits of doubles.
 526    *
 527    * @param x the dividend (the top half)
 528    * @param y the divisor (the bottom half)
 529    * @return the IEEE 754-defined floating point remainder of x/y
 530    * @see #rint(double)
 531    */
 532   public native static double IEEEremainder(double x, double y);
 533
 534   /**
 535    * Take the nearest integer that is that is greater than or equal to the
 536    * argument. If the argument is NaN, infinite, or zero, the result is the
 537    * same; if the argument is between -1 and 0, the result is negative zero.
 538    * Note that <code>Math.ceil(x) == -Math.floor(-x)</code>.
 539    *
 540    * @param a the value to act upon
 541    * @return the nearest integer &gt;= <code>a</code>
 542    */
 543   public native static double ceil(double a);
 544
 545   /**
 546    * Take the nearest integer that is that is less than or equal to the
 547    * argument. If the argument is NaN, infinite, or zero, the result is the
 548    * same. Note that <code>Math.ceil(x) == -Math.floor(-x)</code>.
 549    *
 550    * @param a the value to act upon
 551    * @return the nearest integer &lt;= <code>a</code>
 552    */
 553   public native static double floor(double a);
 554
 555   /**
 556    * Take the nearest integer to the argument.  If it is exactly between
 557    * two integers, the even integer is taken. If the argument is NaN,
 558    * infinite, or zero, the result is the same.
 559    *
 560    * @param a the value to act upon
 561    * @return the nearest integer to <code>a</code>
 562    */
 563   public native static double rint(double a);
 564
 565   /**
 566    * Take the nearest integer to the argument.  This is equivalent to
 567    * <code>(int) Math.floor(a + 0.5f). If the argument is NaN, the result
 568    * is 0; otherwise if the argument is outside the range of int, the result
 569    * will be Integer.MIN_VALUE or Integer.MAX_VALUE, as appropriate.
 570    *
 571    * @param a the argument to round
 572    * @return the nearest integer to the argument
 573    * @see Integer#MIN_VALUE
 574    * @see Integer#MAX_VALUE
 575    */
 576   public static int round(float a)
 577   {
 578     // this check for NaN, from JLS 15.21.1, saves a method call
 579     if (a != a)
 580       return 0;
 581     return (int) floor(a + 0.5f);
 582   }
 583
 584   /**
 585    * Take the nearest long to the argument.  This is equivalent to
 586    * <code>(long) Math.floor(a + 0.5)</code>. If the argument is NaN, the
 587    * result is 0; otherwise if the argument is outside the range of long, the
 588    * result will be Long.MIN_VALUE or Long.MAX_VALUE, as appropriate.
 589    *
 590    * @param a the argument to round
 591    * @return the nearest long to the argument
 592    * @see Long#MIN_VALUE
 593    * @see Long#MAX_VALUE
 594    */
 595   public static long round(double a)
 596   {
 597     // this check for NaN, from JLS 15.21.1, saves a method call
 598     if (a != a)
 599       return 0;
 600     return (long) floor(a + 0.5d);
 601   }
 602
 603   /**
 604    * Get a random number.  This behaves like Random.nextDouble(), seeded by
 605    * System.currentTimeMillis() when first called. In other words, the number
 606    * is from a pseudorandom sequence, and lies in the range [+0.0, 1.0).
 607    * This random sequence is only used by this method, and is threadsafe,
 608    * although you may want your own random number generator if it is shared
 609    * among threads.
 610    *
 611    * @return a random number
 612    * @see Random#nextDouble()
 613    * @see System#currentTimeMillis()
 614    */
 615   public static synchronized double random()
 616   {
 617     if (rand == null)
 618       rand = new Random();
 619     return rand.nextDouble();
 620   }
 621
 622   /**
 623    * Convert from degrees to radians. The formula for this is
 624    * radians = degrees * (pi/180); however it is not always exact given the
 625    * limitations of floating point numbers.
 626    *
 627    * @param degrees an angle in degrees
 628    * @return the angle in radians
 629    * @since 1.2
 630    */
 631   public static double toRadians(double degrees)
 632   {
 633     return (degrees * PI) / 180;
 634   }
 635
 636   /**
 637    * Convert from radians to degrees. The formula for this is
 638    * degrees = radians * (180/pi); however it is not always exact given the
 639    * limitations of floating point numbers.
 640    *
 641    * @param rads an angle in radians
 642    * @return the angle in degrees
 643    * @since 1.2
 644    */
 645   public static double toDegrees(double rads)
 646   {
 647     return (rads * 180) / PI;
 648   }
 649 }