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