Save This Page
Home » openjdk-7 » java » lang » [javadoc | source]
    1   /*
    2    * Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.lang;
   27   import java.util.Random;
   28   
   29   
   30   /**
   31    * The class {@code Math} contains methods for performing basic
   32    * numeric operations such as the elementary exponential, logarithm,
   33    * square root, and trigonometric functions.
   34    *
   35    * <p>Unlike some of the numeric methods of class
   36    * {@code StrictMath}, all implementations of the equivalent
   37    * functions of class {@code Math} are not defined to return the
   38    * bit-for-bit same results.  This relaxation permits
   39    * better-performing implementations where strict reproducibility is
   40    * not required.
   41    *
   42    * <p>By default many of the {@code Math} methods simply call
   43    * the equivalent method in {@code StrictMath} for their
   44    * implementation.  Code generators are encouraged to use
   45    * platform-specific native libraries or microprocessor instructions,
   46    * where available, to provide higher-performance implementations of
   47    * {@code Math} methods.  Such higher-performance
   48    * implementations still must conform to the specification for
   49    * {@code Math}.
   50    *
   51    * <p>The quality of implementation specifications concern two
   52    * properties, accuracy of the returned result and monotonicity of the
   53    * method.  Accuracy of the floating-point {@code Math} methods
   54    * is measured in terms of <i>ulps</i>, units in the last place.  For
   55    * a given floating-point format, an ulp of a specific real number
   56    * value is the distance between the two floating-point values
   57    * bracketing that numerical value.  When discussing the accuracy of a
   58    * method as a whole rather than at a specific argument, the number of
   59    * ulps cited is for the worst-case error at any argument.  If a
   60    * method always has an error less than 0.5 ulps, the method always
   61    * returns the floating-point number nearest the exact result; such a
   62    * method is <i>correctly rounded</i>.  A correctly rounded method is
   63    * generally the best a floating-point approximation can be; however,
   64    * it is impractical for many floating-point methods to be correctly
   65    * rounded.  Instead, for the {@code Math} class, a larger error
   66    * bound of 1 or 2 ulps is allowed for certain methods.  Informally,
   67    * with a 1 ulp error bound, when the exact result is a representable
   68    * number, the exact result should be returned as the computed result;
   69    * otherwise, either of the two floating-point values which bracket
   70    * the exact result may be returned.  For exact results large in
   71    * magnitude, one of the endpoints of the bracket may be infinite.
   72    * Besides accuracy at individual arguments, maintaining proper
   73    * relations between the method at different arguments is also
   74    * important.  Therefore, most methods with more than 0.5 ulp errors
   75    * are required to be <i>semi-monotonic</i>: whenever the mathematical
   76    * function is non-decreasing, so is the floating-point approximation,
   77    * likewise, whenever the mathematical function is non-increasing, so
   78    * is the floating-point approximation.  Not all approximations that
   79    * have 1 ulp accuracy will automatically meet the monotonicity
   80    * requirements.
   81    *
   82    * @author  unascribed
   83    * @author  Joseph D. Darcy
   84    * @since   JDK1.0
   85    */
   86   
   87   public final class Math {
   88   
   89       /**
   90        * Don't let anyone instantiate this class.
   91        */
   92       private Math() {}
   93   
   94       /**
   95        * The {@code double} value that is closer than any other to
   96        * <i>e</i>, the base of the natural logarithms.
   97        */
   98       public static final double E = 2.7182818284590452354;
   99   
  100       /**
  101        * The {@code double} value that is closer than any other to
  102        * <i>pi</i>, the ratio of the circumference of a circle to its
  103        * diameter.
  104        */
  105       public static final double PI = 3.14159265358979323846;
  106   
  107       /**
  108        * Returns the trigonometric sine of an angle.  Special cases:
  109        * <ul><li>If the argument is NaN or an infinity, then the
  110        * result is NaN.
  111        * <li>If the argument is zero, then the result is a zero with the
  112        * same sign as the argument.</ul>
  113        *
  114        * <p>The computed result must be within 1 ulp of the exact result.
  115        * Results must be semi-monotonic.
  116        *
  117        * @param   a   an angle, in radians.
  118        * @return  the sine of the argument.
  119        */
  120       public static double sin(double a) {
  121           return StrictMath.sin(a); // default impl. delegates to StrictMath
  122       }
  123   
  124       /**
  125        * Returns the trigonometric cosine of an angle. Special cases:
  126        * <ul><li>If the argument is NaN or an infinity, then the
  127        * result is NaN.</ul>
  128        *
  129        * <p>The computed result must be within 1 ulp of the exact result.
  130        * Results must be semi-monotonic.
  131        *
  132        * @param   a   an angle, in radians.
  133        * @return  the cosine of the argument.
  134        */
  135       public static double cos(double a) {
  136           return StrictMath.cos(a); // default impl. delegates to StrictMath
  137       }
  138   
  139       /**
  140        * Returns the trigonometric tangent of an angle.  Special cases:
  141        * <ul><li>If the argument is NaN or an infinity, then the result
  142        * is NaN.
  143        * <li>If the argument is zero, then the result is a zero with the
  144        * same sign as the argument.</ul>
  145        *
  146        * <p>The computed result must be within 1 ulp of the exact result.
  147        * Results must be semi-monotonic.
  148        *
  149        * @param   a   an angle, in radians.
  150        * @return  the tangent of the argument.
  151        */
  152       public static double tan(double a) {
  153           return StrictMath.tan(a); // default impl. delegates to StrictMath
  154       }
  155   
  156       /**
  157        * Returns the arc sine of a value; the returned angle is in the
  158        * range -<i>pi</i>/2 through <i>pi</i>/2.  Special cases:
  159        * <ul><li>If the argument is NaN or its absolute value is greater
  160        * than 1, then the result is NaN.
  161        * <li>If the argument is zero, then the result is a zero with the
  162        * same sign as the argument.</ul>
  163        *
  164        * <p>The computed result must be within 1 ulp of the exact result.
  165        * Results must be semi-monotonic.
  166        *
  167        * @param   a   the value whose arc sine is to be returned.
  168        * @return  the arc sine of the argument.
  169        */
  170       public static double asin(double a) {
  171           return StrictMath.asin(a); // default impl. delegates to StrictMath
  172       }
  173   
  174       /**
  175        * Returns the arc cosine of a value; the returned angle is in the
  176        * range 0.0 through <i>pi</i>.  Special case:
  177        * <ul><li>If the argument is NaN or its absolute value is greater
  178        * than 1, then the result is NaN.</ul>
  179        *
  180        * <p>The computed result must be within 1 ulp of the exact result.
  181        * Results must be semi-monotonic.
  182        *
  183        * @param   a   the value whose arc cosine is to be returned.
  184        * @return  the arc cosine of the argument.
  185        */
  186       public static double acos(double a) {
  187           return StrictMath.acos(a); // default impl. delegates to StrictMath
  188       }
  189   
  190       /**
  191        * Returns the arc tangent of a value; the returned angle is in the
  192        * range -<i>pi</i>/2 through <i>pi</i>/2.  Special cases:
  193        * <ul><li>If the argument is NaN, then the result is NaN.
  194        * <li>If the argument is zero, then the result is a zero with the
  195        * same sign as the argument.</ul>
  196        *
  197        * <p>The computed result must be within 1 ulp of the exact result.
  198        * Results must be semi-monotonic.
  199        *
  200        * @param   a   the value whose arc tangent is to be returned.
  201        * @return  the arc tangent of the argument.
  202        */
  203       public static double atan(double a) {
  204           return StrictMath.atan(a); // default impl. delegates to StrictMath
  205       }
  206   
  207       /**
  208        * Converts an angle measured in degrees to an approximately
  209        * equivalent angle measured in radians.  The conversion from
  210        * degrees to radians is generally inexact.
  211        *
  212        * @param   angdeg   an angle, in degrees
  213        * @return  the measurement of the angle {@code angdeg}
  214        *          in radians.
  215        * @since   1.2
  216        */
  217       public static double toRadians(double angdeg) {
  218           return angdeg / 180.0 * PI;
  219       }
  220   
  221       /**
  222        * Converts an angle measured in radians to an approximately
  223        * equivalent angle measured in degrees.  The conversion from
  224        * radians to degrees is generally inexact; users should
  225        * <i>not</i> expect {@code cos(toRadians(90.0))} to exactly
  226        * equal {@code 0.0}.
  227        *
  228        * @param   angrad   an angle, in radians
  229        * @return  the measurement of the angle {@code angrad}
  230        *          in degrees.
  231        * @since   1.2
  232        */
  233       public static double toDegrees(double angrad) {
  234           return angrad * 180.0 / PI;
  235       }
  236   
  237       /**
  238        * Returns Euler's number <i>e</i> raised to the power of a
  239        * {@code double} value.  Special cases:
  240        * <ul><li>If the argument is NaN, the result is NaN.
  241        * <li>If the argument is positive infinity, then the result is
  242        * positive infinity.
  243        * <li>If the argument is negative infinity, then the result is
  244        * positive zero.</ul>
  245        *
  246        * <p>The computed result must be within 1 ulp of the exact result.
  247        * Results must be semi-monotonic.
  248        *
  249        * @param   a   the exponent to raise <i>e</i> to.
  250        * @return  the value <i>e</i><sup>{@code a}</sup>,
  251        *          where <i>e</i> is the base of the natural logarithms.
  252        */
  253       public static double exp(double a) {
  254           return StrictMath.exp(a); // default impl. delegates to StrictMath
  255       }
  256   
  257       /**
  258        * Returns the natural logarithm (base <i>e</i>) of a {@code double}
  259        * value.  Special cases:
  260        * <ul><li>If the argument is NaN or less than zero, then the result
  261        * is NaN.
  262        * <li>If the argument is positive infinity, then the result is
  263        * positive infinity.
  264        * <li>If the argument is positive zero or negative zero, then the
  265        * result is negative infinity.</ul>
  266        *
  267        * <p>The computed result must be within 1 ulp of the exact result.
  268        * Results must be semi-monotonic.
  269        *
  270        * @param   a   a value
  271        * @return  the value ln&nbsp;{@code a}, the natural logarithm of
  272        *          {@code a}.
  273        */
  274       public static double log(double a) {
  275           return StrictMath.log(a); // default impl. delegates to StrictMath
  276       }
  277   
  278       /**
  279        * Returns the base 10 logarithm of a {@code double} value.
  280        * Special cases:
  281        *
  282        * <ul><li>If the argument is NaN or less than zero, then the result
  283        * is NaN.
  284        * <li>If the argument is positive infinity, then the result is
  285        * positive infinity.
  286        * <li>If the argument is positive zero or negative zero, then the
  287        * result is negative infinity.
  288        * <li> If the argument is equal to 10<sup><i>n</i></sup> for
  289        * integer <i>n</i>, then the result is <i>n</i>.
  290        * </ul>
  291        *
  292        * <p>The computed result must be within 1 ulp of the exact result.
  293        * Results must be semi-monotonic.
  294        *
  295        * @param   a   a value
  296        * @return  the base 10 logarithm of  {@code a}.
  297        * @since 1.5
  298        */
  299       public static double log10(double a) {
  300           return StrictMath.log10(a); // default impl. delegates to StrictMath
  301       }
  302   
  303       /**
  304        * Returns the correctly rounded positive square root of a
  305        * {@code double} value.
  306        * Special cases:
  307        * <ul><li>If the argument is NaN or less than zero, then the result
  308        * is NaN.
  309        * <li>If the argument is positive infinity, then the result is positive
  310        * infinity.
  311        * <li>If the argument is positive zero or negative zero, then the
  312        * result is the same as the argument.</ul>
  313        * Otherwise, the result is the {@code double} value closest to
  314        * the true mathematical square root of the argument value.
  315        *
  316        * @param   a   a value.
  317        * @return  the positive square root of {@code a}.
  318        *          If the argument is NaN or less than zero, the result is NaN.
  319        */
  320       public static double sqrt(double a) {
  321           return StrictMath.sqrt(a); // default impl. delegates to StrictMath
  322                                      // Note that hardware sqrt instructions
  323                                      // frequently can be directly used by JITs
  324                                      // and should be much faster than doing
  325                                      // Math.sqrt in software.
  326       }
  327   
  328   
  329       /**
  330        * Returns the cube root of a {@code double} value.  For
  331        * positive finite {@code x}, {@code cbrt(-x) ==
  332        * -cbrt(x)}; that is, the cube root of a negative value is
  333        * the negative of the cube root of that value's magnitude.
  334        *
  335        * Special cases:
  336        *
  337        * <ul>
  338        *
  339        * <li>If the argument is NaN, then the result is NaN.
  340        *
  341        * <li>If the argument is infinite, then the result is an infinity
  342        * with the same sign as the argument.
  343        *
  344        * <li>If the argument is zero, then the result is a zero with the
  345        * same sign as the argument.
  346        *
  347        * </ul>
  348        *
  349        * <p>The computed result must be within 1 ulp of the exact result.
  350        *
  351        * @param   a   a value.
  352        * @return  the cube root of {@code a}.
  353        * @since 1.5
  354        */
  355       public static double cbrt(double a) {
  356           return StrictMath.cbrt(a);
  357       }
  358   
  359       /**
  360        * Computes the remainder operation on two arguments as prescribed
  361        * by the IEEE 754 standard.
  362        * The remainder value is mathematically equal to
  363        * <code>f1&nbsp;-&nbsp;f2</code>&nbsp;&times;&nbsp;<i>n</i>,
  364        * where <i>n</i> is the mathematical integer closest to the exact
  365        * mathematical value of the quotient {@code f1/f2}, and if two
  366        * mathematical integers are equally close to {@code f1/f2},
  367        * then <i>n</i> is the integer that is even. If the remainder is
  368        * zero, its sign is the same as the sign of the first argument.
  369        * Special cases:
  370        * <ul><li>If either argument is NaN, or the first argument is infinite,
  371        * or the second argument is positive zero or negative zero, then the
  372        * result is NaN.
  373        * <li>If the first argument is finite and the second argument is
  374        * infinite, then the result is the same as the first argument.</ul>
  375        *
  376        * @param   f1   the dividend.
  377        * @param   f2   the divisor.
  378        * @return  the remainder when {@code f1} is divided by
  379        *          {@code f2}.
  380        */
  381       public static double IEEEremainder(double f1, double f2) {
  382           return StrictMath.IEEEremainder(f1, f2); // delegate to StrictMath
  383       }
  384   
  385       /**
  386        * Returns the smallest (closest to negative infinity)
  387        * {@code double} value that is greater than or equal to the
  388        * argument and is equal to a mathematical integer. Special cases:
  389        * <ul><li>If the argument value is already equal to a
  390        * mathematical integer, then the result is the same as the
  391        * argument.  <li>If the argument is NaN or an infinity or
  392        * positive zero or negative zero, then the result is the same as
  393        * the argument.  <li>If the argument value is less than zero but
  394        * greater than -1.0, then the result is negative zero.</ul> Note
  395        * that the value of {@code Math.ceil(x)} is exactly the
  396        * value of {@code -Math.floor(-x)}.
  397        *
  398        *
  399        * @param   a   a value.
  400        * @return  the smallest (closest to negative infinity)
  401        *          floating-point value that is greater than or equal to
  402        *          the argument and is equal to a mathematical integer.
  403        */
  404       public static double ceil(double a) {
  405           return StrictMath.ceil(a); // default impl. delegates to StrictMath
  406       }
  407   
  408       /**
  409        * Returns the largest (closest to positive infinity)
  410        * {@code double} value that is less than or equal to the
  411        * argument and is equal to a mathematical integer. Special cases:
  412        * <ul><li>If the argument value is already equal to a
  413        * mathematical integer, then the result is the same as the
  414        * argument.  <li>If the argument is NaN or an infinity or
  415        * positive zero or negative zero, then the result is the same as
  416        * the argument.</ul>
  417        *
  418        * @param   a   a value.
  419        * @return  the largest (closest to positive infinity)
  420        *          floating-point value that less than or equal to the argument
  421        *          and is equal to a mathematical integer.
  422        */
  423       public static double floor(double a) {
  424           return StrictMath.floor(a); // default impl. delegates to StrictMath
  425       }
  426   
  427       /**
  428        * Returns the {@code double} value that is closest in value
  429        * to the argument and is equal to a mathematical integer. If two
  430        * {@code double} values that are mathematical integers are
  431        * equally close, the result is the integer value that is
  432        * even. Special cases:
  433        * <ul><li>If the argument value is already equal to a mathematical
  434        * integer, then the result is the same as the argument.
  435        * <li>If the argument is NaN or an infinity or positive zero or negative
  436        * zero, then the result is the same as the argument.</ul>
  437        *
  438        * @param   a   a {@code double} value.
  439        * @return  the closest floating-point value to {@code a} that is
  440        *          equal to a mathematical integer.
  441        */
  442       public static double rint(double a) {
  443           return StrictMath.rint(a); // default impl. delegates to StrictMath
  444       }
  445   
  446       /**
  447        * Returns the angle <i>theta</i> from the conversion of rectangular
  448        * coordinates ({@code x},&nbsp;{@code y}) to polar
  449        * coordinates (r,&nbsp;<i>theta</i>).
  450        * This method computes the phase <i>theta</i> by computing an arc tangent
  451        * of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special
  452        * cases:
  453        * <ul><li>If either argument is NaN, then the result is NaN.
  454        * <li>If the first argument is positive zero and the second argument
  455        * is positive, or the first argument is positive and finite and the
  456        * second argument is positive infinity, then the result is positive
  457        * zero.
  458        * <li>If the first argument is negative zero and the second argument
  459        * is positive, or the first argument is negative and finite and the
  460        * second argument is positive infinity, then the result is negative zero.
  461        * <li>If the first argument is positive zero and the second argument
  462        * is negative, or the first argument is positive and finite and the
  463        * second argument is negative infinity, then the result is the
  464        * {@code double} value closest to <i>pi</i>.
  465        * <li>If the first argument is negative zero and the second argument
  466        * is negative, or the first argument is negative and finite and the
  467        * second argument is negative infinity, then the result is the
  468        * {@code double} value closest to -<i>pi</i>.
  469        * <li>If the first argument is positive and the second argument is
  470        * positive zero or negative zero, or the first argument is positive
  471        * infinity and the second argument is finite, then the result is the
  472        * {@code double} value closest to <i>pi</i>/2.
  473        * <li>If the first argument is negative and the second argument is
  474        * positive zero or negative zero, or the first argument is negative
  475        * infinity and the second argument is finite, then the result is the
  476        * {@code double} value closest to -<i>pi</i>/2.
  477        * <li>If both arguments are positive infinity, then the result is the
  478        * {@code double} value closest to <i>pi</i>/4.
  479        * <li>If the first argument is positive infinity and the second argument
  480        * is negative infinity, then the result is the {@code double}
  481        * value closest to 3*<i>pi</i>/4.
  482        * <li>If the first argument is negative infinity and the second argument
  483        * is positive infinity, then the result is the {@code double} value
  484        * closest to -<i>pi</i>/4.
  485        * <li>If both arguments are negative infinity, then the result is the
  486        * {@code double} value closest to -3*<i>pi</i>/4.</ul>
  487        *
  488        * <p>The computed result must be within 2 ulps of the exact result.
  489        * Results must be semi-monotonic.
  490        *
  491        * @param   y   the ordinate coordinate
  492        * @param   x   the abscissa coordinate
  493        * @return  the <i>theta</i> component of the point
  494        *          (<i>r</i>,&nbsp;<i>theta</i>)
  495        *          in polar coordinates that corresponds to the point
  496        *          (<i>x</i>,&nbsp;<i>y</i>) in Cartesian coordinates.
  497        */
  498       public static double atan2(double y, double x) {
  499           return StrictMath.atan2(y, x); // default impl. delegates to StrictMath
  500       }
  501   
  502       /**
  503        * Returns the value of the first argument raised to the power of the
  504        * second argument. Special cases:
  505        *
  506        * <ul><li>If the second argument is positive or negative zero, then the
  507        * result is 1.0.
  508        * <li>If the second argument is 1.0, then the result is the same as the
  509        * first argument.
  510        * <li>If the second argument is NaN, then the result is NaN.
  511        * <li>If the first argument is NaN and the second argument is nonzero,
  512        * then the result is NaN.
  513        *
  514        * <li>If
  515        * <ul>
  516        * <li>the absolute value of the first argument is greater than 1
  517        * and the second argument is positive infinity, or
  518        * <li>the absolute value of the first argument is less than 1 and
  519        * the second argument is negative infinity,
  520        * </ul>
  521        * then the result is positive infinity.
  522        *
  523        * <li>If
  524        * <ul>
  525        * <li>the absolute value of the first argument is greater than 1 and
  526        * the second argument is negative infinity, or
  527        * <li>the absolute value of the
  528        * first argument is less than 1 and the second argument is positive
  529        * infinity,
  530        * </ul>
  531        * then the result is positive zero.
  532        *
  533        * <li>If the absolute value of the first argument equals 1 and the
  534        * second argument is infinite, then the result is NaN.
  535        *
  536        * <li>If
  537        * <ul>
  538        * <li>the first argument is positive zero and the second argument
  539        * is greater than zero, or
  540        * <li>the first argument is positive infinity and the second
  541        * argument is less than zero,
  542        * </ul>
  543        * then the result is positive zero.
  544        *
  545        * <li>If
  546        * <ul>
  547        * <li>the first argument is positive zero and the second argument
  548        * is less than zero, or
  549        * <li>the first argument is positive infinity and the second
  550        * argument is greater than zero,
  551        * </ul>
  552        * then the result is positive infinity.
  553        *
  554        * <li>If
  555        * <ul>
  556        * <li>the first argument is negative zero and the second argument
  557        * is greater than zero but not a finite odd integer, or
  558        * <li>the first argument is negative infinity and the second
  559        * argument is less than zero but not a finite odd integer,
  560        * </ul>
  561        * then the result is positive zero.
  562        *
  563        * <li>If
  564        * <ul>
  565        * <li>the first argument is negative zero and the second argument
  566        * is a positive finite odd integer, or
  567        * <li>the first argument is negative infinity and the second
  568        * argument is a negative finite odd integer,
  569        * </ul>
  570        * then the result is negative zero.
  571        *
  572        * <li>If
  573        * <ul>
  574        * <li>the first argument is negative zero and the second argument
  575        * is less than zero but not a finite odd integer, or
  576        * <li>the first argument is negative infinity and the second
  577        * argument is greater than zero but not a finite odd integer,
  578        * </ul>
  579        * then the result is positive infinity.
  580        *
  581        * <li>If
  582        * <ul>
  583        * <li>the first argument is negative zero and the second argument
  584        * is a negative finite odd integer, or
  585        * <li>the first argument is negative infinity and the second
  586        * argument is a positive finite odd integer,
  587        * </ul>
  588        * then the result is negative infinity.
  589        *
  590        * <li>If the first argument is finite and less than zero
  591        * <ul>
  592        * <li> if the second argument is a finite even integer, the
  593        * result is equal to the result of raising the absolute value of
  594        * the first argument to the power of the second argument
  595        *
  596        * <li>if the second argument is a finite odd integer, the result
  597        * is equal to the negative of the result of raising the absolute
  598        * value of the first argument to the power of the second
  599        * argument
  600        *
  601        * <li>if the second argument is finite and not an integer, then
  602        * the result is NaN.
  603        * </ul>
  604        *
  605        * <li>If both arguments are integers, then the result is exactly equal
  606        * to the mathematical result of raising the first argument to the power
  607        * of the second argument if that result can in fact be represented
  608        * exactly as a {@code double} value.</ul>
  609        *
  610        * <p>(In the foregoing descriptions, a floating-point value is
  611        * considered to be an integer if and only if it is finite and a
  612        * fixed point of the method {@link #ceil ceil} or,
  613        * equivalently, a fixed point of the method {@link #floor
  614        * floor}. A value is a fixed point of a one-argument
  615        * method if and only if the result of applying the method to the
  616        * value is equal to the value.)
  617        *
  618        * <p>The computed result must be within 1 ulp of the exact result.
  619        * Results must be semi-monotonic.
  620        *
  621        * @param   a   the base.
  622        * @param   b   the exponent.
  623        * @return  the value {@code a}<sup>{@code b}</sup>.
  624        */
  625       public static double pow(double a, double b) {
  626           return StrictMath.pow(a, b); // default impl. delegates to StrictMath
  627       }
  628   
  629       /**
  630        * Returns the closest {@code int} to the argument, with ties
  631        * rounding up.
  632        *
  633        * <p>
  634        * Special cases:
  635        * <ul><li>If the argument is NaN, the result is 0.
  636        * <li>If the argument is negative infinity or any value less than or
  637        * equal to the value of {@code Integer.MIN_VALUE}, the result is
  638        * equal to the value of {@code Integer.MIN_VALUE}.
  639        * <li>If the argument is positive infinity or any value greater than or
  640        * equal to the value of {@code Integer.MAX_VALUE}, the result is
  641        * equal to the value of {@code Integer.MAX_VALUE}.</ul>
  642        *
  643        * @param   a   a floating-point value to be rounded to an integer.
  644        * @return  the value of the argument rounded to the nearest
  645        *          {@code int} value.
  646        * @see     java.lang.Integer#MAX_VALUE
  647        * @see     java.lang.Integer#MIN_VALUE
  648        */
  649       public static int round(float a) {
  650           if (a != 0x1.fffffep-2f) // greatest float value less than 0.5
  651               return (int)floor(a + 0.5f);
  652           else
  653               return 0;
  654       }
  655   
  656       /**
  657        * Returns the closest {@code long} to the argument, with ties
  658        * rounding up.
  659        *
  660        * <p>Special cases:
  661        * <ul><li>If the argument is NaN, the result is 0.
  662        * <li>If the argument is negative infinity or any value less than or
  663        * equal to the value of {@code Long.MIN_VALUE}, the result is
  664        * equal to the value of {@code Long.MIN_VALUE}.
  665        * <li>If the argument is positive infinity or any value greater than or
  666        * equal to the value of {@code Long.MAX_VALUE}, the result is
  667        * equal to the value of {@code Long.MAX_VALUE}.</ul>
  668        *
  669        * @param   a   a floating-point value to be rounded to a
  670        *          {@code long}.
  671        * @return  the value of the argument rounded to the nearest
  672        *          {@code long} value.
  673        * @see     java.lang.Long#MAX_VALUE
  674        * @see     java.lang.Long#MIN_VALUE
  675        */
  676       public static long round(double a) {
  677           if (a != 0x1.fffffffffffffp-2) // greatest double value less than 0.5
  678               return (long)floor(a + 0.5d);
  679           else
  680               return 0;
  681       }
  682   
  683       private static Random randomNumberGenerator;
  684   
  685       private static synchronized Random initRNG() {
  686           Random rnd = randomNumberGenerator;
  687           return (rnd == null) ? (randomNumberGenerator = new Random()) : rnd;
  688       }
  689   
  690       /**
  691        * Returns a {@code double} value with a positive sign, greater
  692        * than or equal to {@code 0.0} and less than {@code 1.0}.
  693        * Returned values are chosen pseudorandomly with (approximately)
  694        * uniform distribution from that range.
  695        *
  696        * <p>When this method is first called, it creates a single new
  697        * pseudorandom-number generator, exactly as if by the expression
  698        *
  699        * <blockquote>{@code new java.util.Random()}</blockquote>
  700        *
  701        * This new pseudorandom-number generator is used thereafter for
  702        * all calls to this method and is used nowhere else.
  703        *
  704        * <p>This method is properly synchronized to allow correct use by
  705        * more than one thread. However, if many threads need to generate
  706        * pseudorandom numbers at a great rate, it may reduce contention
  707        * for each thread to have its own pseudorandom-number generator.
  708        *
  709        * @return  a pseudorandom {@code double} greater than or equal
  710        * to {@code 0.0} and less than {@code 1.0}.
  711        * @see Random#nextDouble()
  712        */
  713       public static double random() {
  714           Random rnd = randomNumberGenerator;
  715           if (rnd == null) rnd = initRNG();
  716           return rnd.nextDouble();
  717       }
  718   
  719       /**
  720        * Returns the absolute value of an {@code int} value.
  721        * If the argument is not negative, the argument is returned.
  722        * If the argument is negative, the negation of the argument is returned.
  723        *
  724        * <p>Note that if the argument is equal to the value of
  725        * {@link Integer#MIN_VALUE}, the most negative representable
  726        * {@code int} value, the result is that same value, which is
  727        * negative.
  728        *
  729        * @param   a   the argument whose absolute value is to be determined
  730        * @return  the absolute value of the argument.
  731        */
  732       public static int abs(int a) {
  733           return (a < 0) ? -a : a;
  734       }
  735   
  736       /**
  737        * Returns the absolute value of a {@code long} value.
  738        * If the argument is not negative, the argument is returned.
  739        * If the argument is negative, the negation of the argument is returned.
  740        *
  741        * <p>Note that if the argument is equal to the value of
  742        * {@link Long#MIN_VALUE}, the most negative representable
  743        * {@code long} value, the result is that same value, which
  744        * is negative.
  745        *
  746        * @param   a   the argument whose absolute value is to be determined
  747        * @return  the absolute value of the argument.
  748        */
  749       public static long abs(long a) {
  750           return (a < 0) ? -a : a;
  751       }
  752   
  753       /**
  754        * Returns the absolute value of a {@code float} value.
  755        * If the argument is not negative, the argument is returned.
  756        * If the argument is negative, the negation of the argument is returned.
  757        * Special cases:
  758        * <ul><li>If the argument is positive zero or negative zero, the
  759        * result is positive zero.
  760        * <li>If the argument is infinite, the result is positive infinity.
  761        * <li>If the argument is NaN, the result is NaN.</ul>
  762        * In other words, the result is the same as the value of the expression:
  763        * <p>{@code Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))}
  764        *
  765        * @param   a   the argument whose absolute value is to be determined
  766        * @return  the absolute value of the argument.
  767        */
  768       public static float abs(float a) {
  769           return (a <= 0.0F) ? 0.0F - a : a;
  770       }
  771   
  772       /**
  773        * Returns the absolute value of a {@code double} value.
  774        * If the argument is not negative, the argument is returned.
  775        * If the argument is negative, the negation of the argument is returned.
  776        * Special cases:
  777        * <ul><li>If the argument is positive zero or negative zero, the result
  778        * is positive zero.
  779        * <li>If the argument is infinite, the result is positive infinity.
  780        * <li>If the argument is NaN, the result is NaN.</ul>
  781        * In other words, the result is the same as the value of the expression:
  782        * <p>{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)}
  783        *
  784        * @param   a   the argument whose absolute value is to be determined
  785        * @return  the absolute value of the argument.
  786        */
  787       public static double abs(double a) {
  788           return (a <= 0.0D) ? 0.0D - a : a;
  789       }
  790   
  791       /**
  792        * Returns the greater of two {@code int} values. That is, the
  793        * result is the argument closer to the value of
  794        * {@link Integer#MAX_VALUE}. If the arguments have the same value,
  795        * the result is that same value.
  796        *
  797        * @param   a   an argument.
  798        * @param   b   another argument.
  799        * @return  the larger of {@code a} and {@code b}.
  800        */
  801       public static int max(int a, int b) {
  802           return (a >= b) ? a : b;
  803       }
  804   
  805       /**
  806        * Returns the greater of two {@code long} values. That is, the
  807        * result is the argument closer to the value of
  808        * {@link Long#MAX_VALUE}. If the arguments have the same value,
  809        * the result is that same value.
  810        *
  811        * @param   a   an argument.
  812        * @param   b   another argument.
  813        * @return  the larger of {@code a} and {@code b}.
  814        */
  815       public static long max(long a, long b) {
  816           return (a >= b) ? a : b;
  817       }
  818   
  819       private static long negativeZeroFloatBits = Float.floatToIntBits(-0.0f);
  820       private static long negativeZeroDoubleBits = Double.doubleToLongBits(-0.0d);
  821   
  822       /**
  823        * Returns the greater of two {@code float} values.  That is,
  824        * the result is the argument closer to positive infinity. If the
  825        * arguments have the same value, the result is that same
  826        * value. If either value is NaN, then the result is NaN.  Unlike
  827        * the numerical comparison operators, this method considers
  828        * negative zero to be strictly smaller than positive zero. If one
  829        * argument is positive zero and the other negative zero, the
  830        * result is positive zero.
  831        *
  832        * @param   a   an argument.
  833        * @param   b   another argument.
  834        * @return  the larger of {@code a} and {@code b}.
  835        */
  836       public static float max(float a, float b) {
  837           if (a != a) return a;   // a is NaN
  838           if ((a == 0.0f) && (b == 0.0f)
  839               && (Float.floatToIntBits(a) == negativeZeroFloatBits)) {
  840               return b;
  841           }
  842           return (a >= b) ? a : b;
  843       }
  844   
  845       /**
  846        * Returns the greater of two {@code double} values.  That
  847        * is, the result is the argument closer to positive infinity. If
  848        * the arguments have the same value, the result is that same
  849        * value. If either value is NaN, then the result is NaN.  Unlike
  850        * the numerical comparison operators, this method considers
  851        * negative zero to be strictly smaller than positive zero. If one
  852        * argument is positive zero and the other negative zero, the
  853        * result is positive zero.
  854        *
  855        * @param   a   an argument.
  856        * @param   b   another argument.
  857        * @return  the larger of {@code a} and {@code b}.
  858        */
  859       public static double max(double a, double b) {
  860           if (a != a) return a;   // a is NaN
  861           if ((a == 0.0d) && (b == 0.0d)
  862               && (Double.doubleToLongBits(a) == negativeZeroDoubleBits)) {
  863               return b;
  864           }
  865           return (a >= b) ? a : b;
  866       }
  867   
  868       /**
  869        * Returns the smaller of two {@code int} values. That is,
  870        * the result the argument closer to the value of
  871        * {@link Integer#MIN_VALUE}.  If the arguments have the same
  872        * value, the result is that same value.
  873        *
  874        * @param   a   an argument.
  875        * @param   b   another argument.
  876        * @return  the smaller of {@code a} and {@code b}.
  877        */
  878       public static int min(int a, int b) {
  879           return (a <= b) ? a : b;
  880       }
  881   
  882       /**
  883        * Returns the smaller of two {@code long} values. That is,
  884        * the result is the argument closer to the value of
  885        * {@link Long#MIN_VALUE}. If the arguments have the same
  886        * value, the result is that same value.
  887        *
  888        * @param   a   an argument.
  889        * @param   b   another argument.
  890        * @return  the smaller of {@code a} and {@code b}.
  891        */
  892       public static long min(long a, long b) {
  893           return (a <= b) ? a : b;
  894       }
  895   
  896       /**
  897        * Returns the smaller of two {@code float} values.  That is,
  898        * the result is the value closer to negative infinity. If the
  899        * arguments have the same value, the result is that same
  900        * value. If either value is NaN, then the result is NaN.  Unlike
  901        * the numerical comparison operators, this method considers
  902        * negative zero to be strictly smaller than positive zero.  If
  903        * one argument is positive zero and the other is negative zero,
  904        * the result is negative zero.
  905        *
  906        * @param   a   an argument.
  907        * @param   b   another argument.
  908        * @return  the smaller of {@code a} and {@code b}.
  909        */
  910       public static float min(float a, float b) {
  911           if (a != a) return a;   // a is NaN
  912           if ((a == 0.0f) && (b == 0.0f)
  913               && (Float.floatToIntBits(b) == negativeZeroFloatBits)) {
  914               return b;
  915           }
  916           return (a <= b) ? a : b;
  917       }
  918   
  919       /**
  920        * Returns the smaller of two {@code double} values.  That
  921        * is, the result is the value closer to negative infinity. If the
  922        * arguments have the same value, the result is that same
  923        * value. If either value is NaN, then the result is NaN.  Unlike
  924        * the numerical comparison operators, this method considers
  925        * negative zero to be strictly smaller than positive zero. If one
  926        * argument is positive zero and the other is negative zero, the
  927        * result is negative zero.
  928        *
  929        * @param   a   an argument.
  930        * @param   b   another argument.
  931        * @return  the smaller of {@code a} and {@code b}.
  932        */
  933       public static double min(double a, double b) {
  934           if (a != a) return a;   // a is NaN
  935           if ((a == 0.0d) && (b == 0.0d)
  936               && (Double.doubleToLongBits(b) == negativeZeroDoubleBits)) {
  937               return b;
  938           }
  939           return (a <= b) ? a : b;
  940       }
  941   
  942       /**
  943        * Returns the size of an ulp of the argument.  An ulp of a
  944        * {@code double} value is the positive distance between this
  945        * floating-point value and the {@code double} value next
  946        * larger in magnitude.  Note that for non-NaN <i>x</i>,
  947        * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
  948        *
  949        * <p>Special Cases:
  950        * <ul>
  951        * <li> If the argument is NaN, then the result is NaN.
  952        * <li> If the argument is positive or negative infinity, then the
  953        * result is positive infinity.
  954        * <li> If the argument is positive or negative zero, then the result is
  955        * {@code Double.MIN_VALUE}.
  956        * <li> If the argument is &plusmn;{@code Double.MAX_VALUE}, then
  957        * the result is equal to 2<sup>971</sup>.
  958        * </ul>
  959        *
  960        * @param d the floating-point value whose ulp is to be returned
  961        * @return the size of an ulp of the argument
  962        * @author Joseph D. Darcy
  963        * @since 1.5
  964        */
  965       public static double ulp(double d) {
  966           return sun.misc.FpUtils.ulp(d);
  967       }
  968   
  969       /**
  970        * Returns the size of an ulp of the argument.  An ulp of a
  971        * {@code float} value is the positive distance between this
  972        * floating-point value and the {@code float} value next
  973        * larger in magnitude.  Note that for non-NaN <i>x</i>,
  974        * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
  975        *
  976        * <p>Special Cases:
  977        * <ul>
  978        * <li> If the argument is NaN, then the result is NaN.
  979        * <li> If the argument is positive or negative infinity, then the
  980        * result is positive infinity.
  981        * <li> If the argument is positive or negative zero, then the result is
  982        * {@code Float.MIN_VALUE}.
  983        * <li> If the argument is &plusmn;{@code Float.MAX_VALUE}, then
  984        * the result is equal to 2<sup>104</sup>.
  985        * </ul>
  986        *
  987        * @param f the floating-point value whose ulp is to be returned
  988        * @return the size of an ulp of the argument
  989        * @author Joseph D. Darcy
  990        * @since 1.5
  991        */
  992       public static float ulp(float f) {
  993           return sun.misc.FpUtils.ulp(f);
  994       }
  995   
  996       /**
  997        * Returns the signum function of the argument; zero if the argument
  998        * is zero, 1.0 if the argument is greater than zero, -1.0 if the
  999        * argument is less than zero.
 1000        *
 1001        * <p>Special Cases:
 1002        * <ul>
 1003        * <li> If the argument is NaN, then the result is NaN.
 1004        * <li> If the argument is positive zero or negative zero, then the
 1005        *      result is the same as the argument.
 1006        * </ul>
 1007        *
 1008        * @param d the floating-point value whose signum is to be returned
 1009        * @return the signum function of the argument
 1010        * @author Joseph D. Darcy
 1011        * @since 1.5
 1012        */
 1013       public static double signum(double d) {
 1014           return sun.misc.FpUtils.signum(d);
 1015       }
 1016   
 1017       /**
 1018        * Returns the signum function of the argument; zero if the argument
 1019        * is zero, 1.0f if the argument is greater than zero, -1.0f if the
 1020        * argument is less than zero.
 1021        *
 1022        * <p>Special Cases:
 1023        * <ul>
 1024        * <li> If the argument is NaN, then the result is NaN.
 1025        * <li> If the argument is positive zero or negative zero, then the
 1026        *      result is the same as the argument.
 1027        * </ul>
 1028        *
 1029        * @param f the floating-point value whose signum is to be returned
 1030        * @return the signum function of the argument
 1031        * @author Joseph D. Darcy
 1032        * @since 1.5
 1033        */
 1034       public static float signum(float f) {
 1035           return sun.misc.FpUtils.signum(f);
 1036       }
 1037   
 1038       /**
 1039        * Returns the hyperbolic sine of a {@code double} value.
 1040        * The hyperbolic sine of <i>x</i> is defined to be
 1041        * (<i>e<sup>x</sup>&nbsp;-&nbsp;e<sup>-x</sup></i>)/2
 1042        * where <i>e</i> is {@linkplain Math#E Euler's number}.
 1043        *
 1044        * <p>Special cases:
 1045        * <ul>
 1046        *
 1047        * <li>If the argument is NaN, then the result is NaN.
 1048        *
 1049        * <li>If the argument is infinite, then the result is an infinity
 1050        * with the same sign as the argument.
 1051        *
 1052        * <li>If the argument is zero, then the result is a zero with the
 1053        * same sign as the argument.
 1054        *
 1055        * </ul>
 1056        *
 1057        * <p>The computed result must be within 2.5 ulps of the exact result.
 1058        *
 1059        * @param   x The number whose hyperbolic sine is to be returned.
 1060        * @return  The hyperbolic sine of {@code x}.
 1061        * @since 1.5
 1062        */
 1063       public static double sinh(double x) {
 1064           return StrictMath.sinh(x);
 1065       }
 1066   
 1067       /**
 1068        * Returns the hyperbolic cosine of a {@code double} value.
 1069        * The hyperbolic cosine of <i>x</i> is defined to be
 1070        * (<i>e<sup>x</sup>&nbsp;+&nbsp;e<sup>-x</sup></i>)/2
 1071        * where <i>e</i> is {@linkplain Math#E Euler's number}.
 1072        *
 1073        * <p>Special cases:
 1074        * <ul>
 1075        *
 1076        * <li>If the argument is NaN, then the result is NaN.
 1077        *
 1078        * <li>If the argument is infinite, then the result is positive
 1079        * infinity.
 1080        *
 1081        * <li>If the argument is zero, then the result is {@code 1.0}.
 1082        *
 1083        * </ul>
 1084        *
 1085        * <p>The computed result must be within 2.5 ulps of the exact result.
 1086        *
 1087        * @param   x The number whose hyperbolic cosine is to be returned.
 1088        * @return  The hyperbolic cosine of {@code x}.
 1089        * @since 1.5
 1090        */
 1091       public static double cosh(double x) {
 1092           return StrictMath.cosh(x);
 1093       }
 1094   
 1095       /**
 1096        * Returns the hyperbolic tangent of a {@code double} value.
 1097        * The hyperbolic tangent of <i>x</i> is defined to be
 1098        * (<i>e<sup>x</sup>&nbsp;-&nbsp;e<sup>-x</sup></i>)/(<i>e<sup>x</sup>&nbsp;+&nbsp;e<sup>-x</sup></i>),
 1099        * in other words, {@linkplain Math#sinh
 1100        * sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}.  Note
 1101        * that the absolute value of the exact tanh is always less than
 1102        * 1.
 1103        *
 1104        * <p>Special cases:
 1105        * <ul>
 1106        *
 1107        * <li>If the argument is NaN, then the result is NaN.
 1108        *
 1109        * <li>If the argument is zero, then the result is a zero with the
 1110        * same sign as the argument.
 1111        *
 1112        * <li>If the argument is positive infinity, then the result is
 1113        * {@code +1.0}.
 1114        *
 1115        * <li>If the argument is negative infinity, then the result is
 1116        * {@code -1.0}.
 1117        *
 1118        * </ul>
 1119        *
 1120        * <p>The computed result must be within 2.5 ulps of the exact result.
 1121        * The result of {@code tanh} for any finite input must have
 1122        * an absolute value less than or equal to 1.  Note that once the
 1123        * exact result of tanh is within 1/2 of an ulp of the limit value
 1124        * of &plusmn;1, correctly signed &plusmn;{@code 1.0} should
 1125        * be returned.
 1126        *
 1127        * @param   x The number whose hyperbolic tangent is to be returned.
 1128        * @return  The hyperbolic tangent of {@code x}.
 1129        * @since 1.5
 1130        */
 1131       public static double tanh(double x) {
 1132           return StrictMath.tanh(x);
 1133       }
 1134   
 1135       /**
 1136        * Returns sqrt(<i>x</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
 1137        * without intermediate overflow or underflow.
 1138        *
 1139        * <p>Special cases:
 1140        * <ul>
 1141        *
 1142        * <li> If either argument is infinite, then the result
 1143        * is positive infinity.
 1144        *
 1145        * <li> If either argument is NaN and neither argument is infinite,
 1146        * then the result is NaN.
 1147        *
 1148        * </ul>
 1149        *
 1150        * <p>The computed result must be within 1 ulp of the exact
 1151        * result.  If one parameter is held constant, the results must be
 1152        * semi-monotonic in the other parameter.
 1153        *
 1154        * @param x a value
 1155        * @param y a value
 1156        * @return sqrt(<i>x</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
 1157        * without intermediate overflow or underflow
 1158        * @since 1.5
 1159        */
 1160       public static double hypot(double x, double y) {
 1161           return StrictMath.hypot(x, y);
 1162       }
 1163   
 1164       /**
 1165        * Returns <i>e</i><sup>x</sup>&nbsp;-1.  Note that for values of
 1166        * <i>x</i> near 0, the exact sum of
 1167        * {@code expm1(x)}&nbsp;+&nbsp;1 is much closer to the true
 1168        * result of <i>e</i><sup>x</sup> than {@code exp(x)}.
 1169        *
 1170        * <p>Special cases:
 1171        * <ul>
 1172        * <li>If the argument is NaN, the result is NaN.
 1173        *
 1174        * <li>If the argument is positive infinity, then the result is
 1175        * positive infinity.
 1176        *
 1177        * <li>If the argument is negative infinity, then the result is
 1178        * -1.0.
 1179        *
 1180        * <li>If the argument is zero, then the result is a zero with the
 1181        * same sign as the argument.
 1182        *
 1183        * </ul>
 1184        *
 1185        * <p>The computed result must be within 1 ulp of the exact result.
 1186        * Results must be semi-monotonic.  The result of
 1187        * {@code expm1} for any finite input must be greater than or
 1188        * equal to {@code -1.0}.  Note that once the exact result of
 1189        * <i>e</i><sup>{@code x}</sup>&nbsp;-&nbsp;1 is within 1/2
 1190        * ulp of the limit value -1, {@code -1.0} should be
 1191        * returned.
 1192        *
 1193        * @param   x   the exponent to raise <i>e</i> to in the computation of
 1194        *              <i>e</i><sup>{@code x}</sup>&nbsp;-1.
 1195        * @return  the value <i>e</i><sup>{@code x}</sup>&nbsp;-&nbsp;1.
 1196        * @since 1.5
 1197        */
 1198       public static double expm1(double x) {
 1199           return StrictMath.expm1(x);
 1200       }
 1201   
 1202       /**
 1203        * Returns the natural logarithm of the sum of the argument and 1.
 1204        * Note that for small values {@code x}, the result of
 1205        * {@code log1p(x)} is much closer to the true result of ln(1
 1206        * + {@code x}) than the floating-point evaluation of
 1207        * {@code log(1.0+x)}.
 1208        *
 1209        * <p>Special cases:
 1210        *
 1211        * <ul>
 1212        *
 1213        * <li>If the argument is NaN or less than -1, then the result is
 1214        * NaN.
 1215        *
 1216        * <li>If the argument is positive infinity, then the result is
 1217        * positive infinity.
 1218        *
 1219        * <li>If the argument is negative one, then the result is
 1220        * negative infinity.
 1221        *
 1222        * <li>If the argument is zero, then the result is a zero with the
 1223        * same sign as the argument.
 1224        *
 1225        * </ul>
 1226        *
 1227        * <p>The computed result must be within 1 ulp of the exact result.
 1228        * Results must be semi-monotonic.
 1229        *
 1230        * @param   x   a value
 1231        * @return the value ln({@code x}&nbsp;+&nbsp;1), the natural
 1232        * log of {@code x}&nbsp;+&nbsp;1
 1233        * @since 1.5
 1234        */
 1235       public static double log1p(double x) {
 1236           return StrictMath.log1p(x);
 1237       }
 1238   
 1239       /**
 1240        * Returns the first floating-point argument with the sign of the
 1241        * second floating-point argument.  Note that unlike the {@link
 1242        * StrictMath#copySign(double, double) StrictMath.copySign}
 1243        * method, this method does not require NaN {@code sign}
 1244        * arguments to be treated as positive values; implementations are
 1245        * permitted to treat some NaN arguments as positive and other NaN
 1246        * arguments as negative to allow greater performance.
 1247        *
 1248        * @param magnitude  the parameter providing the magnitude of the result
 1249        * @param sign   the parameter providing the sign of the result
 1250        * @return a value with the magnitude of {@code magnitude}
 1251        * and the sign of {@code sign}.
 1252        * @since 1.6
 1253        */
 1254       public static double copySign(double magnitude, double sign) {
 1255           return sun.misc.FpUtils.rawCopySign(magnitude, sign);
 1256       }
 1257   
 1258       /**
 1259        * Returns the first floating-point argument with the sign of the
 1260        * second floating-point argument.  Note that unlike the {@link
 1261        * StrictMath#copySign(float, float) StrictMath.copySign}
 1262        * method, this method does not require NaN {@code sign}
 1263        * arguments to be treated as positive values; implementations are
 1264        * permitted to treat some NaN arguments as positive and other NaN
 1265        * arguments as negative to allow greater performance.
 1266        *
 1267        * @param magnitude  the parameter providing the magnitude of the result
 1268        * @param sign   the parameter providing the sign of the result
 1269        * @return a value with the magnitude of {@code magnitude}
 1270        * and the sign of {@code sign}.
 1271        * @since 1.6
 1272        */
 1273       public static float copySign(float magnitude, float sign) {
 1274           return sun.misc.FpUtils.rawCopySign(magnitude, sign);
 1275       }
 1276   
 1277       /**
 1278        * Returns the unbiased exponent used in the representation of a
 1279        * {@code float}.  Special cases:
 1280        *
 1281        * <ul>
 1282        * <li>If the argument is NaN or infinite, then the result is
 1283        * {@link Float#MAX_EXPONENT} + 1.
 1284        * <li>If the argument is zero or subnormal, then the result is
 1285        * {@link Float#MIN_EXPONENT} -1.
 1286        * </ul>
 1287        * @param f a {@code float} value
 1288        * @return the unbiased exponent of the argument
 1289        * @since 1.6
 1290        */
 1291       public static int getExponent(float f) {
 1292           return sun.misc.FpUtils.getExponent(f);
 1293       }
 1294   
 1295       /**
 1296        * Returns the unbiased exponent used in the representation of a
 1297        * {@code double}.  Special cases:
 1298        *
 1299        * <ul>
 1300        * <li>If the argument is NaN or infinite, then the result is
 1301        * {@link Double#MAX_EXPONENT} + 1.
 1302        * <li>If the argument is zero or subnormal, then the result is
 1303        * {@link Double#MIN_EXPONENT} -1.
 1304        * </ul>
 1305        * @param d a {@code double} value
 1306        * @return the unbiased exponent of the argument
 1307        * @since 1.6
 1308        */
 1309       public static int getExponent(double d) {
 1310           return sun.misc.FpUtils.getExponent(d);
 1311       }
 1312   
 1313       /**
 1314        * Returns the floating-point number adjacent to the first
 1315        * argument in the direction of the second argument.  If both
 1316        * arguments compare as equal the second argument is returned.
 1317        *
 1318        * <p>
 1319        * Special cases:
 1320        * <ul>
 1321        * <li> If either argument is a NaN, then NaN is returned.
 1322        *
 1323        * <li> If both arguments are signed zeros, {@code direction}
 1324        * is returned unchanged (as implied by the requirement of
 1325        * returning the second argument if the arguments compare as
 1326        * equal).
 1327        *
 1328        * <li> If {@code start} is
 1329        * &plusmn;{@link Double#MIN_VALUE} and {@code direction}
 1330        * has a value such that the result should have a smaller
 1331        * magnitude, then a zero with the same sign as {@code start}
 1332        * is returned.
 1333        *
 1334        * <li> If {@code start} is infinite and
 1335        * {@code direction} has a value such that the result should
 1336        * have a smaller magnitude, {@link Double#MAX_VALUE} with the
 1337        * same sign as {@code start} is returned.
 1338        *
 1339        * <li> If {@code start} is equal to &plusmn;
 1340        * {@link Double#MAX_VALUE} and {@code direction} has a
 1341        * value such that the result should have a larger magnitude, an
 1342        * infinity with same sign as {@code start} is returned.
 1343        * </ul>
 1344        *
 1345        * @param start  starting floating-point value
 1346        * @param direction value indicating which of
 1347        * {@code start}'s neighbors or {@code start} should
 1348        * be returned
 1349        * @return The floating-point number adjacent to {@code start} in the
 1350        * direction of {@code direction}.
 1351        * @since 1.6
 1352        */
 1353       public static double nextAfter(double start, double direction) {
 1354           return sun.misc.FpUtils.nextAfter(start, direction);
 1355       }
 1356   
 1357       /**
 1358        * Returns the floating-point number adjacent to the first
 1359        * argument in the direction of the second argument.  If both
 1360        * arguments compare as equal a value equivalent to the second argument
 1361        * is returned.
 1362        *
 1363        * <p>
 1364        * Special cases:
 1365        * <ul>
 1366        * <li> If either argument is a NaN, then NaN is returned.
 1367        *
 1368        * <li> If both arguments are signed zeros, a value equivalent
 1369        * to {@code direction} is returned.
 1370        *
 1371        * <li> If {@code start} is
 1372        * &plusmn;{@link Float#MIN_VALUE} and {@code direction}
 1373        * has a value such that the result should have a smaller
 1374        * magnitude, then a zero with the same sign as {@code start}
 1375        * is returned.
 1376        *
 1377        * <li> If {@code start} is infinite and
 1378        * {@code direction} has a value such that the result should
 1379        * have a smaller magnitude, {@link Float#MAX_VALUE} with the
 1380        * same sign as {@code start} is returned.
 1381        *
 1382        * <li> If {@code start} is equal to &plusmn;
 1383        * {@link Float#MAX_VALUE} and {@code direction} has a
 1384        * value such that the result should have a larger magnitude, an
 1385        * infinity with same sign as {@code start} is returned.
 1386        * </ul>
 1387        *
 1388        * @param start  starting floating-point value
 1389        * @param direction value indicating which of
 1390        * {@code start}'s neighbors or {@code start} should
 1391        * be returned
 1392        * @return The floating-point number adjacent to {@code start} in the
 1393        * direction of {@code direction}.
 1394        * @since 1.6
 1395        */
 1396       public static float nextAfter(float start, double direction) {
 1397           return sun.misc.FpUtils.nextAfter(start, direction);
 1398       }
 1399   
 1400       /**
 1401        * Returns the floating-point value adjacent to {@code d} in
 1402        * the direction of positive infinity.  This method is
 1403        * semantically equivalent to {@code nextAfter(d,
 1404        * Double.POSITIVE_INFINITY)}; however, a {@code nextUp}
 1405        * implementation may run faster than its equivalent
 1406        * {@code nextAfter} call.
 1407        *
 1408        * <p>Special Cases:
 1409        * <ul>
 1410        * <li> If the argument is NaN, the result is NaN.
 1411        *
 1412        * <li> If the argument is positive infinity, the result is
 1413        * positive infinity.
 1414        *
 1415        * <li> If the argument is zero, the result is
 1416        * {@link Double#MIN_VALUE}
 1417        *
 1418        * </ul>
 1419        *
 1420        * @param d starting floating-point value
 1421        * @return The adjacent floating-point value closer to positive
 1422        * infinity.
 1423        * @since 1.6
 1424        */
 1425       public static double nextUp(double d) {
 1426           return sun.misc.FpUtils.nextUp(d);
 1427       }
 1428   
 1429       /**
 1430        * Returns the floating-point value adjacent to {@code f} in
 1431        * the direction of positive infinity.  This method is
 1432        * semantically equivalent to {@code nextAfter(f,
 1433        * Float.POSITIVE_INFINITY)}; however, a {@code nextUp}
 1434        * implementation may run faster than its equivalent
 1435        * {@code nextAfter} call.
 1436        *
 1437        * <p>Special Cases:
 1438        * <ul>
 1439        * <li> If the argument is NaN, the result is NaN.
 1440        *
 1441        * <li> If the argument is positive infinity, the result is
 1442        * positive infinity.
 1443        *
 1444        * <li> If the argument is zero, the result is
 1445        * {@link Float#MIN_VALUE}
 1446        *
 1447        * </ul>
 1448        *
 1449        * @param f starting floating-point value
 1450        * @return The adjacent floating-point value closer to positive
 1451        * infinity.
 1452        * @since 1.6
 1453        */
 1454       public static float nextUp(float f) {
 1455           return sun.misc.FpUtils.nextUp(f);
 1456       }
 1457   
 1458   
 1459       /**
 1460        * Return {@code d} &times;
 1461        * 2<sup>{@code scaleFactor}</sup> rounded as if performed
 1462        * by a single correctly rounded floating-point multiply to a
 1463        * member of the double value set.  See the Java
 1464        * Language Specification for a discussion of floating-point
 1465        * value sets.  If the exponent of the result is between {@link
 1466        * Double#MIN_EXPONENT} and {@link Double#MAX_EXPONENT}, the
 1467        * answer is calculated exactly.  If the exponent of the result
 1468        * would be larger than {@code Double.MAX_EXPONENT}, an
 1469        * infinity is returned.  Note that if the result is subnormal,
 1470        * precision may be lost; that is, when {@code scalb(x, n)}
 1471        * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
 1472        * <i>x</i>.  When the result is non-NaN, the result has the same
 1473        * sign as {@code d}.
 1474        *
 1475        * <p>Special cases:
 1476        * <ul>
 1477        * <li> If the first argument is NaN, NaN is returned.
 1478        * <li> If the first argument is infinite, then an infinity of the
 1479        * same sign is returned.
 1480        * <li> If the first argument is zero, then a zero of the same
 1481        * sign is returned.
 1482        * </ul>
 1483        *
 1484        * @param d number to be scaled by a power of two.
 1485        * @param scaleFactor power of 2 used to scale {@code d}
 1486        * @return {@code d} &times; 2<sup>{@code scaleFactor}</sup>
 1487        * @since 1.6
 1488        */
 1489       public static double scalb(double d, int scaleFactor) {
 1490           return sun.misc.FpUtils.scalb(d, scaleFactor);
 1491       }
 1492   
 1493       /**
 1494        * Return {@code f} &times;
 1495        * 2<sup>{@code scaleFactor}</sup> rounded as if performed
 1496        * by a single correctly rounded floating-point multiply to a
 1497        * member of the float value set.  See the Java
 1498        * Language Specification for a discussion of floating-point
 1499        * value sets.  If the exponent of the result is between {@link
 1500        * Float#MIN_EXPONENT} and {@link Float#MAX_EXPONENT}, the
 1501        * answer is calculated exactly.  If the exponent of the result
 1502        * would be larger than {@code Float.MAX_EXPONENT}, an
 1503        * infinity is returned.  Note that if the result is subnormal,
 1504        * precision may be lost; that is, when {@code scalb(x, n)}
 1505        * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal
 1506        * <i>x</i>.  When the result is non-NaN, the result has the same
 1507        * sign as {@code f}.
 1508        *
 1509        * <p>Special cases:
 1510        * <ul>
 1511        * <li> If the first argument is NaN, NaN is returned.
 1512        * <li> If the first argument is infinite, then an infinity of the
 1513        * same sign is returned.
 1514        * <li> If the first argument is zero, then a zero of the same
 1515        * sign is returned.
 1516        * </ul>
 1517        *
 1518        * @param f number to be scaled by a power of two.
 1519        * @param scaleFactor power of 2 used to scale {@code f}
 1520        * @return {@code f} &times; 2<sup>{@code scaleFactor}</sup>
 1521        * @since 1.6
 1522        */
 1523       public static float scalb(float f, int scaleFactor) {
 1524           return sun.misc.FpUtils.scalb(f, scaleFactor);
 1525       }
 1526   }

Save This Page
Home » openjdk-7 » java » lang » [javadoc | source]