src/java.base/share/classes/java/lang/Math.java
Index Unified diffs Context diffs Sdiffs Patch New Old Previous File Next File 8076112 Sdiff src/java.base/share/classes/java/lang

src/java.base/share/classes/java/lang/Math.java

Print this page




   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 import sun.misc.FloatConsts;
  30 import sun.misc.DoubleConsts;

  31 
  32 /**
  33  * The class {@code Math} contains methods for performing basic
  34  * numeric operations such as the elementary exponential, logarithm,
  35  * square root, and trigonometric functions.
  36  *
  37  * <p>Unlike some of the numeric methods of class
  38  * {@code StrictMath}, all implementations of the equivalent
  39  * functions of class {@code Math} are not defined to return the
  40  * bit-for-bit same results.  This relaxation permits
  41  * better-performing implementations where strict reproducibility is
  42  * not required.
  43  *
  44  * <p>By default many of the {@code Math} methods simply call
  45  * the equivalent method in {@code StrictMath} for their
  46  * implementation.  Code generators are encouraged to use
  47  * platform-specific native libraries or microprocessor instructions,
  48  * where available, to provide higher-performance implementations of
  49  * {@code Math} methods.  Such higher-performance
  50  * implementations still must conform to the specification for


 130 
 131     /**
 132      * Constant by which to multiply an angular value in radians to obtain an
 133      * angular value in degrees.
 134      */
 135     private static final double RADIANS_TO_DEGREES = 57.29577951308232;
 136 
 137     /**
 138      * Returns the trigonometric sine of an angle.  Special cases:
 139      * <ul><li>If the argument is NaN or an infinity, then the
 140      * result is NaN.
 141      * <li>If the argument is zero, then the result is a zero with the
 142      * same sign as the argument.</ul>
 143      *
 144      * <p>The computed result must be within 1 ulp of the exact result.
 145      * Results must be semi-monotonic.
 146      *
 147      * @param   a   an angle, in radians.
 148      * @return  the sine of the argument.
 149      */

 150     public static double sin(double a) {
 151         return StrictMath.sin(a); // default impl. delegates to StrictMath
 152     }
 153 
 154     /**
 155      * Returns the trigonometric cosine of an angle. Special cases:
 156      * <ul><li>If the argument is NaN or an infinity, then the
 157      * result is NaN.</ul>
 158      *
 159      * <p>The computed result must be within 1 ulp of the exact result.
 160      * Results must be semi-monotonic.
 161      *
 162      * @param   a   an angle, in radians.
 163      * @return  the cosine of the argument.
 164      */

 165     public static double cos(double a) {
 166         return StrictMath.cos(a); // default impl. delegates to StrictMath
 167     }
 168 
 169     /**
 170      * Returns the trigonometric tangent of an angle.  Special cases:
 171      * <ul><li>If the argument is NaN or an infinity, then the result
 172      * is NaN.
 173      * <li>If the argument is zero, then the result is a zero with the
 174      * same sign as the argument.</ul>
 175      *
 176      * <p>The computed result must be within 1 ulp of the exact result.
 177      * Results must be semi-monotonic.
 178      *
 179      * @param   a   an angle, in radians.
 180      * @return  the tangent of the argument.
 181      */

 182     public static double tan(double a) {
 183         return StrictMath.tan(a); // default impl. delegates to StrictMath
 184     }
 185 
 186     /**
 187      * Returns the arc sine of a value; the returned angle is in the
 188      * range -<i>pi</i>/2 through <i>pi</i>/2.  Special cases:
 189      * <ul><li>If the argument is NaN or its absolute value is greater
 190      * than 1, then the result is NaN.
 191      * <li>If the argument is zero, then the result is a zero with the
 192      * same sign as the argument.</ul>
 193      *
 194      * <p>The computed result must be within 1 ulp of the exact result.
 195      * Results must be semi-monotonic.
 196      *
 197      * @param   a   the value whose arc sine is to be returned.
 198      * @return  the arc sine of the argument.
 199      */
 200     public static double asin(double a) {
 201         return StrictMath.asin(a); // default impl. delegates to StrictMath


 263     public static double toDegrees(double angrad) {
 264         return angrad * RADIANS_TO_DEGREES;
 265     }
 266 
 267     /**
 268      * Returns Euler's number <i>e</i> raised to the power of a
 269      * {@code double} value.  Special cases:
 270      * <ul><li>If the argument is NaN, the result is NaN.
 271      * <li>If the argument is positive infinity, then the result is
 272      * positive infinity.
 273      * <li>If the argument is negative infinity, then the result is
 274      * positive zero.</ul>
 275      *
 276      * <p>The computed result must be within 1 ulp of the exact result.
 277      * Results must be semi-monotonic.
 278      *
 279      * @param   a   the exponent to raise <i>e</i> to.
 280      * @return  the value <i>e</i><sup>{@code a}</sup>,
 281      *          where <i>e</i> is the base of the natural logarithms.
 282      */

 283     public static double exp(double a) {
 284         return StrictMath.exp(a); // default impl. delegates to StrictMath
 285     }
 286 
 287     /**
 288      * Returns the natural logarithm (base <i>e</i>) of a {@code double}
 289      * value.  Special cases:
 290      * <ul><li>If the argument is NaN or less than zero, then the result
 291      * is NaN.
 292      * <li>If the argument is positive infinity, then the result is
 293      * positive infinity.
 294      * <li>If the argument is positive zero or negative zero, then the
 295      * result is negative infinity.</ul>
 296      *
 297      * <p>The computed result must be within 1 ulp of the exact result.
 298      * Results must be semi-monotonic.
 299      *
 300      * @param   a   a value
 301      * @return  the value ln&nbsp;{@code a}, the natural logarithm of
 302      *          {@code a}.
 303      */

 304     public static double log(double a) {
 305         return StrictMath.log(a); // default impl. delegates to StrictMath
 306     }
 307 
 308     /**
 309      * Returns the base 10 logarithm of a {@code double} value.
 310      * Special cases:
 311      *
 312      * <ul><li>If the argument is NaN or less than zero, then the result
 313      * is NaN.
 314      * <li>If the argument is positive infinity, then the result is
 315      * positive infinity.
 316      * <li>If the argument is positive zero or negative zero, then the
 317      * result is negative infinity.
 318      * <li> If the argument is equal to 10<sup><i>n</i></sup> for
 319      * integer <i>n</i>, then the result is <i>n</i>.
 320      * </ul>
 321      *
 322      * <p>The computed result must be within 1 ulp of the exact result.
 323      * Results must be semi-monotonic.
 324      *
 325      * @param   a   a value
 326      * @return  the base 10 logarithm of  {@code a}.
 327      * @since 1.5
 328      */

 329     public static double log10(double a) {
 330         return StrictMath.log10(a); // default impl. delegates to StrictMath
 331     }
 332 
 333     /**
 334      * Returns the correctly rounded positive square root of a
 335      * {@code double} value.
 336      * Special cases:
 337      * <ul><li>If the argument is NaN or less than zero, then the result
 338      * is NaN.
 339      * <li>If the argument is positive infinity, then the result is positive
 340      * infinity.
 341      * <li>If the argument is positive zero or negative zero, then the
 342      * result is the same as the argument.</ul>
 343      * Otherwise, the result is the {@code double} value closest to
 344      * the true mathematical square root of the argument value.
 345      *
 346      * @param   a   a value.
 347      * @return  the positive square root of {@code a}.
 348      *          If the argument is NaN or less than zero, the result is NaN.
 349      */

 350     public static double sqrt(double a) {
 351         return StrictMath.sqrt(a); // default impl. delegates to StrictMath
 352                                    // Note that hardware sqrt instructions
 353                                    // frequently can be directly used by JITs
 354                                    // and should be much faster than doing
 355                                    // Math.sqrt in software.
 356     }
 357 
 358 
 359     /**
 360      * Returns the cube root of a {@code double} value.  For
 361      * positive finite {@code x}, {@code cbrt(-x) ==
 362      * -cbrt(x)}; that is, the cube root of a negative value is
 363      * the negative of the cube root of that value's magnitude.
 364      *
 365      * Special cases:
 366      *
 367      * <ul>
 368      *
 369      * <li>If the argument is NaN, then the result is NaN.


 508      * {@code double} value closest to <i>pi</i>/4.
 509      * <li>If the first argument is positive infinity and the second argument
 510      * is negative infinity, then the result is the {@code double}
 511      * value closest to 3*<i>pi</i>/4.
 512      * <li>If the first argument is negative infinity and the second argument
 513      * is positive infinity, then the result is the {@code double} value
 514      * closest to -<i>pi</i>/4.
 515      * <li>If both arguments are negative infinity, then the result is the
 516      * {@code double} value closest to -3*<i>pi</i>/4.</ul>
 517      *
 518      * <p>The computed result must be within 2 ulps of the exact result.
 519      * Results must be semi-monotonic.
 520      *
 521      * @param   y   the ordinate coordinate
 522      * @param   x   the abscissa coordinate
 523      * @return  the <i>theta</i> component of the point
 524      *          (<i>r</i>,&nbsp;<i>theta</i>)
 525      *          in polar coordinates that corresponds to the point
 526      *          (<i>x</i>,&nbsp;<i>y</i>) in Cartesian coordinates.
 527      */

 528     public static double atan2(double y, double x) {
 529         return StrictMath.atan2(y, x); // default impl. delegates to StrictMath
 530     }
 531 
 532     /**
 533      * Returns the value of the first argument raised to the power of the
 534      * second argument. Special cases:
 535      *
 536      * <ul><li>If the second argument is positive or negative zero, then the
 537      * result is 1.0.
 538      * <li>If the second argument is 1.0, then the result is the same as the
 539      * first argument.
 540      * <li>If the second argument is NaN, then the result is NaN.
 541      * <li>If the first argument is NaN and the second argument is nonzero,
 542      * then the result is NaN.
 543      *
 544      * <li>If
 545      * <ul>
 546      * <li>the absolute value of the first argument is greater than 1
 547      * and the second argument is positive infinity, or


 635      * <li>If both arguments are integers, then the result is exactly equal
 636      * to the mathematical result of raising the first argument to the power
 637      * of the second argument if that result can in fact be represented
 638      * exactly as a {@code double} value.</ul>
 639      *
 640      * <p>(In the foregoing descriptions, a floating-point value is
 641      * considered to be an integer if and only if it is finite and a
 642      * fixed point of the method {@link #ceil ceil} or,
 643      * equivalently, a fixed point of the method {@link #floor
 644      * floor}. A value is a fixed point of a one-argument
 645      * method if and only if the result of applying the method to the
 646      * value is equal to the value.)
 647      *
 648      * <p>The computed result must be within 1 ulp of the exact result.
 649      * Results must be semi-monotonic.
 650      *
 651      * @param   a   the base.
 652      * @param   b   the exponent.
 653      * @return  the value {@code a}<sup>{@code b}</sup>.
 654      */

 655     public static double pow(double a, double b) {
 656         return StrictMath.pow(a, b); // default impl. delegates to StrictMath
 657     }
 658 
 659     /**
 660      * Returns the closest {@code int} to the argument, with ties
 661      * rounding to positive infinity.
 662      *
 663      * <p>
 664      * Special cases:
 665      * <ul><li>If the argument is NaN, the result is 0.
 666      * <li>If the argument is negative infinity or any value less than or
 667      * equal to the value of {@code Integer.MIN_VALUE}, the result is
 668      * equal to the value of {@code Integer.MIN_VALUE}.
 669      * <li>If the argument is positive infinity or any value greater than or
 670      * equal to the value of {@code Integer.MAX_VALUE}, the result is
 671      * equal to the value of {@code Integer.MAX_VALUE}.</ul>
 672      *
 673      * @param   a   a floating-point value to be rounded to an integer.
 674      * @return  the value of the argument rounded to the nearest


 789      *
 790      * @return  a pseudorandom {@code double} greater than or equal
 791      * to {@code 0.0} and less than {@code 1.0}.
 792      * @see #nextDown(double)
 793      * @see Random#nextDouble()
 794      */
 795     public static double random() {
 796         return RandomNumberGeneratorHolder.randomNumberGenerator.nextDouble();
 797     }
 798 
 799     /**
 800      * Returns the sum of its arguments,
 801      * throwing an exception if the result overflows an {@code int}.
 802      *
 803      * @param x the first value
 804      * @param y the second value
 805      * @return the result
 806      * @throws ArithmeticException if the result overflows an int
 807      * @since 1.8
 808      */

 809     public static int addExact(int x, int y) {
 810         int r = x + y;
 811         // HD 2-12 Overflow iff both arguments have the opposite sign of the result
 812         if (((x ^ r) & (y ^ r)) < 0) {
 813             throw new ArithmeticException("integer overflow");
 814         }
 815         return r;
 816     }
 817 
 818     /**
 819      * Returns the sum of its arguments,
 820      * throwing an exception if the result overflows a {@code long}.
 821      *
 822      * @param x the first value
 823      * @param y the second value
 824      * @return the result
 825      * @throws ArithmeticException if the result overflows a long
 826      * @since 1.8
 827      */

 828     public static long addExact(long x, long y) {
 829         long r = x + y;
 830         // HD 2-12 Overflow iff both arguments have the opposite sign of the result
 831         if (((x ^ r) & (y ^ r)) < 0) {
 832             throw new ArithmeticException("long overflow");
 833         }
 834         return r;
 835     }
 836 
 837     /**
 838      * Returns the difference of the arguments,
 839      * throwing an exception if the result overflows an {@code int}.
 840      *
 841      * @param x the first value
 842      * @param y the second value to subtract from the first
 843      * @return the result
 844      * @throws ArithmeticException if the result overflows an int
 845      * @since 1.8
 846      */

 847     public static int subtractExact(int x, int y) {
 848         int r = x - y;
 849         // HD 2-12 Overflow iff the arguments have different signs and
 850         // the sign of the result is different than the sign of x
 851         if (((x ^ y) & (x ^ r)) < 0) {
 852             throw new ArithmeticException("integer overflow");
 853         }
 854         return r;
 855     }
 856 
 857     /**
 858      * Returns the difference of the arguments,
 859      * throwing an exception if the result overflows a {@code long}.
 860      *
 861      * @param x the first value
 862      * @param y the second value to subtract from the first
 863      * @return the result
 864      * @throws ArithmeticException if the result overflows a long
 865      * @since 1.8
 866      */

 867     public static long subtractExact(long x, long y) {
 868         long r = x - y;
 869         // HD 2-12 Overflow iff the arguments have different signs and
 870         // the sign of the result is different than the sign of x
 871         if (((x ^ y) & (x ^ r)) < 0) {
 872             throw new ArithmeticException("long overflow");
 873         }
 874         return r;
 875     }
 876 
 877     /**
 878      * Returns the product of the arguments,
 879      * throwing an exception if the result overflows an {@code int}.
 880      *
 881      * @param x the first value
 882      * @param y the second value
 883      * @return the result
 884      * @throws ArithmeticException if the result overflows an int
 885      * @since 1.8
 886      */

 887     public static int multiplyExact(int x, int y) {
 888         long r = (long)x * (long)y;
 889         if ((int)r != r) {
 890             throw new ArithmeticException("integer overflow");
 891         }
 892         return (int)r;
 893     }
 894 
 895     /**
 896      * Returns the product of the arguments,
 897      * throwing an exception if the result overflows a {@code long}.
 898      *
 899      * @param x the first value
 900      * @param y the second value
 901      * @return the result
 902      * @throws ArithmeticException if the result overflows a long
 903      * @since 1.8
 904      */

 905     public static long multiplyExact(long x, long y) {
 906         long r = x * y;
 907         long ax = Math.abs(x);
 908         long ay = Math.abs(y);
 909         if (((ax | ay) >>> 31 != 0)) {
 910             // Some bits greater than 2^31 that might cause overflow
 911             // Check the result using the divide operator
 912             // and check for the special case of Long.MIN_VALUE * -1
 913            if (((y != 0) && (r / y != x)) ||
 914                (x == Long.MIN_VALUE && y == -1)) {
 915                 throw new ArithmeticException("long overflow");
 916             }
 917         }
 918         return r;
 919     }
 920 
 921     /**
 922      * Returns the argument incremented by one, throwing an exception if the
 923      * result overflows an {@code int}.
 924      *
 925      * @param a the value to increment
 926      * @return the result
 927      * @throws ArithmeticException if the result overflows an int
 928      * @since 1.8
 929      */

 930     public static int incrementExact(int a) {
 931         if (a == Integer.MAX_VALUE) {
 932             throw new ArithmeticException("integer overflow");
 933         }
 934 
 935         return a + 1;
 936     }
 937 
 938     /**
 939      * Returns the argument incremented by one, throwing an exception if the
 940      * result overflows a {@code long}.
 941      *
 942      * @param a the value to increment
 943      * @return the result
 944      * @throws ArithmeticException if the result overflows a long
 945      * @since 1.8
 946      */

 947     public static long incrementExact(long a) {
 948         if (a == Long.MAX_VALUE) {
 949             throw new ArithmeticException("long overflow");
 950         }
 951 
 952         return a + 1L;
 953     }
 954 
 955     /**
 956      * Returns the argument decremented by one, throwing an exception if the
 957      * result overflows an {@code int}.
 958      *
 959      * @param a the value to decrement
 960      * @return the result
 961      * @throws ArithmeticException if the result overflows an int
 962      * @since 1.8
 963      */

 964     public static int decrementExact(int a) {
 965         if (a == Integer.MIN_VALUE) {
 966             throw new ArithmeticException("integer overflow");
 967         }
 968 
 969         return a - 1;
 970     }
 971 
 972     /**
 973      * Returns the argument decremented by one, throwing an exception if the
 974      * result overflows a {@code long}.
 975      *
 976      * @param a the value to decrement
 977      * @return the result
 978      * @throws ArithmeticException if the result overflows a long
 979      * @since 1.8
 980      */

 981     public static long decrementExact(long a) {
 982         if (a == Long.MIN_VALUE) {
 983             throw new ArithmeticException("long overflow");
 984         }
 985 
 986         return a - 1L;
 987     }
 988 
 989     /**
 990      * Returns the negation of the argument, throwing an exception if the
 991      * result overflows an {@code int}.
 992      *
 993      * @param a the value to negate
 994      * @return the result
 995      * @throws ArithmeticException if the result overflows an int
 996      * @since 1.8
 997      */

 998     public static int negateExact(int a) {
 999         if (a == Integer.MIN_VALUE) {
1000             throw new ArithmeticException("integer overflow");
1001         }
1002 
1003         return -a;
1004     }
1005 
1006     /**
1007      * Returns the negation of the argument, throwing an exception if the
1008      * result overflows a {@code long}.
1009      *
1010      * @param a the value to negate
1011      * @return the result
1012      * @throws ArithmeticException if the result overflows a long
1013      * @since 1.8
1014      */

1015     public static long negateExact(long a) {
1016         if (a == Long.MIN_VALUE) {
1017             throw new ArithmeticException("long overflow");
1018         }
1019 
1020         return -a;
1021     }
1022 
1023     /**
1024      * Returns the value of the {@code long} argument;
1025      * throwing an exception if the value overflows an {@code int}.
1026      *
1027      * @param value the long value
1028      * @return the argument as an int
1029      * @throws ArithmeticException if the {@code argument} overflows an int
1030      * @since 1.8
1031      */
1032     public static int toIntExact(long value) {
1033         if ((int)value != value) {
1034             throw new ArithmeticException("integer overflow");


1239      */
1240     public static float abs(float a) {
1241         return (a <= 0.0F) ? 0.0F - a : a;
1242     }
1243 
1244     /**
1245      * Returns the absolute value of a {@code double} value.
1246      * If the argument is not negative, the argument is returned.
1247      * If the argument is negative, the negation of the argument is returned.
1248      * Special cases:
1249      * <ul><li>If the argument is positive zero or negative zero, the result
1250      * is positive zero.
1251      * <li>If the argument is infinite, the result is positive infinity.
1252      * <li>If the argument is NaN, the result is NaN.</ul>
1253      * In other words, the result is the same as the value of the expression:
1254      * <p>{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)}
1255      *
1256      * @param   a   the argument whose absolute value is to be determined
1257      * @return  the absolute value of the argument.
1258      */

1259     public static double abs(double a) {
1260         return (a <= 0.0D) ? 0.0D - a : a;
1261     }
1262 
1263     /**
1264      * Returns the greater of two {@code int} values. That is, the
1265      * result is the argument closer to the value of
1266      * {@link Integer#MAX_VALUE}. If the arguments have the same value,
1267      * the result is that same value.
1268      *
1269      * @param   a   an argument.
1270      * @param   b   another argument.
1271      * @return  the larger of {@code a} and {@code b}.
1272      */

1273     public static int max(int a, int b) {
1274         return (a >= b) ? a : b;
1275     }
1276 
1277     /**
1278      * Returns the greater of two {@code long} values. That is, the
1279      * result is the argument closer to the value of
1280      * {@link Long#MAX_VALUE}. If the arguments have the same value,
1281      * the result is that same value.
1282      *
1283      * @param   a   an argument.
1284      * @param   b   another argument.
1285      * @return  the larger of {@code a} and {@code b}.
1286      */
1287     public static long max(long a, long b) {
1288         return (a >= b) ? a : b;
1289     }
1290 
1291     // Use raw bit-wise conversions on guaranteed non-NaN arguments.
1292     private static long negativeZeroFloatBits  = Float.floatToRawIntBits(-0.0f);


1337             return a;   // a is NaN
1338         if ((a == 0.0d) &&
1339             (b == 0.0d) &&
1340             (Double.doubleToRawLongBits(a) == negativeZeroDoubleBits)) {
1341             // Raw conversion ok since NaN can't map to -0.0.
1342             return b;
1343         }
1344         return (a >= b) ? a : b;
1345     }
1346 
1347     /**
1348      * Returns the smaller of two {@code int} values. That is,
1349      * the result the argument closer to the value of
1350      * {@link Integer#MIN_VALUE}.  If the arguments have the same
1351      * value, the result is that same value.
1352      *
1353      * @param   a   an argument.
1354      * @param   b   another argument.
1355      * @return  the smaller of {@code a} and {@code b}.
1356      */

1357     public static int min(int a, int b) {
1358         return (a <= b) ? a : b;
1359     }
1360 
1361     /**
1362      * Returns the smaller of two {@code long} values. That is,
1363      * the result is the argument closer to the value of
1364      * {@link Long#MIN_VALUE}. If the arguments have the same
1365      * value, the result is that same value.
1366      *
1367      * @param   a   an argument.
1368      * @param   b   another argument.
1369      * @return  the smaller of {@code a} and {@code b}.
1370      */
1371     public static long min(long a, long b) {
1372         return (a <= b) ? a : b;
1373     }
1374 
1375     /**
1376      * Returns the smaller of two {@code float} values.  That is,




   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 
  28 import java.util.Random;
  29 import sun.misc.FloatConsts;
  30 import sun.misc.DoubleConsts;
  31 import jdk.internal.HotSpotIntrinsicCandidate;
  32 
  33 /**
  34  * The class {@code Math} contains methods for performing basic
  35  * numeric operations such as the elementary exponential, logarithm,
  36  * square root, and trigonometric functions.
  37  *
  38  * <p>Unlike some of the numeric methods of class
  39  * {@code StrictMath}, all implementations of the equivalent
  40  * functions of class {@code Math} are not defined to return the
  41  * bit-for-bit same results.  This relaxation permits
  42  * better-performing implementations where strict reproducibility is
  43  * not required.
  44  *
  45  * <p>By default many of the {@code Math} methods simply call
  46  * the equivalent method in {@code StrictMath} for their
  47  * implementation.  Code generators are encouraged to use
  48  * platform-specific native libraries or microprocessor instructions,
  49  * where available, to provide higher-performance implementations of
  50  * {@code Math} methods.  Such higher-performance
  51  * implementations still must conform to the specification for


 131 
 132     /**
 133      * Constant by which to multiply an angular value in radians to obtain an
 134      * angular value in degrees.
 135      */
 136     private static final double RADIANS_TO_DEGREES = 57.29577951308232;
 137 
 138     /**
 139      * Returns the trigonometric sine of an angle.  Special cases:
 140      * <ul><li>If the argument is NaN or an infinity, then the
 141      * result is NaN.
 142      * <li>If the argument is zero, then the result is a zero with the
 143      * same sign as the argument.</ul>
 144      *
 145      * <p>The computed result must be within 1 ulp of the exact result.
 146      * Results must be semi-monotonic.
 147      *
 148      * @param   a   an angle, in radians.
 149      * @return  the sine of the argument.
 150      */
 151     @HotSpotIntrinsicCandidate
 152     public static double sin(double a) {
 153         return StrictMath.sin(a); // default impl. delegates to StrictMath
 154     }
 155 
 156     /**
 157      * Returns the trigonometric cosine of an angle. Special cases:
 158      * <ul><li>If the argument is NaN or an infinity, then the
 159      * result is NaN.</ul>
 160      *
 161      * <p>The computed result must be within 1 ulp of the exact result.
 162      * Results must be semi-monotonic.
 163      *
 164      * @param   a   an angle, in radians.
 165      * @return  the cosine of the argument.
 166      */
 167     @HotSpotIntrinsicCandidate
 168     public static double cos(double a) {
 169         return StrictMath.cos(a); // default impl. delegates to StrictMath
 170     }
 171 
 172     /**
 173      * Returns the trigonometric tangent of an angle.  Special cases:
 174      * <ul><li>If the argument is NaN or an infinity, then the result
 175      * is NaN.
 176      * <li>If the argument is zero, then the result is a zero with the
 177      * same sign as the argument.</ul>
 178      *
 179      * <p>The computed result must be within 1 ulp of the exact result.
 180      * Results must be semi-monotonic.
 181      *
 182      * @param   a   an angle, in radians.
 183      * @return  the tangent of the argument.
 184      */
 185     @HotSpotIntrinsicCandidate
 186     public static double tan(double a) {
 187         return StrictMath.tan(a); // default impl. delegates to StrictMath
 188     }
 189 
 190     /**
 191      * Returns the arc sine 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 or its absolute value is greater
 194      * than 1, then the result is NaN.
 195      * <li>If the argument is zero, then the result is a zero with the
 196      * same sign as the argument.</ul>
 197      *
 198      * <p>The computed result must be within 1 ulp of the exact result.
 199      * Results must be semi-monotonic.
 200      *
 201      * @param   a   the value whose arc sine is to be returned.
 202      * @return  the arc sine of the argument.
 203      */
 204     public static double asin(double a) {
 205         return StrictMath.asin(a); // default impl. delegates to StrictMath


 267     public static double toDegrees(double angrad) {
 268         return angrad * RADIANS_TO_DEGREES;
 269     }
 270 
 271     /**
 272      * Returns Euler's number <i>e</i> raised to the power of a
 273      * {@code double} value.  Special cases:
 274      * <ul><li>If the argument is NaN, the result is NaN.
 275      * <li>If the argument is positive infinity, then the result is
 276      * positive infinity.
 277      * <li>If the argument is negative infinity, then the result is
 278      * positive zero.</ul>
 279      *
 280      * <p>The computed result must be within 1 ulp of the exact result.
 281      * Results must be semi-monotonic.
 282      *
 283      * @param   a   the exponent to raise <i>e</i> to.
 284      * @return  the value <i>e</i><sup>{@code a}</sup>,
 285      *          where <i>e</i> is the base of the natural logarithms.
 286      */
 287     @HotSpotIntrinsicCandidate
 288     public static double exp(double a) {
 289         return StrictMath.exp(a); // default impl. delegates to StrictMath
 290     }
 291 
 292     /**
 293      * Returns the natural logarithm (base <i>e</i>) of a {@code double}
 294      * value.  Special cases:
 295      * <ul><li>If the argument is NaN or less than zero, then the result
 296      * is NaN.
 297      * <li>If the argument is positive infinity, then the result is
 298      * positive infinity.
 299      * <li>If the argument is positive zero or negative zero, then the
 300      * result is negative infinity.</ul>
 301      *
 302      * <p>The computed result must be within 1 ulp of the exact result.
 303      * Results must be semi-monotonic.
 304      *
 305      * @param   a   a value
 306      * @return  the value ln&nbsp;{@code a}, the natural logarithm of
 307      *          {@code a}.
 308      */
 309     @HotSpotIntrinsicCandidate
 310     public static double log(double a) {
 311         return StrictMath.log(a); // default impl. delegates to StrictMath
 312     }
 313 
 314     /**
 315      * Returns the base 10 logarithm of a {@code double} value.
 316      * Special cases:
 317      *
 318      * <ul><li>If the argument is NaN or less than zero, then the result
 319      * is NaN.
 320      * <li>If the argument is positive infinity, then the result is
 321      * positive infinity.
 322      * <li>If the argument is positive zero or negative zero, then the
 323      * result is negative infinity.
 324      * <li> If the argument is equal to 10<sup><i>n</i></sup> for
 325      * integer <i>n</i>, then the result is <i>n</i>.
 326      * </ul>
 327      *
 328      * <p>The computed result must be within 1 ulp of the exact result.
 329      * Results must be semi-monotonic.
 330      *
 331      * @param   a   a value
 332      * @return  the base 10 logarithm of  {@code a}.
 333      * @since 1.5
 334      */
 335     @HotSpotIntrinsicCandidate
 336     public static double log10(double a) {
 337         return StrictMath.log10(a); // default impl. delegates to StrictMath
 338     }
 339 
 340     /**
 341      * Returns the correctly rounded positive square root of a
 342      * {@code double} value.
 343      * Special cases:
 344      * <ul><li>If the argument is NaN or less than zero, then the result
 345      * is NaN.
 346      * <li>If the argument is positive infinity, then the result is positive
 347      * infinity.
 348      * <li>If the argument is positive zero or negative zero, then the
 349      * result is the same as the argument.</ul>
 350      * Otherwise, the result is the {@code double} value closest to
 351      * the true mathematical square root of the argument value.
 352      *
 353      * @param   a   a value.
 354      * @return  the positive square root of {@code a}.
 355      *          If the argument is NaN or less than zero, the result is NaN.
 356      */
 357     @HotSpotIntrinsicCandidate
 358     public static double sqrt(double a) {
 359         return StrictMath.sqrt(a); // default impl. delegates to StrictMath
 360                                    // Note that hardware sqrt instructions
 361                                    // frequently can be directly used by JITs
 362                                    // and should be much faster than doing
 363                                    // Math.sqrt in software.
 364     }
 365 
 366 
 367     /**
 368      * Returns the cube root of a {@code double} value.  For
 369      * positive finite {@code x}, {@code cbrt(-x) ==
 370      * -cbrt(x)}; that is, the cube root of a negative value is
 371      * the negative of the cube root of that value's magnitude.
 372      *
 373      * Special cases:
 374      *
 375      * <ul>
 376      *
 377      * <li>If the argument is NaN, then the result is NaN.


 516      * {@code double} value closest to <i>pi</i>/4.
 517      * <li>If the first argument is positive infinity and the second argument
 518      * is negative infinity, then the result is the {@code double}
 519      * value closest to 3*<i>pi</i>/4.
 520      * <li>If the first argument is negative infinity and the second argument
 521      * is positive infinity, then the result is the {@code double} value
 522      * closest to -<i>pi</i>/4.
 523      * <li>If both arguments are negative infinity, then the result is the
 524      * {@code double} value closest to -3*<i>pi</i>/4.</ul>
 525      *
 526      * <p>The computed result must be within 2 ulps of the exact result.
 527      * Results must be semi-monotonic.
 528      *
 529      * @param   y   the ordinate coordinate
 530      * @param   x   the abscissa coordinate
 531      * @return  the <i>theta</i> component of the point
 532      *          (<i>r</i>,&nbsp;<i>theta</i>)
 533      *          in polar coordinates that corresponds to the point
 534      *          (<i>x</i>,&nbsp;<i>y</i>) in Cartesian coordinates.
 535      */
 536     @HotSpotIntrinsicCandidate
 537     public static double atan2(double y, double x) {
 538         return StrictMath.atan2(y, x); // default impl. delegates to StrictMath
 539     }
 540 
 541     /**
 542      * Returns the value of the first argument raised to the power of the
 543      * second argument. Special cases:
 544      *
 545      * <ul><li>If the second argument is positive or negative zero, then the
 546      * result is 1.0.
 547      * <li>If the second argument is 1.0, then the result is the same as the
 548      * first argument.
 549      * <li>If the second argument is NaN, then the result is NaN.
 550      * <li>If the first argument is NaN and the second argument is nonzero,
 551      * then the result is NaN.
 552      *
 553      * <li>If
 554      * <ul>
 555      * <li>the absolute value of the first argument is greater than 1
 556      * and the second argument is positive infinity, or


 644      * <li>If both arguments are integers, then the result is exactly equal
 645      * to the mathematical result of raising the first argument to the power
 646      * of the second argument if that result can in fact be represented
 647      * exactly as a {@code double} value.</ul>
 648      *
 649      * <p>(In the foregoing descriptions, a floating-point value is
 650      * considered to be an integer if and only if it is finite and a
 651      * fixed point of the method {@link #ceil ceil} or,
 652      * equivalently, a fixed point of the method {@link #floor
 653      * floor}. A value is a fixed point of a one-argument
 654      * method if and only if the result of applying the method to the
 655      * value is equal to the value.)
 656      *
 657      * <p>The computed result must be within 1 ulp of the exact result.
 658      * Results must be semi-monotonic.
 659      *
 660      * @param   a   the base.
 661      * @param   b   the exponent.
 662      * @return  the value {@code a}<sup>{@code b}</sup>.
 663      */
 664     @HotSpotIntrinsicCandidate
 665     public static double pow(double a, double b) {
 666         return StrictMath.pow(a, b); // default impl. delegates to StrictMath
 667     }
 668 
 669     /**
 670      * Returns the closest {@code int} to the argument, with ties
 671      * rounding to positive infinity.
 672      *
 673      * <p>
 674      * Special cases:
 675      * <ul><li>If the argument is NaN, the result is 0.
 676      * <li>If the argument is negative infinity or any value less than or
 677      * equal to the value of {@code Integer.MIN_VALUE}, the result is
 678      * equal to the value of {@code Integer.MIN_VALUE}.
 679      * <li>If the argument is positive infinity or any value greater than or
 680      * equal to the value of {@code Integer.MAX_VALUE}, the result is
 681      * equal to the value of {@code Integer.MAX_VALUE}.</ul>
 682      *
 683      * @param   a   a floating-point value to be rounded to an integer.
 684      * @return  the value of the argument rounded to the nearest


 799      *
 800      * @return  a pseudorandom {@code double} greater than or equal
 801      * to {@code 0.0} and less than {@code 1.0}.
 802      * @see #nextDown(double)
 803      * @see Random#nextDouble()
 804      */
 805     public static double random() {
 806         return RandomNumberGeneratorHolder.randomNumberGenerator.nextDouble();
 807     }
 808 
 809     /**
 810      * Returns the sum of its arguments,
 811      * throwing an exception if the result overflows an {@code int}.
 812      *
 813      * @param x the first value
 814      * @param y the second value
 815      * @return the result
 816      * @throws ArithmeticException if the result overflows an int
 817      * @since 1.8
 818      */
 819     @HotSpotIntrinsicCandidate
 820     public static int addExact(int x, int y) {
 821         int r = x + y;
 822         // HD 2-12 Overflow iff both arguments have the opposite sign of the result
 823         if (((x ^ r) & (y ^ r)) < 0) {
 824             throw new ArithmeticException("integer overflow");
 825         }
 826         return r;
 827     }
 828 
 829     /**
 830      * Returns the sum of its arguments,
 831      * throwing an exception if the result overflows a {@code long}.
 832      *
 833      * @param x the first value
 834      * @param y the second value
 835      * @return the result
 836      * @throws ArithmeticException if the result overflows a long
 837      * @since 1.8
 838      */
 839     @HotSpotIntrinsicCandidate
 840     public static long addExact(long x, long y) {
 841         long r = x + y;
 842         // HD 2-12 Overflow iff both arguments have the opposite sign of the result
 843         if (((x ^ r) & (y ^ r)) < 0) {
 844             throw new ArithmeticException("long overflow");
 845         }
 846         return r;
 847     }
 848 
 849     /**
 850      * Returns the difference of the arguments,
 851      * throwing an exception if the result overflows an {@code int}.
 852      *
 853      * @param x the first value
 854      * @param y the second value to subtract from the first
 855      * @return the result
 856      * @throws ArithmeticException if the result overflows an int
 857      * @since 1.8
 858      */
 859     @HotSpotIntrinsicCandidate
 860     public static int subtractExact(int x, int y) {
 861         int r = x - y;
 862         // HD 2-12 Overflow iff the arguments have different signs and
 863         // the sign of the result is different than the sign of x
 864         if (((x ^ y) & (x ^ r)) < 0) {
 865             throw new ArithmeticException("integer overflow");
 866         }
 867         return r;
 868     }
 869 
 870     /**
 871      * Returns the difference of the arguments,
 872      * throwing an exception if the result overflows a {@code long}.
 873      *
 874      * @param x the first value
 875      * @param y the second value to subtract from the first
 876      * @return the result
 877      * @throws ArithmeticException if the result overflows a long
 878      * @since 1.8
 879      */
 880     @HotSpotIntrinsicCandidate
 881     public static long subtractExact(long x, long y) {
 882         long r = x - y;
 883         // HD 2-12 Overflow iff the arguments have different signs and
 884         // the sign of the result is different than the sign of x
 885         if (((x ^ y) & (x ^ r)) < 0) {
 886             throw new ArithmeticException("long overflow");
 887         }
 888         return r;
 889     }
 890 
 891     /**
 892      * Returns the product of the arguments,
 893      * throwing an exception if the result overflows an {@code int}.
 894      *
 895      * @param x the first value
 896      * @param y the second value
 897      * @return the result
 898      * @throws ArithmeticException if the result overflows an int
 899      * @since 1.8
 900      */
 901     @HotSpotIntrinsicCandidate
 902     public static int multiplyExact(int x, int y) {
 903         long r = (long)x * (long)y;
 904         if ((int)r != r) {
 905             throw new ArithmeticException("integer overflow");
 906         }
 907         return (int)r;
 908     }
 909 
 910     /**
 911      * Returns the product of the arguments,
 912      * throwing an exception if the result overflows a {@code long}.
 913      *
 914      * @param x the first value
 915      * @param y the second value
 916      * @return the result
 917      * @throws ArithmeticException if the result overflows a long
 918      * @since 1.8
 919      */
 920     @HotSpotIntrinsicCandidate
 921     public static long multiplyExact(long x, long y) {
 922         long r = x * y;
 923         long ax = Math.abs(x);
 924         long ay = Math.abs(y);
 925         if (((ax | ay) >>> 31 != 0)) {
 926             // Some bits greater than 2^31 that might cause overflow
 927             // Check the result using the divide operator
 928             // and check for the special case of Long.MIN_VALUE * -1
 929            if (((y != 0) && (r / y != x)) ||
 930                (x == Long.MIN_VALUE && y == -1)) {
 931                 throw new ArithmeticException("long overflow");
 932             }
 933         }
 934         return r;
 935     }
 936 
 937     /**
 938      * Returns the argument incremented by one, throwing an exception if the
 939      * result overflows an {@code int}.
 940      *
 941      * @param a the value to increment
 942      * @return the result
 943      * @throws ArithmeticException if the result overflows an int
 944      * @since 1.8
 945      */
 946     @HotSpotIntrinsicCandidate
 947     public static int incrementExact(int a) {
 948         if (a == Integer.MAX_VALUE) {
 949             throw new ArithmeticException("integer overflow");
 950         }
 951 
 952         return a + 1;
 953     }
 954 
 955     /**
 956      * Returns the argument incremented by one, throwing an exception if the
 957      * result overflows a {@code long}.
 958      *
 959      * @param a the value to increment
 960      * @return the result
 961      * @throws ArithmeticException if the result overflows a long
 962      * @since 1.8
 963      */
 964     @HotSpotIntrinsicCandidate
 965     public static long incrementExact(long a) {
 966         if (a == Long.MAX_VALUE) {
 967             throw new ArithmeticException("long overflow");
 968         }
 969 
 970         return a + 1L;
 971     }
 972 
 973     /**
 974      * Returns the argument decremented by one, throwing an exception if the
 975      * result overflows an {@code int}.
 976      *
 977      * @param a the value to decrement
 978      * @return the result
 979      * @throws ArithmeticException if the result overflows an int
 980      * @since 1.8
 981      */
 982     @HotSpotIntrinsicCandidate
 983     public static int decrementExact(int a) {
 984         if (a == Integer.MIN_VALUE) {
 985             throw new ArithmeticException("integer overflow");
 986         }
 987 
 988         return a - 1;
 989     }
 990 
 991     /**
 992      * Returns the argument decremented by one, throwing an exception if the
 993      * result overflows a {@code long}.
 994      *
 995      * @param a the value to decrement
 996      * @return the result
 997      * @throws ArithmeticException if the result overflows a long
 998      * @since 1.8
 999      */
1000     @HotSpotIntrinsicCandidate
1001     public static long decrementExact(long a) {
1002         if (a == Long.MIN_VALUE) {
1003             throw new ArithmeticException("long overflow");
1004         }
1005 
1006         return a - 1L;
1007     }
1008 
1009     /**
1010      * Returns the negation of the argument, throwing an exception if the
1011      * result overflows an {@code int}.
1012      *
1013      * @param a the value to negate
1014      * @return the result
1015      * @throws ArithmeticException if the result overflows an int
1016      * @since 1.8
1017      */
1018     @HotSpotIntrinsicCandidate
1019     public static int negateExact(int a) {
1020         if (a == Integer.MIN_VALUE) {
1021             throw new ArithmeticException("integer overflow");
1022         }
1023 
1024         return -a;
1025     }
1026 
1027     /**
1028      * Returns the negation of the argument, throwing an exception if the
1029      * result overflows a {@code long}.
1030      *
1031      * @param a the value to negate
1032      * @return the result
1033      * @throws ArithmeticException if the result overflows a long
1034      * @since 1.8
1035      */
1036     @HotSpotIntrinsicCandidate
1037     public static long negateExact(long a) {
1038         if (a == Long.MIN_VALUE) {
1039             throw new ArithmeticException("long overflow");
1040         }
1041 
1042         return -a;
1043     }
1044 
1045     /**
1046      * Returns the value of the {@code long} argument;
1047      * throwing an exception if the value overflows an {@code int}.
1048      *
1049      * @param value the long value
1050      * @return the argument as an int
1051      * @throws ArithmeticException if the {@code argument} overflows an int
1052      * @since 1.8
1053      */
1054     public static int toIntExact(long value) {
1055         if ((int)value != value) {
1056             throw new ArithmeticException("integer overflow");


1261      */
1262     public static float abs(float a) {
1263         return (a <= 0.0F) ? 0.0F - a : a;
1264     }
1265 
1266     /**
1267      * Returns the absolute value of a {@code double} value.
1268      * If the argument is not negative, the argument is returned.
1269      * If the argument is negative, the negation of the argument is returned.
1270      * Special cases:
1271      * <ul><li>If the argument is positive zero or negative zero, the result
1272      * is positive zero.
1273      * <li>If the argument is infinite, the result is positive infinity.
1274      * <li>If the argument is NaN, the result is NaN.</ul>
1275      * In other words, the result is the same as the value of the expression:
1276      * <p>{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)}
1277      *
1278      * @param   a   the argument whose absolute value is to be determined
1279      * @return  the absolute value of the argument.
1280      */
1281     @HotSpotIntrinsicCandidate
1282     public static double abs(double a) {
1283         return (a <= 0.0D) ? 0.0D - a : a;
1284     }
1285 
1286     /**
1287      * Returns the greater of two {@code int} values. That is, the
1288      * result is the argument closer to the value of
1289      * {@link Integer#MAX_VALUE}. If the arguments have the same value,
1290      * the result is that same value.
1291      *
1292      * @param   a   an argument.
1293      * @param   b   another argument.
1294      * @return  the larger of {@code a} and {@code b}.
1295      */
1296     @HotSpotIntrinsicCandidate
1297     public static int max(int a, int b) {
1298         return (a >= b) ? a : b;
1299     }
1300 
1301     /**
1302      * Returns the greater of two {@code long} values. That is, the
1303      * result is the argument closer to the value of
1304      * {@link Long#MAX_VALUE}. If the arguments have the same value,
1305      * the result is that same value.
1306      *
1307      * @param   a   an argument.
1308      * @param   b   another argument.
1309      * @return  the larger of {@code a} and {@code b}.
1310      */
1311     public static long max(long a, long b) {
1312         return (a >= b) ? a : b;
1313     }
1314 
1315     // Use raw bit-wise conversions on guaranteed non-NaN arguments.
1316     private static long negativeZeroFloatBits  = Float.floatToRawIntBits(-0.0f);


1361             return a;   // a is NaN
1362         if ((a == 0.0d) &&
1363             (b == 0.0d) &&
1364             (Double.doubleToRawLongBits(a) == negativeZeroDoubleBits)) {
1365             // Raw conversion ok since NaN can't map to -0.0.
1366             return b;
1367         }
1368         return (a >= b) ? a : b;
1369     }
1370 
1371     /**
1372      * Returns the smaller of two {@code int} values. That is,
1373      * the result the argument closer to the value of
1374      * {@link Integer#MIN_VALUE}.  If the arguments have the same
1375      * value, the result is that same value.
1376      *
1377      * @param   a   an argument.
1378      * @param   b   another argument.
1379      * @return  the smaller of {@code a} and {@code b}.
1380      */
1381     @HotSpotIntrinsicCandidate
1382     public static int min(int a, int b) {
1383         return (a <= b) ? a : b;
1384     }
1385 
1386     /**
1387      * Returns the smaller of two {@code long} values. That is,
1388      * the result is the argument closer to the value of
1389      * {@link Long#MIN_VALUE}. If the arguments have the same
1390      * value, the result is that same value.
1391      *
1392      * @param   a   an argument.
1393      * @param   b   another argument.
1394      * @return  the smaller of {@code a} and {@code b}.
1395      */
1396     public static long min(long a, long b) {
1397         return (a <= b) ? a : b;
1398     }
1399 
1400     /**
1401      * Returns the smaller of two {@code float} values.  That is,


src/java.base/share/classes/java/lang/Math.java
Index Unified diffs Context diffs Sdiffs Patch New Old Previous File Next File