home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / lang / Math.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  17.8 KB  |  501 lines
  1. /*
  2.  * @(#)Math.java    1.29 98/03/18
  3.  *
  4.  * Copyright 1994-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.lang;
  16. import java.util.Random;
  17.  
  18.  
  19. /**
  20.  * The class <code>Math</code> contains methods for performing basic 
  21.  * numeric operations such as the elementary exponential, logarithm, 
  22.  * square root, and trigonometric functions. 
  23.  * <p>
  24.  * To help ensure portability of Java programs, the definitions of 
  25.  * many of the numeric functions in this package require that they 
  26.  * produce the same results as certain published algorithms. These 
  27.  * algorithms are available from the well-known network library 
  28.  * <code>netlib</code> as the package "Freely Distributable 
  29.  * Math Library" (<code>fdlibm</code>). These algorithms, which 
  30.  * are written in the C programming language, are then to be 
  31.  * understood as executed with all floating-point operations 
  32.  * following the rules of Java floating-point arithmetic. 
  33.  * <p>
  34.  * The network library may be found on the World Wide Web at:
  35.  * <blockquote><pre>
  36.  *   http://netlib.att.com/
  37.  * </pre></blockquote>
  38.  * <p>
  39.  * then perform a keyword search for "<code>fdlibm</code>".
  40.  * <p>
  41.  * The Java math library is defined with respect to the version of 
  42.  * <code>fdlibm</code> dated January 4, 1995. Where 
  43.  * <code>fdlibm</code> provides more than one definition for a 
  44.  * function (such as <code>acos</code>), use the "IEEE 754 core 
  45.  * function" version (residing in a file whose name begins with 
  46.  * the letter <code>e</code>). 
  47.  *
  48.  * @author  unascribed
  49.  * @version 1.29, 03/18/98
  50.  * @since   JDK1.0
  51.  */
  52.  
  53. public final class Math {
  54.  
  55.     /**
  56.      * Don't let anyone instantiate this class.
  57.      */
  58.     private Math() {}
  59.  
  60.     /**
  61.      * The <code>double</code> value that is closer than any other to 
  62.      * <code>e</code>, the base of the natural logarithms. 
  63.      */
  64.     public static final double E = 2.7182818284590452354;
  65.  
  66.     /**
  67.      * The <code>double</code> value that is closer than any other to 
  68.      * <i>pi</i>, the ratio of the circumference of a circle to its diameter. 
  69.      */
  70.     public static final double PI = 3.14159265358979323846;
  71.  
  72.     /**
  73.      * Returns the trigonometric sine of an angle.
  74.      *
  75.      * @param   a   an angle, in radians.
  76.      * @return  the sine of the argument.
  77.      */
  78.     public static native double sin(double a);
  79.     
  80.     /**
  81.      * Returns the trigonometric cosine of an angle.
  82.      *
  83.      * @param   a   an angle, in radians.
  84.      * @return  the cosine of the argument.
  85.      */
  86.     public static native double cos(double a);
  87.    
  88.     /**
  89.      * Returns the trigonometric tangent of an angle.
  90.      *
  91.      * @param   a   an angle, in radians.
  92.      * @return  the tangent of the argument.
  93.      */
  94.     public static native double tan(double a);
  95.  
  96.     /**
  97.      * Returns the arc sine of an angle, in the range of -<i>pi</i>/2 through
  98.      * <i>pi</i>/2.
  99.      *
  100.      * @param   a   an angle, in radians.
  101.      * @return  the arc sine of the argument.
  102.      */
  103.     public static native double asin(double a);
  104.  
  105.     /**
  106.      * Returns the arc cosine of an angle, in the range of 0.0 through
  107.      * <i>pi</i>.
  108.      *
  109.      * @param   a   an angle, in radians.
  110.      * @return  the arc cosine of the argument.
  111.      */
  112.     public static native double acos(double a); 
  113.  
  114.     /**
  115.      * Returns the arc tangent of an angle, in the range of -<i>pi</i>/2
  116.      * through <i>pi</i>/2.
  117.      *
  118.      * @param   a   an angle, in radians.
  119.      * @return  the arc tangent of the argument.
  120.      */
  121.     public static native double atan(double a);
  122.  
  123.     /**
  124.      * Returns the exponential number <i>e</i> (i.e., 2.718...) raised to
  125.      * the power of a <code>double</code> value.
  126.      *
  127.      * @param   a   a <code>double</code> value.
  128.      * @return  the value <i>e</i><sup>a</sup>, where <i>e</i> is the base of
  129.      *          the natural logarithms.
  130.      */
  131.     public static native double exp(double a);
  132.  
  133.     /**
  134.      * Returns the natural logarithm (base <i>e</i>) of a <code>double</code>
  135.      * value.
  136.      *
  137.      * @param   a   a number greater than <code>0.0</code>.
  138.      * @return  the value ln <code>a</code>, the natural logarithm of
  139.      *          <code>a</code>.
  140.      */
  141.     public static native double log(double a);
  142.  
  143.     /**
  144.      * Returns the square root of a <code>double</code> value.
  145.      *
  146.      * @param   a   a <code>double</code> value.
  147.      * <!--@return  the value of √ <code>a</code>.-->
  148.      * @return  the square root of <code>a</code>.
  149.      *          If the argument is NaN or less than zero, the result is NaN.
  150.      */
  151.     public static native double sqrt(double a);
  152.  
  153.     /**
  154.      * Computes the remainder operation on two arguments as prescribed 
  155.      * by the IEEE 754 standard.
  156.      * The remainder value is mathematically equal to 
  157.      * <code>f1 - f2</code> × <i>n</i>,
  158.      * where <i>n</i> is the mathematical integer closest to the exact 
  159.      * mathematical value of the quotient <code>f1/f2</code>, and if two 
  160.      * mathematical integers are equally close to <code>f1/f2</code>, 
  161.      * then <i>n</i> is the integer that is even. If the remainder is 
  162.      * zero, its sign is the same as the sign of the first argument. 
  163.      *
  164.      * @param   f1   the dividend.
  165.      * @param   f2   the divisor.
  166.      * @return  the remainder when <code>f1</code> is divided by
  167.      *          <code>f2</code>.
  168.      */
  169.     public static native double IEEEremainder(double f1, double f2);
  170.  
  171.     /**
  172.      * Returns the smallest (closest to negative infinity) 
  173.      * <code>double</code> value that is not less than the argument and is 
  174.      * equal to a mathematical integer. 
  175.      *
  176.      * @param   a   a <code>double</code> value.
  177.      * <!--@return  the value ⌈ <code>a</code> ⌉.-->
  178.      * @return  the smallest (closest to negative infinity) 
  179.      *          <code>double</code> value that is not less than the argument
  180.      *          and is equal to a mathematical integer. 
  181.      */
  182.     public static native double ceil(double a);
  183.  
  184.     /**
  185.      * Returns the largest (closest to positive infinity) 
  186.      * <code>double</code> value that is not greater than the argument and 
  187.      * is equal to a mathematical integer. 
  188.      *
  189.      * @param   a   a <code>double</code> value.
  190.      * @param   a   an assigned value.
  191.      * <!--@return  the value ⌊ <code>a</code> ⌋.-->
  192.      * @return  the largest (closest to positive infinity) 
  193.      *          <code>double</code> value that is not greater than the argument
  194.      *          and is equal to a mathematical integer. 
  195.      */
  196.     public static native double floor(double a);
  197.  
  198.     /**
  199.      * returns the closest integer to the argument. 
  200.      *
  201.      * @param   a   a <code>double</code> value.
  202.      * @return  the closest <code>double</code> value to <code>a</code> that is
  203.      *          equal to a mathematical integer. If two <code>double</code>
  204.      *          values that are mathematical integers are equally close to the
  205.      *          value of the argument, the result is the integer value that
  206.      *          is even.
  207.      */
  208.     public static native double rint(double a);
  209.  
  210.     /**
  211.      * Converts rectangular coordinates (<code>b</code>, <code>a</code>)
  212.      * to polar (r, <i>theta</i>).
  213.      * This method computes the phase <i>theta</i> by computing an arc tangent
  214.      * of <code>b/a</code> in the range of -<i>pi</i> to <i>pi</i>.
  215.      *
  216.      * @param   a   a <code>double</code> value.
  217.      * @param   b   a <code>double</code> value.
  218.      * @return  the <i>theta</i> component of the point
  219.      *          (<i>r</i>, <i>theta</i>)
  220.      *          in polar coordinates that corresponds to the point
  221.      *          (<i>b</i>, <i>a</i>) in Cartesian coordinates.
  222.      */
  223.     public static native double atan2(double a, double b);
  224.  
  225.  
  226.     /**
  227.      * Returns of value of the first argument raised to the power of the
  228.      * second argument.
  229.      * <p>
  230.      * If (<code>a == 0.0</code>), then <code>b</code> must be
  231.      * greater than <code>0.0</code>; otherwise an exception is thrown. 
  232.      * An exception also will occur if (<code>a <= 0.0</code>)
  233.      * and <code>b</code> is not equal to a whole number.
  234.      *
  235.      * @param   a   a <code>double</code> value.
  236.      * @param   b   a <code>double</code> value.
  237.      * @return  the value <code>a<sup>b</sup></code>.
  238.      * @exception ArithmeticException  if (<code>a == 0.0</code>) and
  239.      *              (<code>b <= 0.0</code>), or
  240.      *              if (<code>a <= 0.0</code>) and <code>b</code>
  241.      *              is not equal to a whole number.
  242.      */
  243.     public static native double pow(double a, double b);
  244.  
  245.     /**
  246.      * Returns the closest <code>int</code> to the argument. 
  247.      * <p>
  248.      * If the argument is negative infinity or any value less than or 
  249.      * equal to the value of <code>Integer.MIN_VALUE</code>, the result is 
  250.      * equal to the value of <code>Integer.MIN_VALUE</code>. 
  251.      * <p>
  252.      * If the argument is positive infinity or any value greater than or 
  253.      * equal to the value of <code>Integer.MAX_VALUE</code>, the result is 
  254.      * equal to the value of <code>Integer.MAX_VALUE</code>. 
  255.      *
  256.      * @param   a   a <code>float</code> value.
  257.      * @return  the value of the argument rounded to the nearest
  258.      *          <code>int</code> value.
  259.      * @see     java.lang.Integer#MAX_VALUE
  260.      * @see     java.lang.Integer#MIN_VALUE
  261.      */
  262.     public static int round(float a) {
  263.     return (int)floor(a + 0.5f);
  264.     }
  265.  
  266.     /**
  267.      * Returns the closest <code>long</code> to the argument. 
  268.      * <p>
  269.      * If the argument is negative infinity or any value less than or 
  270.      * equal to the value of <code>Long.MIN_VALUE</code>, the result is 
  271.      * equal to the value of <code>Long.MIN_VALUE</code>. 
  272.      * <p>
  273.      * If the argument is positive infinity or any value greater than or 
  274.      * equal to the value of <code>Long.MAX_VALUE</code>, the result is 
  275.      * equal to the value of <code>Long.MAX_VALUE</code>. 
  276.      *
  277.      * @param   a   a <code>double</code> value.
  278.      * @return  the value of the argument rounded to the nearest
  279.      *          <code>long</code> value.
  280.      * @see     java.lang.Long#MAX_VALUE
  281.      * @see     java.lang.Long#MIN_VALUE
  282.      */
  283.     public static long round(double a) {
  284.     return (long)floor(a + 0.5d);
  285.     }
  286.  
  287.     private static Random randomNumberGenerator;
  288.  
  289.     /**
  290.      * Returns a random number between <code>0.0</code> and <code>1.0</code>.
  291.      * Random number generators are often referred to as pseudorandom number 
  292.      * generators because the numbers produced tend to repeat themselves after
  293.      * a period of time.
  294.      *  
  295.      * @return  a pseudorandom <code>double</code> between <code>0.0</code>
  296.      *          and <code>1.0</code>.
  297.      * @see     java.util.Random#nextDouble()
  298.      */
  299.     public static synchronized double random() {
  300.         if (randomNumberGenerator == null)
  301.             randomNumberGenerator = new Random();
  302.         return randomNumberGenerator.nextDouble();
  303.     }
  304.  
  305.     /**
  306.      * Returns the absolute value of an <code>int</code> value.
  307.      * If the argument is not negative, the argument is returned.
  308.      * If the argument is negative, the negation of the argument is returned. 
  309.      * <p>
  310.      * Note that if the argument is equal to the value of 
  311.      * <code>Integer.MIN_VALUE</code>, the most negative representable 
  312.      * <code>int</code> value, the result is that same value, which is 
  313.      * negative. 
  314.      *
  315.      * @param   a   an <code>int</code> value.
  316.      * @return  the absolute value of the argument.
  317.      * @see     java.lang.Integer#MIN_VALUE
  318.      */
  319.     public static int abs(int a) {
  320.     return (a < 0) ? -a : a;
  321.     }
  322.  
  323.     /**
  324.      * Returns the absolute value of a <code>long</code> value.
  325.      * If the argument is not negative, the argument is returned.
  326.      * If the argument is negative, the negation of the argument is returned. 
  327.      * <p>
  328.      * Note that if the argument is equal to the value of 
  329.      * <code>Long.MIN_VALUE</code>, the most negative representable 
  330.      * <code>long</code> value, the result is that same value, which is 
  331.      * negative. 
  332.      *
  333.      * @param   a   a <code>long</code> value.
  334.      * @return  the absolute value of the argument.
  335.      * @see     java.lang.Long#MIN_VALUE
  336.      */
  337.     public static long abs(long a) {
  338.     return (a < 0) ? -a : a;
  339.     }
  340.  
  341.     /**
  342.      * Returns the absolute value of a <code>float</code> value.
  343.      * If the argument is not negative, the argument is returned.
  344.      * If the argument is negative, the negation of the argument is returned. 
  345.      *
  346.      * @param   a   a <code>float</code> value.
  347.      * @return  the absolute value of the argument.
  348.      */
  349.     public static float abs(float a) {
  350.     if (a < 0.0F) {           /* negative-non-zero */
  351.         return -a;
  352.     }
  353.     if (a > 0.0F || a != a) { /* positive-non-zero or NaN */
  354.         return a;
  355.     }
  356.     return 0.0F;              /* zero */
  357.     }
  358.   
  359.     /**
  360.      * Returns the absolute value of a <code>double</code> value.
  361.      * If the argument is not negative, the argument is returned.
  362.      * If the argument is negative, the negation of the argument is returned. 
  363.      *
  364.      * @param   a   a <code>double</code> value.
  365.      * @return  the absolute value of the argument.
  366.      */
  367.     public static double abs(double a) {
  368.     if (a < 0.0D) {           /* negative-non-zero */
  369.         return -a;
  370.     }
  371.     if (a > 0.0D || a != a) { /* positive-non-zero or NaN */
  372.         return a;
  373.     }
  374.     return 0.0D;              /* zero */
  375.     }
  376.  
  377.     /**
  378.      * Returns the greater of two <code>int</code> values.
  379.      *
  380.      * @param   a   an <code>int</code> value.
  381.      * @param   b   an <code>int</code> value.
  382.      * @return  the larger of <code>a</code> and <code>b</code>.
  383.      */
  384.     public static int max(int a, int b) {
  385.     return (a >= b) ? a : b;
  386.     }
  387.  
  388.     /**
  389.      * Returns the greater of two <code>long</code> values.
  390.      *
  391.      * @param   a   a <code>long</code> value.
  392.      * @param   b   a <code>long</code> value.
  393.      * @return  the larger of <code>a</code> and <code>b</code>.
  394.      */
  395.     public static long max(long a, long b) {
  396.     return (a >= b) ? a : b;
  397.     }
  398.  
  399.     private static long negativeZeroFloatBits = Float.floatToIntBits(-0.0f);
  400.     private static long negativeZeroDoubleBits = Double.doubleToLongBits(-0.0d);
  401.  
  402.     /**
  403.      * Returns the greater of two <code>float</code> values.  If either value
  404.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  405.      * the numerical comparison operators, this method considers negative zero
  406.      * to be strictly smaller than positive zero.
  407.      *
  408.      * @param   a   a <code>float</code> value.
  409.      * @param   b   a <code>float</code> value.
  410.      * @return  the larger of <code>a</code> and <code>b</code>.
  411.      */
  412.     public static float max(float a, float b) {
  413.         if (a != a) return a;    // a is NaN
  414.     if ((a == 0.0f) && (b == 0.0f)
  415.         && (Float.floatToIntBits(a) == negativeZeroFloatBits)) {
  416.         return b;
  417.     }
  418.     return (a >= b) ? a : b;
  419.     }
  420.  
  421.     /**
  422.      * Returns the greater of two <code>double</code> values.  If either value
  423.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  424.      * the numerical comparison operators, this method considers negative zero
  425.      * to be strictly smaller than positive zero.
  426.      *
  427.      * @param   a   a <code>double</code> value.
  428.      * @param   b   a <code>double</code> value.
  429.      * @return  the larger of <code>a</code> and <code>b</code>.
  430.      */
  431.     public static double max(double a, double b) {
  432.         if (a != a) return a;    // a is NaN
  433.     if ((a == 0.0d) && (b == 0.0d)
  434.         && (Double.doubleToLongBits(a) == negativeZeroDoubleBits)) {
  435.         return b;
  436.     }
  437.     return (a >= b) ? a : b;
  438.     }
  439.  
  440.     /**
  441.      * Returns the smaller of two <code>int</code> values.
  442.      *
  443.      * @param   a   an <code>int</code> value.
  444.      * @param   b   an <code>int</code> value.
  445.      * @return  the smaller of <code>a</code> and <code>b</code>.
  446.      */
  447.     public static int min(int a, int b) {
  448.     return (a <= b) ? a : b;
  449.     }
  450.  
  451.     /**
  452.      * Returns the smaller of two <code>long</code> values.
  453.      *
  454.      * @param   a   a <code>long</code> value.
  455.      * @param   b   a <code>long</code> value.
  456.      * @return  the smaller of <code>a</code> and <code>b</code>.
  457.      */
  458.     public static long min(long a, long b) {
  459.     return (a <= b) ? a : b;
  460.     }
  461.  
  462.     /**
  463.      * Returns the smaller of two <code>float</code> values.  If either value
  464.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  465.      * the numerical comparison operators, this method considers negative zero
  466.      * to be strictly smaller than positive zero.
  467.      *
  468.      * @param   a   a <code>float</code> value.
  469.      * @param   b   a <code>float</code> value.
  470.      * @return  the smaller of <code>a</code> and <code>b.</code>
  471.      */
  472.     public static float min(float a, float b) {
  473.         if (a != a) return a;    // a is NaN
  474.     if ((a == 0.0f) && (b == 0.0f)
  475.         && (Float.floatToIntBits(b) == negativeZeroFloatBits)) {
  476.         return b;
  477.     }
  478.     return (a <= b) ? a : b;
  479.     }
  480.  
  481.     /**
  482.      * Returns the smaller of two <code>double</code> values.  If either value
  483.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  484.      * the numerical comparison operators, this method considers negative zero
  485.      * to be strictly smaller than positive zero.
  486.      *
  487.      * @param   a   a <code>double</code> value.
  488.      * @param   b   a <code>double</code> value.
  489.      * @return  the smaller of <code>a</code> and <code>b</code>.
  490.      */
  491.     public static double min(double a, double b) {
  492.         if (a != a) return a;    // a is NaN
  493.     if ((a == 0.0d) && (b == 0.0d)
  494.         && (Double.doubleToLongBits(b) == negativeZeroDoubleBits)) {
  495.         return b;
  496.     }
  497.     return (a <= b) ? a : b;
  498.     }
  499.  
  500. }
  501.