1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 1994, 2017, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27 package java.lang; 28 29 import dalvik.annotation.optimization.CriticalNative; 30 import java.util.Random; 31 32 import sun.misc.FloatConsts; 33 import sun.misc.DoubleConsts; 34 35 // Android-note: Document that the results from Math are based on libm's behavior. 36 // For performance, Android implements many of the methods in this class in terms of the underlying 37 // OS's libm functions. libm has well-defined behavior for special cases. Where known these are 38 // marked with the tag above and the documentation has been modified as needed. 39 /** 40 * The class {@code Math} contains methods for performing basic 41 * numeric operations such as the elementary exponential, logarithm, 42 * square root, and trigonometric functions. 43 * 44 * <p>Unlike some of the numeric methods of class 45 * {@code StrictMath}, all implementations of the equivalent 46 * functions of class {@code Math} are not defined to return the 47 * bit-for-bit same results. This relaxation permits 48 * better-performing implementations where strict reproducibility is 49 * not required. 50 * 51 * <p>By default many of the {@code Math} methods simply call 52 * the equivalent method in {@code StrictMath} for their 53 * implementation. Code generators are encouraged to use 54 * platform-specific native libraries or microprocessor instructions, 55 * where available, to provide higher-performance implementations of 56 * {@code Math} methods. Such higher-performance 57 * implementations still must conform to the specification for 58 * {@code Math}. 59 * 60 * <p>The quality of implementation specifications concern two 61 * properties, accuracy of the returned result and monotonicity of the 62 * method. Accuracy of the floating-point {@code Math} methods is 63 * measured in terms of <i>ulps</i>, units in the last place. For a 64 * given floating-point format, an {@linkplain #ulp(double) ulp} of a 65 * specific real number value is the distance between the two 66 * floating-point values bracketing that numerical value. When 67 * discussing the accuracy of a method as a whole rather than at a 68 * specific argument, the number of ulps cited is for the worst-case 69 * error at any argument. If a method always has an error less than 70 * 0.5 ulps, the method always returns the floating-point number 71 * nearest the exact result; such a method is <i>correctly 72 * rounded</i>. A correctly rounded method is generally the best a 73 * floating-point approximation can be; however, it is impractical for 74 * many floating-point methods to be correctly rounded. Instead, for 75 * the {@code Math} class, a larger error bound of 1 or 2 ulps is 76 * allowed for certain methods. Informally, with a 1 ulp error bound, 77 * when the exact result is a representable number, the exact result 78 * should be returned as the computed result; otherwise, either of the 79 * two floating-point values which bracket the exact result may be 80 * returned. For exact results large in magnitude, one of the 81 * endpoints of the bracket may be infinite. Besides accuracy at 82 * individual arguments, maintaining proper relations between the 83 * method at different arguments is also important. Therefore, most 84 * methods with more than 0.5 ulp errors are required to be 85 * <i>semi-monotonic</i>: whenever the mathematical function is 86 * non-decreasing, so is the floating-point approximation, likewise, 87 * whenever the mathematical function is non-increasing, so is the 88 * floating-point approximation. Not all approximations that have 1 89 * ulp accuracy will automatically meet the monotonicity requirements. 90 * 91 * <p> 92 * The platform uses signed two's complement integer arithmetic with 93 * int and long primitive types. The developer should choose 94 * the primitive type to ensure that arithmetic operations consistently 95 * produce correct results, which in some cases means the operations 96 * will not overflow the range of values of the computation. 97 * The best practice is to choose the primitive type and algorithm to avoid 98 * overflow. In cases where the size is {@code int} or {@code long} and 99 * overflow errors need to be detected, the methods {@code addExact}, 100 * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact} 101 * throw an {@code ArithmeticException} when the results overflow. 102 * For other arithmetic operations such as divide, absolute value, 103 * increment by one, decrement by one, and negation, overflow occurs only with 104 * a specific minimum or maximum value and should be checked against 105 * the minimum or maximum as appropriate. 106 * 107 * @author unascribed 108 * @author Joseph D. Darcy 109 * @since 1.0 110 */ 111 112 public final class Math { 113 114 // Android-changed: Numerous methods in this class are re-implemented in native for performance. 115 // Those methods are also annotated @CriticalNative. 116 117 /** 118 * Don't let anyone instantiate this class. 119 */ Math()120 private Math() {} 121 122 /** 123 * The {@code double} value that is closer than any other to 124 * <i>e</i>, the base of the natural logarithms. 125 */ 126 public static final double E = 2.7182818284590452354; 127 128 /** 129 * The {@code double} value that is closer than any other to 130 * <i>pi</i>, the ratio of the circumference of a circle to its 131 * diameter. 132 */ 133 public static final double PI = 3.14159265358979323846; 134 135 /** 136 * Constant by which to multiply an angular value in degrees to obtain an 137 * angular value in radians. 138 */ 139 private static final double DEGREES_TO_RADIANS = 0.017453292519943295; 140 141 /** 142 * Constant by which to multiply an angular value in radians to obtain an 143 * angular value in degrees. 144 */ 145 private static final double RADIANS_TO_DEGREES = 57.29577951308232; 146 147 /** 148 * Returns the trigonometric sine of an angle. Special cases: 149 * <ul><li>If the argument is NaN or an infinity, then the 150 * result is NaN. 151 * <li>If the argument is zero, then the result is a zero with the 152 * same sign as the argument.</ul> 153 * 154 * <p>The computed result must be within 1 ulp of the exact result. 155 * Results must be semi-monotonic. 156 * 157 * @param a an angle, in radians. 158 * @return the sine of the argument. 159 */ 160 @CriticalNative sin(double a)161 public static native double sin(double a); 162 163 /** 164 * Returns the trigonometric cosine of an angle. Special cases: 165 * <ul><li>If the argument is NaN or an infinity, then the 166 * result is NaN.</ul> 167 * 168 * <p>The computed result must be within 1 ulp of the exact result. 169 * Results must be semi-monotonic. 170 * 171 * @param a an angle, in radians. 172 * @return the cosine of the argument. 173 */ 174 @CriticalNative cos(double a)175 public static native double cos(double a); 176 177 /** 178 * Returns the trigonometric tangent of an angle. Special cases: 179 * <ul><li>If the argument is NaN or an infinity, then the result 180 * is NaN. 181 * <li>If the argument is zero, then the result is a zero with the 182 * same sign as the argument.</ul> 183 * 184 * <p>The computed result must be within 1 ulp of the exact result. 185 * Results must be semi-monotonic. 186 * 187 * @param a an angle, in radians. 188 * @return the tangent of the argument. 189 */ 190 @CriticalNative tan(double a)191 public static native double tan(double a); 192 193 /** 194 * Returns the arc sine of a value; the returned angle is in the 195 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases: 196 * <ul><li>If the argument is NaN or its absolute value is greater 197 * than 1, then the result is NaN. 198 * <li>If the argument is zero, then the result is a zero with the 199 * same sign as the argument.</ul> 200 * 201 * <p>The computed result must be within 1 ulp of the exact result. 202 * Results must be semi-monotonic. 203 * 204 * @param a the value whose arc sine is to be returned. 205 * @return the arc sine of the argument. 206 */ 207 @CriticalNative asin(double a)208 public static native double asin(double a); 209 210 /** 211 * Returns the arc cosine of a value; the returned angle is in the 212 * range 0.0 through <i>pi</i>. Special case: 213 * <ul><li>If the argument is NaN or its absolute value is greater 214 * than 1, then the result is NaN.</ul> 215 * 216 * <p>The computed result must be within 1 ulp of the exact result. 217 * Results must be semi-monotonic. 218 * 219 * @param a the value whose arc cosine is to be returned. 220 * @return the arc cosine of the argument. 221 */ 222 @CriticalNative acos(double a)223 public static native double acos(double a); 224 225 /** 226 * Returns the arc tangent of a value; the returned angle is in the 227 * range -<i>pi</i>/2 through <i>pi</i>/2. Special cases: 228 * <ul><li>If the argument is NaN, then the result is NaN. 229 * <li>If the argument is zero, then the result is a zero with the 230 * same sign as the argument.</ul> 231 * 232 * <p>The computed result must be within 1 ulp of the exact result. 233 * Results must be semi-monotonic. 234 * 235 * @param a the value whose arc tangent is to be returned. 236 * @return the arc tangent of the argument. 237 */ 238 @CriticalNative atan(double a)239 public static native double atan(double a); 240 241 /** 242 * Converts an angle measured in degrees to an approximately 243 * equivalent angle measured in radians. The conversion from 244 * degrees to radians is generally inexact. 245 * 246 * @param angdeg an angle, in degrees 247 * @return the measurement of the angle {@code angdeg} 248 * in radians. 249 * @since 1.2 250 */ toRadians(double angdeg)251 public static double toRadians(double angdeg) { 252 return angdeg * DEGREES_TO_RADIANS; 253 } 254 255 /** 256 * Converts an angle measured in radians to an approximately 257 * equivalent angle measured in degrees. The conversion from 258 * radians to degrees is generally inexact; users should 259 * <i>not</i> expect {@code cos(toRadians(90.0))} to exactly 260 * equal {@code 0.0}. 261 * 262 * @param angrad an angle, in radians 263 * @return the measurement of the angle {@code angrad} 264 * in degrees. 265 * @since 1.2 266 */ toDegrees(double angrad)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 @CriticalNative exp(double a)288 public static native double exp(double a); 289 290 /** 291 * Returns the natural logarithm (base <i>e</i>) of a {@code double} 292 * value. Special cases: 293 * <ul><li>If the argument is NaN or less than zero, then the result 294 * is NaN. 295 * <li>If the argument is positive infinity, then the result is 296 * positive infinity. 297 * <li>If the argument is positive zero or negative zero, then the 298 * result is negative infinity.</ul> 299 * 300 * <p>The computed result must be within 1 ulp of the exact result. 301 * Results must be semi-monotonic. 302 * 303 * @param a a value 304 * @return the value ln {@code a}, the natural logarithm of 305 * {@code a}. 306 */ 307 @CriticalNative log(double a)308 public static native double log(double a); 309 310 /** 311 * Returns the base 10 logarithm of a {@code double} value. 312 * Special cases: 313 * 314 * <ul><li>If the argument is NaN or less than zero, then the result 315 * is NaN. 316 * <li>If the argument is positive infinity, then the result is 317 * positive infinity. 318 * <li>If the argument is positive zero or negative zero, then the 319 * result is negative infinity. 320 * <li> If the argument is equal to 10<sup><i>n</i></sup> for 321 * integer <i>n</i>, then the result is <i>n</i>. 322 * </ul> 323 * 324 * <p>The computed result must be within 1 ulp of the exact result. 325 * Results must be semi-monotonic. 326 * 327 * @param a a value 328 * @return the base 10 logarithm of {@code a}. 329 * @since 1.5 330 */ 331 @CriticalNative log10(double a)332 public static native double log10(double a); 333 334 /** 335 * Returns the correctly rounded positive square root of a 336 * {@code double} value. 337 * Special cases: 338 * <ul><li>If the argument is NaN or less than zero, then the result 339 * is NaN. 340 * <li>If the argument is positive infinity, then the result is positive 341 * infinity. 342 * <li>If the argument is positive zero or negative zero, then the 343 * result is the same as the argument.</ul> 344 * Otherwise, the result is the {@code double} value closest to 345 * the true mathematical square root of the argument value. 346 * 347 * @param a a value. 348 * @return the positive square root of {@code a}. 349 * If the argument is NaN or less than zero, the result is NaN. 350 */ 351 @CriticalNative sqrt(double a)352 public static native double sqrt(double a); 353 354 355 /** 356 * Returns the cube root of a {@code double} value. For 357 * positive finite {@code x}, {@code cbrt(-x) == 358 * -cbrt(x)}; that is, the cube root of a negative value is 359 * the negative of the cube root of that value's magnitude. 360 * 361 * Special cases: 362 * 363 * <ul> 364 * 365 * <li>If the argument is NaN, then the result is NaN. 366 * 367 * <li>If the argument is infinite, then the result is an infinity 368 * with the same sign as the argument. 369 * 370 * <li>If the argument is zero, then the result is a zero with the 371 * same sign as the argument. 372 * 373 * </ul> 374 * 375 * <p>The computed result must be within 1 ulp of the exact result. 376 * 377 * @param a a value. 378 * @return the cube root of {@code a}. 379 * @since 1.5 380 */ 381 @CriticalNative cbrt(double a)382 public static native double cbrt(double a); 383 384 /** 385 * Computes the remainder operation on two arguments as prescribed 386 * by the IEEE 754 standard. 387 * The remainder value is mathematically equal to 388 * <code>f1 - f2</code> × <i>n</i>, 389 * where <i>n</i> is the mathematical integer closest to the exact 390 * mathematical value of the quotient {@code f1/f2}, and if two 391 * mathematical integers are equally close to {@code f1/f2}, 392 * then <i>n</i> is the integer that is even. If the remainder is 393 * zero, its sign is the same as the sign of the first argument. 394 * Special cases: 395 * <ul><li>If either argument is NaN, or the first argument is infinite, 396 * or the second argument is positive zero or negative zero, then the 397 * result is NaN. 398 * <li>If the first argument is finite and the second argument is 399 * infinite, then the result is the same as the first argument.</ul> 400 * 401 * @param f1 the dividend. 402 * @param f2 the divisor. 403 * @return the remainder when {@code f1} is divided by 404 * {@code f2}. 405 */ 406 @CriticalNative IEEEremainder(double f1, double f2)407 public static native double IEEEremainder(double f1, double f2); 408 409 /** 410 * Returns the smallest (closest to negative infinity) 411 * {@code double} value that is greater than or equal to the 412 * argument and is equal to a mathematical integer. Special cases: 413 * <ul><li>If the argument value is already equal to a 414 * mathematical integer, then the result is the same as the 415 * argument. <li>If the argument is NaN or an infinity or 416 * positive zero or negative zero, then the result is the same as 417 * the argument. <li>If the argument value is less than zero but 418 * greater than -1.0, then the result is negative zero.</ul> Note 419 * that the value of {@code Math.ceil(x)} is exactly the 420 * value of {@code -Math.floor(-x)}. 421 * 422 * 423 * @param a a value. 424 * @return the smallest (closest to negative infinity) 425 * floating-point value that is greater than or equal to 426 * the argument and is equal to a mathematical integer. 427 */ 428 @CriticalNative ceil(double a)429 public static native double ceil(double a); 430 431 /** 432 * Returns the largest (closest to positive infinity) 433 * {@code double} value that is less than or equal to the 434 * argument and is equal to a mathematical integer. Special cases: 435 * <ul><li>If the argument value is already equal to a 436 * mathematical integer, then the result is the same as the 437 * argument. <li>If the argument is NaN or an infinity or 438 * positive zero or negative zero, then the result is the same as 439 * the argument.</ul> 440 * 441 * @param a a value. 442 * @return the largest (closest to positive infinity) 443 * floating-point value that less than or equal to the argument 444 * and is equal to a mathematical integer. 445 */ 446 @CriticalNative floor(double a)447 public static native double floor(double a); 448 449 /** 450 * Returns the {@code double} value that is closest in value 451 * to the argument and is equal to a mathematical integer. If two 452 * {@code double} values that are mathematical integers are 453 * equally close, the result is the integer value that is 454 * even. Special cases: 455 * <ul><li>If the argument value is already equal to a mathematical 456 * integer, then the result is the same as the argument. 457 * <li>If the argument is NaN or an infinity or positive zero or negative 458 * zero, then the result is the same as the argument.</ul> 459 * 460 * @param a a {@code double} value. 461 * @return the closest floating-point value to {@code a} that is 462 * equal to a mathematical integer. 463 */ 464 @CriticalNative rint(double a)465 public static native double rint(double a); 466 467 /** 468 * Returns the angle <i>theta</i> from the conversion of rectangular 469 * coordinates ({@code x}, {@code y}) to polar 470 * coordinates (r, <i>theta</i>). 471 * This method computes the phase <i>theta</i> by computing an arc tangent 472 * of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special 473 * cases: 474 * <ul><li>If either argument is NaN, then the result is NaN. 475 * <li>If the first argument is positive zero and the second argument 476 * is positive, or the first argument is positive and finite and the 477 * second argument is positive infinity, then the result is positive 478 * zero. 479 * <li>If the first argument is negative zero and the second argument 480 * is positive, or the first argument is negative and finite and the 481 * second argument is positive infinity, then the result is negative zero. 482 * <li>If the first argument is positive zero and the second argument 483 * is negative, or the first argument is positive and finite and the 484 * second argument is negative infinity, then the result is the 485 * {@code double} value closest to <i>pi</i>. 486 * <li>If the first argument is negative zero and the second argument 487 * is negative, or the first argument is negative and finite and the 488 * second argument is negative infinity, then the result is the 489 * {@code double} value closest to -<i>pi</i>. 490 * <li>If the first argument is positive and the second argument is 491 * positive zero or negative zero, or the first argument is positive 492 * infinity and the second argument is finite, then the result is the 493 * {@code double} value closest to <i>pi</i>/2. 494 * <li>If the first argument is negative and the second argument is 495 * positive zero or negative zero, or the first argument is negative 496 * infinity and the second argument is finite, then the result is the 497 * {@code double} value closest to -<i>pi</i>/2. 498 * <li>If both arguments are positive infinity, then the result is the 499 * {@code double} value closest to <i>pi</i>/4. 500 * <li>If the first argument is positive infinity and the second argument 501 * is negative infinity, then the result is the {@code double} 502 * value closest to 3*<i>pi</i>/4. 503 * <li>If the first argument is negative infinity and the second argument 504 * is positive infinity, then the result is the {@code double} value 505 * closest to -<i>pi</i>/4. 506 * <li>If both arguments are negative infinity, then the result is the 507 * {@code double} value closest to -3*<i>pi</i>/4.</ul> 508 * 509 * <p>The computed result must be within 2 ulps of the exact result. 510 * Results must be semi-monotonic. 511 * 512 * @param y the ordinate coordinate 513 * @param x the abscissa coordinate 514 * @return the <i>theta</i> component of the point 515 * (<i>r</i>, <i>theta</i>) 516 * in polar coordinates that corresponds to the point 517 * (<i>x</i>, <i>y</i>) in Cartesian coordinates. 518 */ 519 @CriticalNative atan2(double y, double x)520 public static native double atan2(double y, double x); 521 522 // Android-changed: Document that the results from Math are based on libm's behavior. 523 // The cases known to differ with libm's pow(): 524 // If the first argument is 1.0 then result is always 1.0 (not NaN). 525 // If the first argument is -1.0 and the second argument is infinite, the result is 1.0 (not 526 // NaN). 527 /** 528 * Returns the value of the first argument raised to the power of the 529 * second argument. Special cases: 530 * 531 * <ul><li>If the second argument is positive or negative zero, then the 532 * result is 1.0. 533 * <li>If the second argument is 1.0, then the result is the same as the 534 * first argument. 535 * <li>If the first argument is 1.0, then the result is 1.0. 536 * <li>If the second argument is NaN, then the result is NaN except where the first argument is 537 * 1.0. 538 * <li>If the first argument is NaN and the second argument is nonzero, 539 * then the result is NaN. 540 * 541 * <li>If 542 * <ul> 543 * <li>the absolute value of the first argument is greater than 1 544 * and the second argument is positive infinity, or 545 * <li>the absolute value of the first argument is less than 1 and 546 * the second argument is negative infinity, 547 * </ul> 548 * then the result is positive infinity. 549 * 550 * <li>If 551 * <ul> 552 * <li>the absolute value of the first argument is greater than 1 and 553 * the second argument is negative infinity, or 554 * <li>the absolute value of the 555 * first argument is less than 1 and the second argument is positive 556 * infinity, 557 * </ul> 558 * then the result is positive zero. 559 * 560 * <li>If the absolute value of the first argument equals 1 and the 561 * second argument is infinite, then the result is 1.0. 562 * 563 * <li>If 564 * <ul> 565 * <li>the first argument is positive zero and the second argument 566 * is greater than zero, or 567 * <li>the first argument is positive infinity and the second 568 * argument is less than zero, 569 * </ul> 570 * then the result is positive zero. 571 * 572 * <li>If 573 * <ul> 574 * <li>the first argument is positive zero and the second argument 575 * is less than zero, or 576 * <li>the first argument is positive infinity and the second 577 * argument is greater than zero, 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 greater than zero but not a finite odd integer, or 585 * <li>the first argument is negative infinity and the second 586 * argument is less than zero but not a finite odd integer, 587 * </ul> 588 * then the result is positive zero. 589 * 590 * <li>If 591 * <ul> 592 * <li>the first argument is negative zero and the second argument 593 * is a positive finite odd integer, or 594 * <li>the first argument is negative infinity and the second 595 * argument is a negative finite odd integer, 596 * </ul> 597 * then the result is negative zero. 598 * 599 * <li>If 600 * <ul> 601 * <li>the first argument is negative zero and the second argument 602 * is less than zero but not a finite odd integer, or 603 * <li>the first argument is negative infinity and the second 604 * argument is greater than zero but not a finite odd integer, 605 * </ul> 606 * then the result is positive infinity. 607 * 608 * <li>If 609 * <ul> 610 * <li>the first argument is negative zero and the second argument 611 * is a negative finite odd integer, or 612 * <li>the first argument is negative infinity and the second 613 * argument is a positive finite odd integer, 614 * </ul> 615 * then the result is negative infinity. 616 * 617 * <li>If the first argument is finite and less than zero 618 * <ul> 619 * <li> if the second argument is a finite even integer, the 620 * result is equal to the result of raising the absolute value of 621 * the first argument to the power of the second argument 622 * 623 * <li>if the second argument is a finite odd integer, the result 624 * is equal to the negative of the result of raising the absolute 625 * value of the first argument to the power of the second 626 * argument 627 * 628 * <li>if the second argument is finite and not an integer, then 629 * the result is NaN. 630 * </ul> 631 * 632 * <li>If both arguments are integers, then the result is exactly equal 633 * to the mathematical result of raising the first argument to the power 634 * of the second argument if that result can in fact be represented 635 * exactly as a {@code double} value.</ul> 636 * 637 * <p>(In the foregoing descriptions, a floating-point value is 638 * considered to be an integer if and only if it is finite and a 639 * fixed point of the method {@link #ceil ceil} or, 640 * equivalently, a fixed point of the method {@link #floor 641 * floor}. A value is a fixed point of a one-argument 642 * method if and only if the result of applying the method to the 643 * value is equal to the value.) 644 * 645 * <p>The computed result must be within 1 ulp of the exact result. 646 * Results must be semi-monotonic. 647 * 648 * @param a the base. 649 * @param b the exponent. 650 * @return the value {@code a}<sup>{@code b}</sup>. 651 */ 652 @CriticalNative pow(double a, double b)653 public static native double pow(double a, double b); 654 655 /** 656 * Returns the closest {@code int} to the argument, with ties 657 * rounding to positive infinity. 658 * 659 * <p> 660 * 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 Integer.MIN_VALUE}, the result is 664 * equal to the value of {@code Integer.MIN_VALUE}. 665 * <li>If the argument is positive infinity or any value greater than or 666 * equal to the value of {@code Integer.MAX_VALUE}, the result is 667 * equal to the value of {@code Integer.MAX_VALUE}.</ul> 668 * 669 * @param a a floating-point value to be rounded to an integer. 670 * @return the value of the argument rounded to the nearest 671 * {@code int} value. 672 * @see java.lang.Integer#MAX_VALUE 673 * @see java.lang.Integer#MIN_VALUE 674 */ round(float a)675 public static int round(float a) { 676 int intBits = Float.floatToRawIntBits(a); 677 int biasedExp = (intBits & FloatConsts.EXP_BIT_MASK) 678 >> (FloatConsts.SIGNIFICAND_WIDTH - 1); 679 int shift = (FloatConsts.SIGNIFICAND_WIDTH - 2 680 + FloatConsts.EXP_BIAS) - biasedExp; 681 if ((shift & -32) == 0) { // shift >= 0 && shift < 32 682 // a is a finite number such that pow(2,-32) <= ulp(a) < 1 683 int r = ((intBits & FloatConsts.SIGNIF_BIT_MASK) 684 | (FloatConsts.SIGNIF_BIT_MASK + 1)); 685 if (intBits < 0) { 686 r = -r; 687 } 688 // In the comments below each Java expression evaluates to the value 689 // the corresponding mathematical expression: 690 // (r) evaluates to a / ulp(a) 691 // (r >> shift) evaluates to floor(a * 2) 692 // ((r >> shift) + 1) evaluates to floor((a + 1/2) * 2) 693 // (((r >> shift) + 1) >> 1) evaluates to floor(a + 1/2) 694 return ((r >> shift) + 1) >> 1; 695 } else { 696 // a is either 697 // - a finite number with abs(a) < exp(2,FloatConsts.SIGNIFICAND_WIDTH-32) < 1/2 698 // - a finite number with ulp(a) >= 1 and hence a is a mathematical integer 699 // - an infinity or NaN 700 return (int) a; 701 } 702 } 703 704 /** 705 * Returns the closest {@code long} to the argument, with ties 706 * rounding to positive infinity. 707 * 708 * <p>Special cases: 709 * <ul><li>If the argument is NaN, the result is 0. 710 * <li>If the argument is negative infinity or any value less than or 711 * equal to the value of {@code Long.MIN_VALUE}, the result is 712 * equal to the value of {@code Long.MIN_VALUE}. 713 * <li>If the argument is positive infinity or any value greater than or 714 * equal to the value of {@code Long.MAX_VALUE}, the result is 715 * equal to the value of {@code Long.MAX_VALUE}.</ul> 716 * 717 * @param a a floating-point value to be rounded to a 718 * {@code long}. 719 * @return the value of the argument rounded to the nearest 720 * {@code long} value. 721 * @see java.lang.Long#MAX_VALUE 722 * @see java.lang.Long#MIN_VALUE 723 */ round(double a)724 public static long round(double a) { 725 long longBits = Double.doubleToRawLongBits(a); 726 long biasedExp = (longBits & DoubleConsts.EXP_BIT_MASK) 727 >> (DoubleConsts.SIGNIFICAND_WIDTH - 1); 728 long shift = (DoubleConsts.SIGNIFICAND_WIDTH - 2 729 + DoubleConsts.EXP_BIAS) - biasedExp; 730 if ((shift & -64) == 0) { // shift >= 0 && shift < 64 731 // a is a finite number such that pow(2,-64) <= ulp(a) < 1 732 long r = ((longBits & DoubleConsts.SIGNIF_BIT_MASK) 733 | (DoubleConsts.SIGNIF_BIT_MASK + 1)); 734 if (longBits < 0) { 735 r = -r; 736 } 737 // In the comments below each Java expression evaluates to the value 738 // the corresponding mathematical expression: 739 // (r) evaluates to a / ulp(a) 740 // (r >> shift) evaluates to floor(a * 2) 741 // ((r >> shift) + 1) evaluates to floor((a + 1/2) * 2) 742 // (((r >> shift) + 1) >> 1) evaluates to floor(a + 1/2) 743 return ((r >> shift) + 1) >> 1; 744 } else { 745 // a is either 746 // - a finite number with abs(a) < exp(2,DoubleConsts.SIGNIFICAND_WIDTH-64) < 1/2 747 // - a finite number with ulp(a) >= 1 and hence a is a mathematical integer 748 // - an infinity or NaN 749 return (long) a; 750 } 751 } 752 753 private static final class RandomNumberGeneratorHolder { 754 static final Random randomNumberGenerator = new Random(); 755 } 756 757 /** 758 * Returns a {@code double} value with a positive sign, greater 759 * than or equal to {@code 0.0} and less than {@code 1.0}. 760 * Returned values are chosen pseudorandomly with (approximately) 761 * uniform distribution from that range. 762 * 763 * <p>When this method is first called, it creates a single new 764 * pseudorandom-number generator, exactly as if by the expression 765 * 766 * <blockquote>{@code new java.util.Random()}</blockquote> 767 * 768 * This new pseudorandom-number generator is used thereafter for 769 * all calls to this method and is used nowhere else. 770 * 771 * <p>This method is properly synchronized to allow correct use by 772 * more than one thread. However, if many threads need to generate 773 * pseudorandom numbers at a great rate, it may reduce contention 774 * for each thread to have its own pseudorandom-number generator. 775 * 776 * @return a pseudorandom {@code double} greater than or equal 777 * to {@code 0.0} and less than {@code 1.0}. 778 * @see Random#nextDouble() 779 */ random()780 public static double random() { 781 return RandomNumberGeneratorHolder.randomNumberGenerator.nextDouble(); 782 } 783 784 // Android-added: setRandomSeedInternal(long), called after zygote forks. 785 // This allows different processes to have different random seeds. 786 /** 787 * Set the seed for the pseudo random generator used by {@link #random()} 788 * and {@link #randomIntInternal()}. 789 * 790 * @hide for internal use only. 791 */ setRandomSeedInternal(long seed)792 public static void setRandomSeedInternal(long seed) { 793 RandomNumberGeneratorHolder.randomNumberGenerator.setSeed(seed); 794 } 795 796 // Android-added: randomIntInternal() method: like random() but for int. 797 /** 798 * @hide for internal use only. 799 */ randomIntInternal()800 public static int randomIntInternal() { 801 return RandomNumberGeneratorHolder.randomNumberGenerator.nextInt(); 802 } 803 804 // Android-added: randomLongInternal() method: like random() but for long. 805 /** 806 * @hide for internal use only. 807 */ randomLongInternal()808 public static long randomLongInternal() { 809 return RandomNumberGeneratorHolder.randomNumberGenerator.nextLong(); 810 } 811 812 /** 813 * Returns the sum of its arguments, 814 * throwing an exception if the result overflows an {@code int}. 815 * 816 * @param x the first value 817 * @param y the second value 818 * @return the result 819 * @throws ArithmeticException if the result overflows an int 820 * @since 1.8 821 */ addExact(int x, int y)822 public static int addExact(int x, int y) { 823 int r = x + y; 824 // HD 2-12 Overflow iff both arguments have the opposite sign of the result 825 if (((x ^ r) & (y ^ r)) < 0) { 826 throw new ArithmeticException("integer overflow"); 827 } 828 return r; 829 } 830 831 /** 832 * Returns the sum of its arguments, 833 * throwing an exception if the result overflows a {@code long}. 834 * 835 * @param x the first value 836 * @param y the second value 837 * @return the result 838 * @throws ArithmeticException if the result overflows a long 839 * @since 1.8 840 */ addExact(long x, long y)841 public static long addExact(long x, long y) { 842 long r = x + y; 843 // HD 2-12 Overflow iff both arguments have the opposite sign of the result 844 if (((x ^ r) & (y ^ r)) < 0) { 845 throw new ArithmeticException("long overflow"); 846 } 847 return r; 848 } 849 850 /** 851 * Returns the difference of the arguments, 852 * throwing an exception if the result overflows an {@code int}. 853 * 854 * @param x the first value 855 * @param y the second value to subtract from the first 856 * @return the result 857 * @throws ArithmeticException if the result overflows an int 858 * @since 1.8 859 */ subtractExact(int x, int y)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 */ subtractExact(long x, long y)880 public static long subtractExact(long x, long y) { 881 long r = x - y; 882 // HD 2-12 Overflow iff the arguments have different signs and 883 // the sign of the result is different than the sign of x 884 if (((x ^ y) & (x ^ r)) < 0) { 885 throw new ArithmeticException("long overflow"); 886 } 887 return r; 888 } 889 890 /** 891 * Returns the product of the arguments, 892 * throwing an exception if the result overflows an {@code int}. 893 * 894 * @param x the first value 895 * @param y the second value 896 * @return the result 897 * @throws ArithmeticException if the result overflows an int 898 * @since 1.8 899 */ multiplyExact(int x, int y)900 public static int multiplyExact(int x, int y) { 901 long r = (long)x * (long)y; 902 if ((int)r != r) { 903 throw new ArithmeticException("integer overflow"); 904 } 905 return (int)r; 906 } 907 908 /** 909 * Returns the product of the arguments, throwing an exception if the result 910 * overflows a {@code long}. 911 * 912 * @param x the first value 913 * @param y the second value 914 * @return the result 915 * @throws ArithmeticException if the result overflows a long 916 * @since 9 917 */ multiplyExact(long x, int y)918 public static long multiplyExact(long x, int y) { 919 return multiplyExact(x, (long)y); 920 } 921 922 /** 923 * Returns the product of the arguments, 924 * throwing an exception if the result overflows a {@code long}. 925 * 926 * @param x the first value 927 * @param y the second value 928 * @return the result 929 * @throws ArithmeticException if the result overflows a long 930 * @since 1.8 931 */ multiplyExact(long x, long y)932 public static long multiplyExact(long x, long y) { 933 long r = x * y; 934 long ax = Math.abs(x); 935 long ay = Math.abs(y); 936 if (((ax | ay) >>> 31 != 0)) { 937 // Some bits greater than 2^31 that might cause overflow 938 // Check the result using the divide operator 939 // and check for the special case of Long.MIN_VALUE * -1 940 if (((y != 0) && (r / y != x)) || 941 (x == Long.MIN_VALUE && y == -1)) { 942 throw new ArithmeticException("long overflow"); 943 } 944 } 945 return r; 946 } 947 948 /** 949 * Returns the argument incremented by one, throwing an exception if the 950 * result overflows an {@code int}. 951 * 952 * @param a the value to increment 953 * @return the result 954 * @throws ArithmeticException if the result overflows an int 955 * @since 1.8 956 */ incrementExact(int a)957 public static int incrementExact(int a) { 958 if (a == Integer.MAX_VALUE) { 959 throw new ArithmeticException("integer overflow"); 960 } 961 962 return a + 1; 963 } 964 965 /** 966 * Returns the argument incremented by one, throwing an exception if the 967 * result overflows a {@code long}. 968 * 969 * @param a the value to increment 970 * @return the result 971 * @throws ArithmeticException if the result overflows a long 972 * @since 1.8 973 */ incrementExact(long a)974 public static long incrementExact(long a) { 975 if (a == Long.MAX_VALUE) { 976 throw new ArithmeticException("long overflow"); 977 } 978 979 return a + 1L; 980 } 981 982 /** 983 * Returns the argument decremented by one, throwing an exception if the 984 * result overflows an {@code int}. 985 * 986 * @param a the value to decrement 987 * @return the result 988 * @throws ArithmeticException if the result overflows an int 989 * @since 1.8 990 */ decrementExact(int a)991 public static int decrementExact(int a) { 992 if (a == Integer.MIN_VALUE) { 993 throw new ArithmeticException("integer overflow"); 994 } 995 996 return a - 1; 997 } 998 999 /** 1000 * Returns the argument decremented by one, throwing an exception if the 1001 * result overflows a {@code long}. 1002 * 1003 * @param a the value to decrement 1004 * @return the result 1005 * @throws ArithmeticException if the result overflows a long 1006 * @since 1.8 1007 */ decrementExact(long a)1008 public static long decrementExact(long a) { 1009 if (a == Long.MIN_VALUE) { 1010 throw new ArithmeticException("long overflow"); 1011 } 1012 1013 return a - 1L; 1014 } 1015 1016 /** 1017 * Returns the negation of the argument, throwing an exception if the 1018 * result overflows an {@code int}. 1019 * 1020 * @param a the value to negate 1021 * @return the result 1022 * @throws ArithmeticException if the result overflows an int 1023 * @since 1.8 1024 */ negateExact(int a)1025 public static int negateExact(int a) { 1026 if (a == Integer.MIN_VALUE) { 1027 throw new ArithmeticException("integer overflow"); 1028 } 1029 1030 return -a; 1031 } 1032 1033 /** 1034 * Returns the negation of the argument, throwing an exception if the 1035 * result overflows a {@code long}. 1036 * 1037 * @param a the value to negate 1038 * @return the result 1039 * @throws ArithmeticException if the result overflows a long 1040 * @since 1.8 1041 */ negateExact(long a)1042 public static long negateExact(long a) { 1043 if (a == Long.MIN_VALUE) { 1044 throw new ArithmeticException("long overflow"); 1045 } 1046 1047 return -a; 1048 } 1049 1050 /** 1051 * Returns the value of the {@code long} argument; 1052 * throwing an exception if the value overflows an {@code int}. 1053 * 1054 * @param value the long value 1055 * @return the argument as an int 1056 * @throws ArithmeticException if the {@code argument} overflows an int 1057 * @since 1.8 1058 */ toIntExact(long value)1059 public static int toIntExact(long value) { 1060 if ((int)value != value) { 1061 throw new ArithmeticException("integer overflow"); 1062 } 1063 return (int)value; 1064 } 1065 1066 /** 1067 * Returns the exact mathematical product of the arguments. 1068 * 1069 * @param x the first value 1070 * @param y the second value 1071 * @return the result 1072 * @since 9 1073 */ multiplyFull(int x, int y)1074 public static long multiplyFull(int x, int y) { 1075 return (long)x * (long)y; 1076 } 1077 1078 /** 1079 * Returns as a {@code long} the most significant 64 bits of the 128-bit 1080 * product of two 64-bit factors. 1081 * 1082 * @param x the first value 1083 * @param y the second value 1084 * @return the result 1085 * @since 9 1086 */ multiplyHigh(long x, long y)1087 public static long multiplyHigh(long x, long y) { 1088 if (x < 0 || y < 0) { 1089 // Use technique from section 8-2 of Henry S. Warren, Jr., 1090 // Hacker's Delight (2nd ed.) (Addison Wesley, 2013), 173-174. 1091 long x1 = x >> 32; 1092 long x2 = x & 0xFFFFFFFFL; 1093 long y1 = y >> 32; 1094 long y2 = y & 0xFFFFFFFFL; 1095 long z2 = x2 * y2; 1096 long t = x1 * y2 + (z2 >>> 32); 1097 long z1 = t & 0xFFFFFFFFL; 1098 long z0 = t >> 32; 1099 z1 += x2 * y1; 1100 return x1 * y1 + z0 + (z1 >> 32); 1101 } else { 1102 // Use Karatsuba technique with two base 2^32 digits. 1103 long x1 = x >>> 32; 1104 long y1 = y >>> 32; 1105 long x2 = x & 0xFFFFFFFFL; 1106 long y2 = y & 0xFFFFFFFFL; 1107 long A = x1 * y1; 1108 long B = x2 * y2; 1109 long C = (x1 + x2) * (y1 + y2); 1110 long K = C - A - B; 1111 return (((B >>> 32) + K) >>> 32) + A; 1112 } 1113 } 1114 1115 /** 1116 * Returns the largest (closest to positive infinity) 1117 * {@code int} value that is less than or equal to the algebraic quotient. 1118 * There is one special case, if the dividend is the 1119 * {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and the divisor is {@code -1}, 1120 * then integer overflow occurs and 1121 * the result is equal to {@code Integer.MIN_VALUE}. 1122 * <p> 1123 * Normal integer division operates under the round to zero rounding mode 1124 * (truncation). This operation instead acts under the round toward 1125 * negative infinity (floor) rounding mode. 1126 * The floor rounding mode gives different results from truncation 1127 * when the exact result is negative. 1128 * <ul> 1129 * <li>If the signs of the arguments are the same, the results of 1130 * {@code floorDiv} and the {@code /} operator are the same. <br> 1131 * For example, {@code floorDiv(4, 3) == 1} and {@code (4 / 3) == 1}.</li> 1132 * <li>If the signs of the arguments are different, the quotient is negative and 1133 * {@code floorDiv} returns the integer less than or equal to the quotient 1134 * and the {@code /} operator returns the integer closest to zero.<br> 1135 * For example, {@code floorDiv(-4, 3) == -2}, 1136 * whereas {@code (-4 / 3) == -1}. 1137 * </li> 1138 * </ul> 1139 * <p> 1140 * 1141 * @param x the dividend 1142 * @param y the divisor 1143 * @return the largest (closest to positive infinity) 1144 * {@code int} value that is less than or equal to the algebraic quotient. 1145 * @throws ArithmeticException if the divisor {@code y} is zero 1146 * @see #floorMod(int, int) 1147 * @see #floor(double) 1148 * @since 1.8 1149 */ floorDiv(int x, int y)1150 public static int floorDiv(int x, int y) { 1151 int r = x / y; 1152 // if the signs are different and modulo not zero, round down 1153 if ((x ^ y) < 0 && (r * y != x)) { 1154 r--; 1155 } 1156 return r; 1157 } 1158 1159 /** 1160 * Returns the largest (closest to positive infinity) 1161 * {@code long} value that is less than or equal to the algebraic quotient. 1162 * There is one special case, if the dividend is the 1163 * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1}, 1164 * then integer overflow occurs and 1165 * the result is equal to {@code Long.MIN_VALUE}. 1166 * <p> 1167 * Normal integer division operates under the round to zero rounding mode 1168 * (truncation). This operation instead acts under the round toward 1169 * negative infinity (floor) rounding mode. 1170 * The floor rounding mode gives different results from truncation 1171 * when the exact result is negative. 1172 * <p> 1173 * For examples, see {@link #floorDiv(int, int)}. 1174 * 1175 * @param x the dividend 1176 * @param y the divisor 1177 * @return the largest (closest to positive infinity) 1178 * {@code int} value that is less than or equal to the algebraic quotient. 1179 * @throws ArithmeticException if the divisor {@code y} is zero 1180 * @see #floorMod(long, int) 1181 * @see #floor(double) 1182 * @since 9 1183 */ floorDiv(long x, int y)1184 public static long floorDiv(long x, int y) { 1185 return floorDiv(x, (long)y); 1186 } 1187 1188 /** 1189 * Returns the largest (closest to positive infinity) 1190 * {@code long} value that is less than or equal to the algebraic quotient. 1191 * There is one special case, if the dividend is the 1192 * {@linkplain Long#MIN_VALUE Long.MIN_VALUE} and the divisor is {@code -1}, 1193 * then integer overflow occurs and 1194 * the result is equal to {@code Long.MIN_VALUE}. 1195 * <p> 1196 * Normal integer division operates under the round to zero rounding mode 1197 * (truncation). This operation instead acts under the round toward 1198 * negative infinity (floor) rounding mode. 1199 * The floor rounding mode gives different results from truncation 1200 * when the exact result is negative. 1201 * <p> 1202 * For examples, see {@link #floorDiv(int, int)}. 1203 * 1204 * @param x the dividend 1205 * @param y the divisor 1206 * @return the largest (closest to positive infinity) 1207 * {@code long} value that is less than or equal to the algebraic quotient. 1208 * @throws ArithmeticException if the divisor {@code y} is zero 1209 * @see #floorMod(long, long) 1210 * @see #floor(double) 1211 * @since 1.8 1212 */ floorDiv(long x, long y)1213 public static long floorDiv(long x, long y) { 1214 long r = x / y; 1215 // if the signs are different and modulo not zero, round down 1216 if ((x ^ y) < 0 && (r * y != x)) { 1217 r--; 1218 } 1219 return r; 1220 } 1221 1222 /** 1223 * Returns the floor modulus of the {@code int} arguments. 1224 * <p> 1225 * The floor modulus is {@code x - (floorDiv(x, y) * y)}, 1226 * has the same sign as the divisor {@code y}, and 1227 * is in the range of {@code -abs(y) < r < +abs(y)}. 1228 * 1229 * <p> 1230 * The relationship between {@code floorDiv} and {@code floorMod} is such that: 1231 * <ul> 1232 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} 1233 * </ul> 1234 * <p> 1235 * The difference in values between {@code floorMod} and 1236 * the {@code %} operator is due to the difference between 1237 * {@code floorDiv} that returns the integer less than or equal to the quotient 1238 * and the {@code /} operator that returns the integer closest to zero. 1239 * <p> 1240 * Examples: 1241 * <ul> 1242 * <li>If the signs of the arguments are the same, the results 1243 * of {@code floorMod} and the {@code %} operator are the same. <br> 1244 * <ul> 1245 * <li>{@code floorMod(4, 3) == 1}; and {@code (4 % 3) == 1}</li> 1246 * </ul> 1247 * <li>If the signs of the arguments are different, the results differ from the {@code %} operator.<br> 1248 * <ul> 1249 * <li>{@code floorMod(+4, -3) == -2}; and {@code (+4 % -3) == +1} </li> 1250 * <li>{@code floorMod(-4, +3) == +2}; and {@code (-4 % +3) == -1} </li> 1251 * <li>{@code floorMod(-4, -3) == -1}; and {@code (-4 % -3) == -1 } </li> 1252 * </ul> 1253 * </li> 1254 * </ul> 1255 * <p> 1256 * If the signs of arguments are unknown and a positive modulus 1257 * is needed it can be computed as {@code (floorMod(x, y) + abs(y)) % abs(y)}. 1258 * 1259 * @param x the dividend 1260 * @param y the divisor 1261 * @return the floor modulus {@code x - (floorDiv(x, y) * y)} 1262 * @throws ArithmeticException if the divisor {@code y} is zero 1263 * @see #floorDiv(int, int) 1264 * @since 1.8 1265 */ floorMod(int x, int y)1266 public static int floorMod(int x, int y) { 1267 return x - floorDiv(x, y) * y; 1268 } 1269 1270 /** 1271 * Returns the floor modulus of the {@code long} and {@code int} arguments. 1272 * <p> 1273 * The floor modulus is {@code x - (floorDiv(x, y) * y)}, 1274 * has the same sign as the divisor {@code y}, and 1275 * is in the range of {@code -abs(y) < r < +abs(y)}. 1276 * 1277 * <p> 1278 * The relationship between {@code floorDiv} and {@code floorMod} is such that: 1279 * <ul> 1280 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} 1281 * </ul> 1282 * <p> 1283 * For examples, see {@link #floorMod(int, int)}. 1284 * 1285 * @param x the dividend 1286 * @param y the divisor 1287 * @return the floor modulus {@code x - (floorDiv(x, y) * y)} 1288 * @throws ArithmeticException if the divisor {@code y} is zero 1289 * @see #floorDiv(long, int) 1290 * @since 9 1291 */ floorMod(long x, int y)1292 public static int floorMod(long x, int y) { 1293 // Result cannot overflow the range of int. 1294 return (int)(x - floorDiv(x, y) * y); 1295 } 1296 1297 /** 1298 * Returns the floor modulus of the {@code long} arguments. 1299 * <p> 1300 * The floor modulus is {@code x - (floorDiv(x, y) * y)}, 1301 * has the same sign as the divisor {@code y}, and 1302 * is in the range of {@code -abs(y) < r < +abs(y)}. 1303 * 1304 * <p> 1305 * The relationship between {@code floorDiv} and {@code floorMod} is such that: 1306 * <ul> 1307 * <li>{@code floorDiv(x, y) * y + floorMod(x, y) == x} 1308 * </ul> 1309 * <p> 1310 * For examples, see {@link #floorMod(int, int)}. 1311 * 1312 * @param x the dividend 1313 * @param y the divisor 1314 * @return the floor modulus {@code x - (floorDiv(x, y) * y)} 1315 * @throws ArithmeticException if the divisor {@code y} is zero 1316 * @see #floorDiv(long, long) 1317 * @since 1.8 1318 */ floorMod(long x, long y)1319 public static long floorMod(long x, long y) { 1320 return x - floorDiv(x, y) * y; 1321 } 1322 1323 /** 1324 * Returns the absolute value of an {@code int} value. 1325 * If the argument is not negative, the argument is returned. 1326 * If the argument is negative, the negation of the argument is returned. 1327 * 1328 * <p>Note that if the argument is equal to the value of 1329 * {@link Integer#MIN_VALUE}, the most negative representable 1330 * {@code int} value, the result is that same value, which is 1331 * negative. 1332 * 1333 * @param a the argument whose absolute value is to be determined 1334 * @return the absolute value of the argument. 1335 */ abs(int a)1336 public static int abs(int a) { 1337 return (a < 0) ? -a : a; 1338 } 1339 1340 /** 1341 * Returns the absolute value of a {@code long} value. 1342 * If the argument is not negative, the argument is returned. 1343 * If the argument is negative, the negation of the argument is returned. 1344 * 1345 * <p>Note that if the argument is equal to the value of 1346 * {@link Long#MIN_VALUE}, the most negative representable 1347 * {@code long} value, the result is that same value, which 1348 * is negative. 1349 * 1350 * @param a the argument whose absolute value is to be determined 1351 * @return the absolute value of the argument. 1352 */ abs(long a)1353 public static long abs(long a) { 1354 return (a < 0) ? -a : a; 1355 } 1356 1357 /** 1358 * Returns the absolute value of a {@code float} value. 1359 * If the argument is not negative, the argument is returned. 1360 * If the argument is negative, the negation of the argument is returned. 1361 * Special cases: 1362 * <ul><li>If the argument is positive zero or negative zero, the 1363 * result is positive zero. 1364 * <li>If the argument is infinite, the result is positive infinity. 1365 * <li>If the argument is NaN, the result is NaN.</ul> 1366 * In other words, the result is the same as the value of the expression: 1367 * <p>{@code Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))} 1368 * 1369 * @param a the argument whose absolute value is to be determined 1370 * @return the absolute value of the argument. 1371 */ abs(float a)1372 public static float abs(float a) { 1373 // Android-changed: Implementation modified to exactly match ART intrinsics behavior. 1374 // Note, as a "quality of implementation", rather than pure "spec compliance", 1375 // we require that Math.abs() clears the sign bit (but changes nothing else) 1376 // for all numbers, including NaN (signaling NaN may become quiet though). 1377 // http://b/30758343 1378 return Float.intBitsToFloat(0x7fffffff & Float.floatToRawIntBits(a)); 1379 } 1380 1381 /** 1382 * Returns the absolute value of a {@code double} value. 1383 * If the argument is not negative, the argument is returned. 1384 * If the argument is negative, the negation of the argument is returned. 1385 * Special cases: 1386 * <ul><li>If the argument is positive zero or negative zero, the result 1387 * is positive zero. 1388 * <li>If the argument is infinite, the result is positive infinity. 1389 * <li>If the argument is NaN, the result is NaN.</ul> 1390 * In other words, the result is the same as the value of the expression: 1391 * <p>{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)} 1392 * 1393 * @param a the argument whose absolute value is to be determined 1394 * @return the absolute value of the argument. 1395 */ abs(double a)1396 public static double abs(double a) { 1397 // Android-changed: Implementation modified to exactly match ART intrinsics behavior. 1398 // Note, as a "quality of implementation", rather than pure "spec compliance", 1399 // we require that Math.abs() clears the sign bit (but changes nothing else) 1400 // for all numbers, including NaN (signaling NaN may become quiet though). 1401 // http://b/30758343 1402 return Double.longBitsToDouble(0x7fffffffffffffffL & Double.doubleToRawLongBits(a)); 1403 } 1404 1405 /** 1406 * Returns the greater of two {@code int} values. That is, the 1407 * result is the argument closer to the value of 1408 * {@link Integer#MAX_VALUE}. If the arguments have the same value, 1409 * the result is that same value. 1410 * 1411 * @param a an argument. 1412 * @param b another argument. 1413 * @return the larger of {@code a} and {@code b}. 1414 */ max(int a, int b)1415 public static int max(int a, int b) { 1416 return (a >= b) ? a : b; 1417 } 1418 1419 /** 1420 * Returns the greater of two {@code long} values. That is, the 1421 * result is the argument closer to the value of 1422 * {@link Long#MAX_VALUE}. If the arguments have the same value, 1423 * the result is that same value. 1424 * 1425 * @param a an argument. 1426 * @param b another argument. 1427 * @return the larger of {@code a} and {@code b}. 1428 */ max(long a, long b)1429 public static long max(long a, long b) { 1430 return (a >= b) ? a : b; 1431 } 1432 1433 // Use raw bit-wise conversions on guaranteed non-NaN arguments. 1434 private static long negativeZeroFloatBits = Float.floatToRawIntBits(-0.0f); 1435 private static long negativeZeroDoubleBits = Double.doubleToRawLongBits(-0.0d); 1436 1437 /** 1438 * Returns the greater of two {@code float} values. That is, 1439 * the result is the argument closer to positive infinity. If the 1440 * arguments have the same value, the result is that same 1441 * value. If either value is NaN, then the result is NaN. Unlike 1442 * the numerical comparison operators, this method considers 1443 * negative zero to be strictly smaller than positive zero. If one 1444 * argument is positive zero and the other negative zero, the 1445 * result is positive zero. 1446 * 1447 * @param a an argument. 1448 * @param b another argument. 1449 * @return the larger of {@code a} and {@code b}. 1450 */ max(float a, float b)1451 public static float max(float a, float b) { 1452 if (a != a) 1453 return a; // a is NaN 1454 if ((a == 0.0f) && 1455 (b == 0.0f) && 1456 (Float.floatToRawIntBits(a) == negativeZeroFloatBits)) { 1457 // Raw conversion ok since NaN can't map to -0.0. 1458 return b; 1459 } 1460 return (a >= b) ? a : b; 1461 } 1462 1463 /** 1464 * Returns the greater of two {@code double} values. That 1465 * is, the result is the argument closer to positive infinity. If 1466 * the arguments have the same value, the result is that same 1467 * value. If either value is NaN, then the result is NaN. Unlike 1468 * the numerical comparison operators, this method considers 1469 * negative zero to be strictly smaller than positive zero. If one 1470 * argument is positive zero and the other negative zero, the 1471 * result is positive zero. 1472 * 1473 * @param a an argument. 1474 * @param b another argument. 1475 * @return the larger of {@code a} and {@code b}. 1476 */ max(double a, double b)1477 public static double max(double a, double b) { 1478 if (a != a) 1479 return a; // a is NaN 1480 if ((a == 0.0d) && 1481 (b == 0.0d) && 1482 (Double.doubleToRawLongBits(a) == negativeZeroDoubleBits)) { 1483 // Raw conversion ok since NaN can't map to -0.0. 1484 return b; 1485 } 1486 return (a >= b) ? a : b; 1487 } 1488 1489 /** 1490 * Returns the smaller of two {@code int} values. That is, 1491 * the result the argument closer to the value of 1492 * {@link Integer#MIN_VALUE}. If the arguments have the same 1493 * value, the result is that same value. 1494 * 1495 * @param a an argument. 1496 * @param b another argument. 1497 * @return the smaller of {@code a} and {@code b}. 1498 */ min(int a, int b)1499 public static int min(int a, int b) { 1500 return (a <= b) ? a : b; 1501 } 1502 1503 /** 1504 * Returns the smaller of two {@code long} values. That is, 1505 * the result is the argument closer to the value of 1506 * {@link Long#MIN_VALUE}. If the arguments have the same 1507 * value, the result is that same value. 1508 * 1509 * @param a an argument. 1510 * @param b another argument. 1511 * @return the smaller of {@code a} and {@code b}. 1512 */ min(long a, long b)1513 public static long min(long a, long b) { 1514 return (a <= b) ? a : b; 1515 } 1516 1517 /** 1518 * Returns the smaller of two {@code float} values. That is, 1519 * the result is the value closer to negative infinity. If the 1520 * arguments have the same value, the result is that same 1521 * value. If either value is NaN, then the result is NaN. Unlike 1522 * the numerical comparison operators, this method considers 1523 * negative zero to be strictly smaller than positive zero. If 1524 * one argument is positive zero and the other is negative zero, 1525 * the result is negative zero. 1526 * 1527 * @param a an argument. 1528 * @param b another argument. 1529 * @return the smaller of {@code a} and {@code b}. 1530 */ min(float a, float b)1531 public static float min(float a, float b) { 1532 if (a != a) 1533 return a; // a is NaN 1534 if ((a == 0.0f) && 1535 (b == 0.0f) && 1536 (Float.floatToRawIntBits(b) == negativeZeroFloatBits)) { 1537 // Raw conversion ok since NaN can't map to -0.0. 1538 return b; 1539 } 1540 return (a <= b) ? a : b; 1541 } 1542 1543 /** 1544 * Returns the smaller of two {@code double} values. That 1545 * is, the result is the value closer to negative infinity. If the 1546 * arguments have the same value, the result is that same 1547 * value. If either value is NaN, then the result is NaN. Unlike 1548 * the numerical comparison operators, this method considers 1549 * negative zero to be strictly smaller than positive zero. If one 1550 * argument is positive zero and the other is negative zero, the 1551 * result is negative zero. 1552 * 1553 * @param a an argument. 1554 * @param b another argument. 1555 * @return the smaller of {@code a} and {@code b}. 1556 */ min(double a, double b)1557 public static double min(double a, double b) { 1558 if (a != a) 1559 return a; // a is NaN 1560 if ((a == 0.0d) && 1561 (b == 0.0d) && 1562 (Double.doubleToRawLongBits(b) == negativeZeroDoubleBits)) { 1563 // Raw conversion ok since NaN can't map to -0.0. 1564 return b; 1565 } 1566 return (a <= b) ? a : b; 1567 } 1568 1569 /** 1570 * Returns the size of an ulp of the argument. An ulp, unit in 1571 * the last place, of a {@code double} value is the positive 1572 * distance between this floating-point value and the {@code 1573 * double} value next larger in magnitude. Note that for non-NaN 1574 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1575 * 1576 * <p>Special Cases: 1577 * <ul> 1578 * <li> If the argument is NaN, then the result is NaN. 1579 * <li> If the argument is positive or negative infinity, then the 1580 * result is positive infinity. 1581 * <li> If the argument is positive or negative zero, then the result is 1582 * {@code Double.MIN_VALUE}. 1583 * <li> If the argument is ±{@code Double.MAX_VALUE}, then 1584 * the result is equal to 2<sup>971</sup>. 1585 * </ul> 1586 * 1587 * @param d the floating-point value whose ulp is to be returned 1588 * @return the size of an ulp of the argument 1589 * @author Joseph D. Darcy 1590 * @since 1.5 1591 */ ulp(double d)1592 public static double ulp(double d) { 1593 int exp = getExponent(d); 1594 1595 switch(exp) { 1596 case DoubleConsts.MAX_EXPONENT+1: // NaN or infinity 1597 return Math.abs(d); 1598 1599 case DoubleConsts.MIN_EXPONENT-1: // zero or subnormal 1600 return Double.MIN_VALUE; 1601 1602 default: 1603 assert exp <= DoubleConsts.MAX_EXPONENT && exp >= DoubleConsts.MIN_EXPONENT; 1604 1605 // ulp(x) is usually 2^(SIGNIFICAND_WIDTH-1)*(2^ilogb(x)) 1606 exp = exp - (DoubleConsts.SIGNIFICAND_WIDTH-1); 1607 if (exp >= DoubleConsts.MIN_EXPONENT) { 1608 return powerOfTwoD(exp); 1609 } 1610 else { 1611 // return a subnormal result; left shift integer 1612 // representation of Double.MIN_VALUE appropriate 1613 // number of positions 1614 return Double.longBitsToDouble(1L << 1615 (exp - (DoubleConsts.MIN_EXPONENT - (DoubleConsts.SIGNIFICAND_WIDTH-1)) )); 1616 } 1617 } 1618 } 1619 1620 /** 1621 * Returns the size of an ulp of the argument. An ulp, unit in 1622 * the last place, of a {@code float} value is the positive 1623 * distance between this floating-point value and the {@code 1624 * float} value next larger in magnitude. Note that for non-NaN 1625 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1626 * 1627 * <p>Special Cases: 1628 * <ul> 1629 * <li> If the argument is NaN, then the result is NaN. 1630 * <li> If the argument is positive or negative infinity, then the 1631 * result is positive infinity. 1632 * <li> If the argument is positive or negative zero, then the result is 1633 * {@code Float.MIN_VALUE}. 1634 * <li> If the argument is ±{@code Float.MAX_VALUE}, then 1635 * the result is equal to 2<sup>104</sup>. 1636 * </ul> 1637 * 1638 * @param f the floating-point value whose ulp is to be returned 1639 * @return the size of an ulp of the argument 1640 * @author Joseph D. Darcy 1641 * @since 1.5 1642 */ ulp(float f)1643 public static float ulp(float f) { 1644 int exp = getExponent(f); 1645 1646 switch(exp) { 1647 case FloatConsts.MAX_EXPONENT+1: // NaN or infinity 1648 return Math.abs(f); 1649 1650 case FloatConsts.MIN_EXPONENT-1: // zero or subnormal 1651 return FloatConsts.MIN_VALUE; 1652 1653 default: 1654 assert exp <= FloatConsts.MAX_EXPONENT && exp >= FloatConsts.MIN_EXPONENT; 1655 1656 // ulp(x) is usually 2^(SIGNIFICAND_WIDTH-1)*(2^ilogb(x)) 1657 exp = exp - (FloatConsts.SIGNIFICAND_WIDTH-1); 1658 if (exp >= FloatConsts.MIN_EXPONENT) { 1659 return powerOfTwoF(exp); 1660 } 1661 else { 1662 // return a subnormal result; left shift integer 1663 // representation of FloatConsts.MIN_VALUE appropriate 1664 // number of positions 1665 return Float.intBitsToFloat(1 << 1666 (exp - (FloatConsts.MIN_EXPONENT - (FloatConsts.SIGNIFICAND_WIDTH-1)) )); 1667 } 1668 } 1669 } 1670 1671 /** 1672 * Returns the signum function of the argument; zero if the argument 1673 * is zero, 1.0 if the argument is greater than zero, -1.0 if the 1674 * argument is less than zero. 1675 * 1676 * <p>Special Cases: 1677 * <ul> 1678 * <li> If the argument is NaN, then the result is NaN. 1679 * <li> If the argument is positive zero or negative zero, then the 1680 * result is the same as the argument. 1681 * </ul> 1682 * 1683 * @param d the floating-point value whose signum is to be returned 1684 * @return the signum function of the argument 1685 * @author Joseph D. Darcy 1686 * @since 1.5 1687 */ signum(double d)1688 public static double signum(double d) { 1689 return (d == 0.0 || Double.isNaN(d))?d:copySign(1.0, d); 1690 } 1691 1692 /** 1693 * Returns the signum function of the argument; zero if the argument 1694 * is zero, 1.0f if the argument is greater than zero, -1.0f if the 1695 * argument is less than zero. 1696 * 1697 * <p>Special Cases: 1698 * <ul> 1699 * <li> If the argument is NaN, then the result is NaN. 1700 * <li> If the argument is positive zero or negative zero, then the 1701 * result is the same as the argument. 1702 * </ul> 1703 * 1704 * @param f the floating-point value whose signum is to be returned 1705 * @return the signum function of the argument 1706 * @author Joseph D. Darcy 1707 * @since 1.5 1708 */ signum(float f)1709 public static float signum(float f) { 1710 return (f == 0.0f || Float.isNaN(f))?f:copySign(1.0f, f); 1711 } 1712 1713 /** 1714 * Returns the hyperbolic sine of a {@code double} value. 1715 * The hyperbolic sine of <i>x</i> is defined to be 1716 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/2 1717 * where <i>e</i> is {@linkplain Math#E Euler's number}. 1718 * 1719 * <p>Special cases: 1720 * <ul> 1721 * 1722 * <li>If the argument is NaN, then the result is NaN. 1723 * 1724 * <li>If the argument is infinite, then the result is an infinity 1725 * with the same sign as the argument. 1726 * 1727 * <li>If the argument is zero, then the result is a zero with the 1728 * same sign as the argument. 1729 * 1730 * </ul> 1731 * 1732 * <p>The computed result must be within 2.5 ulps of the exact result. 1733 * 1734 * @param x The number whose hyperbolic sine is to be returned. 1735 * @return The hyperbolic sine of {@code x}. 1736 * @since 1.5 1737 */ 1738 @CriticalNative sinh(double x)1739 public static native double sinh(double x); 1740 1741 /** 1742 * Returns the hyperbolic cosine of a {@code double} value. 1743 * The hyperbolic cosine of <i>x</i> is defined to be 1744 * (<i>e<sup>x</sup> + e<sup>-x</sup></i>)/2 1745 * where <i>e</i> is {@linkplain Math#E Euler's number}. 1746 * 1747 * <p>Special cases: 1748 * <ul> 1749 * 1750 * <li>If the argument is NaN, then the result is NaN. 1751 * 1752 * <li>If the argument is infinite, then the result is positive 1753 * infinity. 1754 * 1755 * <li>If the argument is zero, then the result is {@code 1.0}. 1756 * 1757 * </ul> 1758 * 1759 * <p>The computed result must be within 2.5 ulps of the exact result. 1760 * 1761 * @param x The number whose hyperbolic cosine is to be returned. 1762 * @return The hyperbolic cosine of {@code x}. 1763 * @since 1.5 1764 */ 1765 @CriticalNative cosh(double x)1766 public static native double cosh(double x); 1767 1768 /** 1769 * Returns the hyperbolic tangent of a {@code double} value. 1770 * The hyperbolic tangent of <i>x</i> is defined to be 1771 * (<i>e<sup>x</sup> - e<sup>-x</sup></i>)/(<i>e<sup>x</sup> + e<sup>-x</sup></i>), 1772 * in other words, {@linkplain Math#sinh 1773 * sinh(<i>x</i>)}/{@linkplain Math#cosh cosh(<i>x</i>)}. Note 1774 * that the absolute value of the exact tanh is always less than 1775 * 1. 1776 * 1777 * <p>Special cases: 1778 * <ul> 1779 * 1780 * <li>If the argument is NaN, then the result is NaN. 1781 * 1782 * <li>If the argument is zero, then the result is a zero with the 1783 * same sign as the argument. 1784 * 1785 * <li>If the argument is positive infinity, then the result is 1786 * {@code +1.0}. 1787 * 1788 * <li>If the argument is negative infinity, then the result is 1789 * {@code -1.0}. 1790 * 1791 * </ul> 1792 * 1793 * <p>The computed result must be within 2.5 ulps of the exact result. 1794 * The result of {@code tanh} for any finite input must have 1795 * an absolute value less than or equal to 1. Note that once the 1796 * exact result of tanh is within 1/2 of an ulp of the limit value 1797 * of ±1, correctly signed ±{@code 1.0} should 1798 * be returned. 1799 * 1800 * @param x The number whose hyperbolic tangent is to be returned. 1801 * @return The hyperbolic tangent of {@code x}. 1802 * @since 1.5 1803 */ 1804 @CriticalNative tanh(double x)1805 public static native double tanh(double x); 1806 1807 /** 1808 * Returns sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>) 1809 * without intermediate overflow or underflow. 1810 * 1811 * <p>Special cases: 1812 * <ul> 1813 * 1814 * <li> If either argument is infinite, then the result 1815 * is positive infinity. 1816 * 1817 * <li> If either argument is NaN and neither argument is infinite, 1818 * then the result is NaN. 1819 * 1820 * </ul> 1821 * 1822 * <p>The computed result must be within 1 ulp of the exact 1823 * result. If one parameter is held constant, the results must be 1824 * semi-monotonic in the other parameter. 1825 * 1826 * @param x a value 1827 * @param y a value 1828 * @return sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>) 1829 * without intermediate overflow or underflow 1830 * @since 1.5 1831 */ 1832 @CriticalNative hypot(double x, double y)1833 public static native double hypot(double x, double y); 1834 1835 /** 1836 * Returns <i>e</i><sup>x</sup> -1. Note that for values of 1837 * <i>x</i> near 0, the exact sum of 1838 * {@code expm1(x)} + 1 is much closer to the true 1839 * result of <i>e</i><sup>x</sup> than {@code exp(x)}. 1840 * 1841 * <p>Special cases: 1842 * <ul> 1843 * <li>If the argument is NaN, the result is NaN. 1844 * 1845 * <li>If the argument is positive infinity, then the result is 1846 * positive infinity. 1847 * 1848 * <li>If the argument is negative infinity, then the result is 1849 * -1.0. 1850 * 1851 * <li>If the argument is zero, then the result is a zero with the 1852 * same sign as the argument. 1853 * 1854 * </ul> 1855 * 1856 * <p>The computed result must be within 1 ulp of the exact result. 1857 * Results must be semi-monotonic. The result of 1858 * {@code expm1} for any finite input must be greater than or 1859 * equal to {@code -1.0}. Note that once the exact result of 1860 * <i>e</i><sup>{@code x}</sup> - 1 is within 1/2 1861 * ulp of the limit value -1, {@code -1.0} should be 1862 * returned. 1863 * 1864 * @param x the exponent to raise <i>e</i> to in the computation of 1865 * <i>e</i><sup>{@code x}</sup> -1. 1866 * @return the value <i>e</i><sup>{@code x}</sup> - 1. 1867 * @since 1.5 1868 */ 1869 @CriticalNative expm1(double x)1870 public static native double expm1(double x); 1871 1872 /** 1873 * Returns the natural logarithm of the sum of the argument and 1. 1874 * Note that for small values {@code x}, the result of 1875 * {@code log1p(x)} is much closer to the true result of ln(1 1876 * + {@code x}) than the floating-point evaluation of 1877 * {@code log(1.0+x)}. 1878 * 1879 * <p>Special cases: 1880 * 1881 * <ul> 1882 * 1883 * <li>If the argument is NaN or less than -1, then the result is 1884 * NaN. 1885 * 1886 * <li>If the argument is positive infinity, then the result is 1887 * positive infinity. 1888 * 1889 * <li>If the argument is negative one, then the result is 1890 * negative infinity. 1891 * 1892 * <li>If the argument is zero, then the result is a zero with the 1893 * same sign as the argument. 1894 * 1895 * </ul> 1896 * 1897 * <p>The computed result must be within 1 ulp of the exact result. 1898 * Results must be semi-monotonic. 1899 * 1900 * @param x a value 1901 * @return the value ln({@code x} + 1), the natural 1902 * log of {@code x} + 1 1903 * @since 1.5 1904 */ 1905 @CriticalNative log1p(double x)1906 public static native double log1p(double x); 1907 1908 /** 1909 * Returns the first floating-point argument with the sign of the 1910 * second floating-point argument. Note that unlike the {@link 1911 * StrictMath#copySign(double, double) StrictMath.copySign} 1912 * method, this method does not require NaN {@code sign} 1913 * arguments to be treated as positive values; implementations are 1914 * permitted to treat some NaN arguments as positive and other NaN 1915 * arguments as negative to allow greater performance. 1916 * 1917 * @param magnitude the parameter providing the magnitude of the result 1918 * @param sign the parameter providing the sign of the result 1919 * @return a value with the magnitude of {@code magnitude} 1920 * and the sign of {@code sign}. 1921 * @since 1.6 1922 */ copySign(double magnitude, double sign)1923 public static double copySign(double magnitude, double sign) { 1924 return Double.longBitsToDouble((Double.doubleToRawLongBits(sign) & 1925 (DoubleConsts.SIGN_BIT_MASK)) | 1926 (Double.doubleToRawLongBits(magnitude) & 1927 (DoubleConsts.EXP_BIT_MASK | 1928 DoubleConsts.SIGNIF_BIT_MASK))); 1929 } 1930 1931 /** 1932 * Returns the first floating-point argument with the sign of the 1933 * second floating-point argument. Note that unlike the {@link 1934 * StrictMath#copySign(float, float) StrictMath.copySign} 1935 * method, this method does not require NaN {@code sign} 1936 * arguments to be treated as positive values; implementations are 1937 * permitted to treat some NaN arguments as positive and other NaN 1938 * arguments as negative to allow greater performance. 1939 * 1940 * @param magnitude the parameter providing the magnitude of the result 1941 * @param sign the parameter providing the sign of the result 1942 * @return a value with the magnitude of {@code magnitude} 1943 * and the sign of {@code sign}. 1944 * @since 1.6 1945 */ copySign(float magnitude, float sign)1946 public static float copySign(float magnitude, float sign) { 1947 return Float.intBitsToFloat((Float.floatToRawIntBits(sign) & 1948 (FloatConsts.SIGN_BIT_MASK)) | 1949 (Float.floatToRawIntBits(magnitude) & 1950 (FloatConsts.EXP_BIT_MASK | 1951 FloatConsts.SIGNIF_BIT_MASK))); 1952 } 1953 1954 /** 1955 * Returns the unbiased exponent used in the representation of a 1956 * {@code float}. Special cases: 1957 * 1958 * <ul> 1959 * <li>If the argument is NaN or infinite, then the result is 1960 * {@link Float#MAX_EXPONENT} + 1. 1961 * <li>If the argument is zero or subnormal, then the result is 1962 * {@link Float#MIN_EXPONENT} -1. 1963 * </ul> 1964 * @param f a {@code float} value 1965 * @return the unbiased exponent of the argument 1966 * @since 1.6 1967 */ getExponent(float f)1968 public static int getExponent(float f) { 1969 /* 1970 * Bitwise convert f to integer, mask out exponent bits, shift 1971 * to the right and then subtract out float's bias adjust to 1972 * get true exponent value 1973 */ 1974 return ((Float.floatToRawIntBits(f) & FloatConsts.EXP_BIT_MASK) >> 1975 (FloatConsts.SIGNIFICAND_WIDTH - 1)) - FloatConsts.EXP_BIAS; 1976 } 1977 1978 /** 1979 * Returns the unbiased exponent used in the representation of a 1980 * {@code double}. Special cases: 1981 * 1982 * <ul> 1983 * <li>If the argument is NaN or infinite, then the result is 1984 * {@link Double#MAX_EXPONENT} + 1. 1985 * <li>If the argument is zero or subnormal, then the result is 1986 * {@link Double#MIN_EXPONENT} -1. 1987 * </ul> 1988 * @param d a {@code double} value 1989 * @return the unbiased exponent of the argument 1990 * @since 1.6 1991 */ getExponent(double d)1992 public static int getExponent(double d) { 1993 /* 1994 * Bitwise convert d to long, mask out exponent bits, shift 1995 * to the right and then subtract out double's bias adjust to 1996 * get true exponent value. 1997 */ 1998 return (int)(((Double.doubleToRawLongBits(d) & DoubleConsts.EXP_BIT_MASK) >> 1999 (DoubleConsts.SIGNIFICAND_WIDTH - 1)) - DoubleConsts.EXP_BIAS); 2000 } 2001 2002 /** 2003 * Returns the floating-point number adjacent to the first 2004 * argument in the direction of the second argument. If both 2005 * arguments compare as equal the second argument is returned. 2006 * 2007 * <p> 2008 * Special cases: 2009 * <ul> 2010 * <li> If either argument is a NaN, then NaN is returned. 2011 * 2012 * <li> If both arguments are signed zeros, {@code direction} 2013 * is returned unchanged (as implied by the requirement of 2014 * returning the second argument if the arguments compare as 2015 * equal). 2016 * 2017 * <li> If {@code start} is 2018 * ±{@link Double#MIN_VALUE} and {@code direction} 2019 * has a value such that the result should have a smaller 2020 * magnitude, then a zero with the same sign as {@code start} 2021 * is returned. 2022 * 2023 * <li> If {@code start} is infinite and 2024 * {@code direction} has a value such that the result should 2025 * have a smaller magnitude, {@link Double#MAX_VALUE} with the 2026 * same sign as {@code start} is returned. 2027 * 2028 * <li> If {@code start} is equal to ± 2029 * {@link Double#MAX_VALUE} and {@code direction} has a 2030 * value such that the result should have a larger magnitude, an 2031 * infinity with same sign as {@code start} is returned. 2032 * </ul> 2033 * 2034 * @param start starting floating-point value 2035 * @param direction value indicating which of 2036 * {@code start}'s neighbors or {@code start} should 2037 * be returned 2038 * @return The floating-point number adjacent to {@code start} in the 2039 * direction of {@code direction}. 2040 * @since 1.6 2041 */ nextAfter(double start, double direction)2042 public static double nextAfter(double start, double direction) { 2043 /* 2044 * The cases: 2045 * 2046 * nextAfter(+infinity, 0) == MAX_VALUE 2047 * nextAfter(+infinity, +infinity) == +infinity 2048 * nextAfter(-infinity, 0) == -MAX_VALUE 2049 * nextAfter(-infinity, -infinity) == -infinity 2050 * 2051 * are naturally handled without any additional testing 2052 */ 2053 2054 // First check for NaN values 2055 if (Double.isNaN(start) || Double.isNaN(direction)) { 2056 // return a NaN derived from the input NaN(s) 2057 return start + direction; 2058 } else if (start == direction) { 2059 return direction; 2060 } else { // start > direction or start < direction 2061 // Add +0.0 to get rid of a -0.0 (+0.0 + -0.0 => +0.0) 2062 // then bitwise convert start to integer. 2063 long transducer = Double.doubleToRawLongBits(start + 0.0d); 2064 2065 /* 2066 * IEEE 754 floating-point numbers are lexicographically 2067 * ordered if treated as signed- magnitude integers . 2068 * Since Java's integers are two's complement, 2069 * incrementing" the two's complement representation of a 2070 * logically negative floating-point value *decrements* 2071 * the signed-magnitude representation. Therefore, when 2072 * the integer representation of a floating-point values 2073 * is less than zero, the adjustment to the representation 2074 * is in the opposite direction than would be expected at 2075 * first . 2076 */ 2077 if (direction > start) { // Calculate next greater value 2078 transducer = transducer + (transducer >= 0L ? 1L:-1L); 2079 } else { // Calculate next lesser value 2080 assert direction < start; 2081 if (transducer > 0L) 2082 --transducer; 2083 else 2084 if (transducer < 0L ) 2085 ++transducer; 2086 /* 2087 * transducer==0, the result is -MIN_VALUE 2088 * 2089 * The transition from zero (implicitly 2090 * positive) to the smallest negative 2091 * signed magnitude value must be done 2092 * explicitly. 2093 */ 2094 else 2095 transducer = DoubleConsts.SIGN_BIT_MASK | 1L; 2096 } 2097 2098 return Double.longBitsToDouble(transducer); 2099 } 2100 } 2101 2102 /** 2103 * Returns the floating-point number adjacent to the first 2104 * argument in the direction of the second argument. If both 2105 * arguments compare as equal a value equivalent to the second argument 2106 * is returned. 2107 * 2108 * <p> 2109 * Special cases: 2110 * <ul> 2111 * <li> If either argument is a NaN, then NaN is returned. 2112 * 2113 * <li> If both arguments are signed zeros, a value equivalent 2114 * to {@code direction} is returned. 2115 * 2116 * <li> If {@code start} is 2117 * ±{@link Float#MIN_VALUE} and {@code direction} 2118 * has a value such that the result should have a smaller 2119 * magnitude, then a zero with the same sign as {@code start} 2120 * is returned. 2121 * 2122 * <li> If {@code start} is infinite and 2123 * {@code direction} has a value such that the result should 2124 * have a smaller magnitude, {@link Float#MAX_VALUE} with the 2125 * same sign as {@code start} is returned. 2126 * 2127 * <li> If {@code start} is equal to ± 2128 * {@link Float#MAX_VALUE} and {@code direction} has a 2129 * value such that the result should have a larger magnitude, an 2130 * infinity with same sign as {@code start} is returned. 2131 * </ul> 2132 * 2133 * @param start starting floating-point value 2134 * @param direction value indicating which of 2135 * {@code start}'s neighbors or {@code start} should 2136 * be returned 2137 * @return The floating-point number adjacent to {@code start} in the 2138 * direction of {@code direction}. 2139 * @since 1.6 2140 */ nextAfter(float start, double direction)2141 public static float nextAfter(float start, double direction) { 2142 /* 2143 * The cases: 2144 * 2145 * nextAfter(+infinity, 0) == MAX_VALUE 2146 * nextAfter(+infinity, +infinity) == +infinity 2147 * nextAfter(-infinity, 0) == -MAX_VALUE 2148 * nextAfter(-infinity, -infinity) == -infinity 2149 * 2150 * are naturally handled without any additional testing 2151 */ 2152 2153 // First check for NaN values 2154 if (Float.isNaN(start) || Double.isNaN(direction)) { 2155 // return a NaN derived from the input NaN(s) 2156 return start + (float)direction; 2157 } else if (start == direction) { 2158 return (float)direction; 2159 } else { // start > direction or start < direction 2160 // Add +0.0 to get rid of a -0.0 (+0.0 + -0.0 => +0.0) 2161 // then bitwise convert start to integer. 2162 int transducer = Float.floatToRawIntBits(start + 0.0f); 2163 2164 /* 2165 * IEEE 754 floating-point numbers are lexicographically 2166 * ordered if treated as signed- magnitude integers . 2167 * Since Java's integers are two's complement, 2168 * incrementing" the two's complement representation of a 2169 * logically negative floating-point value *decrements* 2170 * the signed-magnitude representation. Therefore, when 2171 * the integer representation of a floating-point values 2172 * is less than zero, the adjustment to the representation 2173 * is in the opposite direction than would be expected at 2174 * first. 2175 */ 2176 if (direction > start) {// Calculate next greater value 2177 transducer = transducer + (transducer >= 0 ? 1:-1); 2178 } else { // Calculate next lesser value 2179 assert direction < start; 2180 if (transducer > 0) 2181 --transducer; 2182 else 2183 if (transducer < 0 ) 2184 ++transducer; 2185 /* 2186 * transducer==0, the result is -MIN_VALUE 2187 * 2188 * The transition from zero (implicitly 2189 * positive) to the smallest negative 2190 * signed magnitude value must be done 2191 * explicitly. 2192 */ 2193 else 2194 transducer = FloatConsts.SIGN_BIT_MASK | 1; 2195 } 2196 2197 return Float.intBitsToFloat(transducer); 2198 } 2199 } 2200 2201 /** 2202 * Returns the floating-point value adjacent to {@code d} in 2203 * the direction of positive infinity. This method is 2204 * semantically equivalent to {@code nextAfter(d, 2205 * Double.POSITIVE_INFINITY)}; however, a {@code nextUp} 2206 * implementation may run faster than its equivalent 2207 * {@code nextAfter} call. 2208 * 2209 * <p>Special Cases: 2210 * <ul> 2211 * <li> If the argument is NaN, the result is NaN. 2212 * 2213 * <li> If the argument is positive infinity, the result is 2214 * positive infinity. 2215 * 2216 * <li> If the argument is zero, the result is 2217 * {@link Double#MIN_VALUE} 2218 * 2219 * </ul> 2220 * 2221 * @param d starting floating-point value 2222 * @return The adjacent floating-point value closer to positive 2223 * infinity. 2224 * @since 1.6 2225 */ nextUp(double d)2226 public static double nextUp(double d) { 2227 if( Double.isNaN(d) || d == Double.POSITIVE_INFINITY) 2228 return d; 2229 else { 2230 d += 0.0d; 2231 return Double.longBitsToDouble(Double.doubleToRawLongBits(d) + 2232 ((d >= 0.0d)?+1L:-1L)); 2233 } 2234 } 2235 2236 /** 2237 * Returns the floating-point value adjacent to {@code f} in 2238 * the direction of positive infinity. This method is 2239 * semantically equivalent to {@code nextAfter(f, 2240 * Float.POSITIVE_INFINITY)}; however, a {@code nextUp} 2241 * implementation may run faster than its equivalent 2242 * {@code nextAfter} call. 2243 * 2244 * <p>Special Cases: 2245 * <ul> 2246 * <li> If the argument is NaN, the result is NaN. 2247 * 2248 * <li> If the argument is positive infinity, the result is 2249 * positive infinity. 2250 * 2251 * <li> If the argument is zero, the result is 2252 * {@link Float#MIN_VALUE} 2253 * 2254 * </ul> 2255 * 2256 * @param f starting floating-point value 2257 * @return The adjacent floating-point value closer to positive 2258 * infinity. 2259 * @since 1.6 2260 */ nextUp(float f)2261 public static float nextUp(float f) { 2262 if( Float.isNaN(f) || f == FloatConsts.POSITIVE_INFINITY) 2263 return f; 2264 else { 2265 f += 0.0f; 2266 return Float.intBitsToFloat(Float.floatToRawIntBits(f) + 2267 ((f >= 0.0f)?+1:-1)); 2268 } 2269 } 2270 2271 /** 2272 * Returns the floating-point value adjacent to {@code d} in 2273 * the direction of negative infinity. This method is 2274 * semantically equivalent to {@code nextAfter(d, 2275 * Double.NEGATIVE_INFINITY)}; however, a 2276 * {@code nextDown} implementation may run faster than its 2277 * equivalent {@code nextAfter} call. 2278 * 2279 * <p>Special Cases: 2280 * <ul> 2281 * <li> If the argument is NaN, the result is NaN. 2282 * 2283 * <li> If the argument is negative infinity, the result is 2284 * negative infinity. 2285 * 2286 * <li> If the argument is zero, the result is 2287 * {@code -Double.MIN_VALUE} 2288 * 2289 * </ul> 2290 * 2291 * @param d starting floating-point value 2292 * @return The adjacent floating-point value closer to negative 2293 * infinity. 2294 * @since 1.8 2295 */ nextDown(double d)2296 public static double nextDown(double d) { 2297 if (Double.isNaN(d) || d == Double.NEGATIVE_INFINITY) 2298 return d; 2299 else { 2300 if (d == 0.0) 2301 return -Double.MIN_VALUE; 2302 else 2303 return Double.longBitsToDouble(Double.doubleToRawLongBits(d) + 2304 ((d > 0.0d)?-1L:+1L)); 2305 } 2306 } 2307 2308 /** 2309 * Returns the floating-point value adjacent to {@code f} in 2310 * the direction of negative infinity. This method is 2311 * semantically equivalent to {@code nextAfter(f, 2312 * Float.NEGATIVE_INFINITY)}; however, a 2313 * {@code nextDown} implementation may run faster than its 2314 * equivalent {@code nextAfter} call. 2315 * 2316 * <p>Special Cases: 2317 * <ul> 2318 * <li> If the argument is NaN, the result is NaN. 2319 * 2320 * <li> If the argument is negative infinity, the result is 2321 * negative infinity. 2322 * 2323 * <li> If the argument is zero, the result is 2324 * {@code -Float.MIN_VALUE} 2325 * 2326 * </ul> 2327 * 2328 * @param f starting floating-point value 2329 * @return The adjacent floating-point value closer to negative 2330 * infinity. 2331 * @since 1.8 2332 */ nextDown(float f)2333 public static float nextDown(float f) { 2334 if (Float.isNaN(f) || f == Float.NEGATIVE_INFINITY) 2335 return f; 2336 else { 2337 if (f == 0.0f) 2338 return -Float.MIN_VALUE; 2339 else 2340 return Float.intBitsToFloat(Float.floatToRawIntBits(f) + 2341 ((f > 0.0f)?-1:+1)); 2342 } 2343 } 2344 2345 /** 2346 * Returns {@code d} × 2347 * 2<sup>{@code scaleFactor}</sup> rounded as if performed 2348 * by a single correctly rounded floating-point multiply to a 2349 * member of the double value set. See the Java 2350 * Language Specification for a discussion of floating-point 2351 * value sets. If the exponent of the result is between {@link 2352 * Double#MIN_EXPONENT} and {@link Double#MAX_EXPONENT}, the 2353 * answer is calculated exactly. If the exponent of the result 2354 * would be larger than {@code Double.MAX_EXPONENT}, an 2355 * infinity is returned. Note that if the result is subnormal, 2356 * precision may be lost; that is, when {@code scalb(x, n)} 2357 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal 2358 * <i>x</i>. When the result is non-NaN, the result has the same 2359 * sign as {@code d}. 2360 * 2361 * <p>Special cases: 2362 * <ul> 2363 * <li> If the first argument is NaN, NaN is returned. 2364 * <li> If the first argument is infinite, then an infinity of the 2365 * same sign is returned. 2366 * <li> If the first argument is zero, then a zero of the same 2367 * sign is returned. 2368 * </ul> 2369 * 2370 * @param d number to be scaled by a power of two. 2371 * @param scaleFactor power of 2 used to scale {@code d} 2372 * @return {@code d} × 2<sup>{@code scaleFactor}</sup> 2373 * @since 1.6 2374 */ scalb(double d, int scaleFactor)2375 public static double scalb(double d, int scaleFactor) { 2376 /* 2377 * This method does not need to be declared strictfp to 2378 * compute the same correct result on all platforms. When 2379 * scaling up, it does not matter what order the 2380 * multiply-store operations are done; the result will be 2381 * finite or overflow regardless of the operation ordering. 2382 * However, to get the correct result when scaling down, a 2383 * particular ordering must be used. 2384 * 2385 * When scaling down, the multiply-store operations are 2386 * sequenced so that it is not possible for two consecutive 2387 * multiply-stores to return subnormal results. If one 2388 * multiply-store result is subnormal, the next multiply will 2389 * round it away to zero. This is done by first multiplying 2390 * by 2 ^ (scaleFactor % n) and then multiplying several 2391 * times by by 2^n as needed where n is the exponent of number 2392 * that is a covenient power of two. In this way, at most one 2393 * real rounding error occurs. If the double value set is 2394 * being used exclusively, the rounding will occur on a 2395 * multiply. If the double-extended-exponent value set is 2396 * being used, the products will (perhaps) be exact but the 2397 * stores to d are guaranteed to round to the double value 2398 * set. 2399 * 2400 * It is _not_ a valid implementation to first multiply d by 2401 * 2^MIN_EXPONENT and then by 2 ^ (scaleFactor % 2402 * MIN_EXPONENT) since even in a strictfp program double 2403 * rounding on underflow could occur; e.g. if the scaleFactor 2404 * argument was (MIN_EXPONENT - n) and the exponent of d was a 2405 * little less than -(MIN_EXPONENT - n), meaning the final 2406 * result would be subnormal. 2407 * 2408 * Since exact reproducibility of this method can be achieved 2409 * without any undue performance burden, there is no 2410 * compelling reason to allow double rounding on underflow in 2411 * scalb. 2412 */ 2413 2414 // magnitude of a power of two so large that scaling a finite 2415 // nonzero value by it would be guaranteed to over or 2416 // underflow; due to rounding, scaling down takes takes an 2417 // additional power of two which is reflected here 2418 final int MAX_SCALE = DoubleConsts.MAX_EXPONENT + -DoubleConsts.MIN_EXPONENT + 2419 DoubleConsts.SIGNIFICAND_WIDTH + 1; 2420 int exp_adjust = 0; 2421 int scale_increment = 0; 2422 double exp_delta = Double.NaN; 2423 2424 // Make sure scaling factor is in a reasonable range 2425 2426 if(scaleFactor < 0) { 2427 scaleFactor = Math.max(scaleFactor, -MAX_SCALE); 2428 scale_increment = -512; 2429 exp_delta = twoToTheDoubleScaleDown; 2430 } 2431 else { 2432 scaleFactor = Math.min(scaleFactor, MAX_SCALE); 2433 scale_increment = 512; 2434 exp_delta = twoToTheDoubleScaleUp; 2435 } 2436 2437 // Calculate (scaleFactor % +/-512), 512 = 2^9, using 2438 // technique from "Hacker's Delight" section 10-2. 2439 int t = (scaleFactor >> 9-1) >>> 32 - 9; 2440 exp_adjust = ((scaleFactor + t) & (512 -1)) - t; 2441 2442 d *= powerOfTwoD(exp_adjust); 2443 scaleFactor -= exp_adjust; 2444 2445 while(scaleFactor != 0) { 2446 d *= exp_delta; 2447 scaleFactor -= scale_increment; 2448 } 2449 return d; 2450 } 2451 2452 /** 2453 * Returns {@code f} × 2454 * 2<sup>{@code scaleFactor}</sup> rounded as if performed 2455 * by a single correctly rounded floating-point multiply to a 2456 * member of the float value set. See the Java 2457 * Language Specification for a discussion of floating-point 2458 * value sets. If the exponent of the result is between {@link 2459 * Float#MIN_EXPONENT} and {@link Float#MAX_EXPONENT}, the 2460 * answer is calculated exactly. If the exponent of the result 2461 * would be larger than {@code Float.MAX_EXPONENT}, an 2462 * infinity is returned. Note that if the result is subnormal, 2463 * precision may be lost; that is, when {@code scalb(x, n)} 2464 * is subnormal, {@code scalb(scalb(x, n), -n)} may not equal 2465 * <i>x</i>. When the result is non-NaN, the result has the same 2466 * sign as {@code f}. 2467 * 2468 * <p>Special cases: 2469 * <ul> 2470 * <li> If the first argument is NaN, NaN is returned. 2471 * <li> If the first argument is infinite, then an infinity of the 2472 * same sign is returned. 2473 * <li> If the first argument is zero, then a zero of the same 2474 * sign is returned. 2475 * </ul> 2476 * 2477 * @param f number to be scaled by a power of two. 2478 * @param scaleFactor power of 2 used to scale {@code f} 2479 * @return {@code f} × 2<sup>{@code scaleFactor}</sup> 2480 * @since 1.6 2481 */ scalb(float f, int scaleFactor)2482 public static float scalb(float f, int scaleFactor) { 2483 // magnitude of a power of two so large that scaling a finite 2484 // nonzero value by it would be guaranteed to over or 2485 // underflow; due to rounding, scaling down takes takes an 2486 // additional power of two which is reflected here 2487 final int MAX_SCALE = FloatConsts.MAX_EXPONENT + -FloatConsts.MIN_EXPONENT + 2488 FloatConsts.SIGNIFICAND_WIDTH + 1; 2489 2490 // Make sure scaling factor is in a reasonable range 2491 scaleFactor = Math.max(Math.min(scaleFactor, MAX_SCALE), -MAX_SCALE); 2492 2493 /* 2494 * Since + MAX_SCALE for float fits well within the double 2495 * exponent range and + float -> double conversion is exact 2496 * the multiplication below will be exact. Therefore, the 2497 * rounding that occurs when the double product is cast to 2498 * float will be the correctly rounded float result. Since 2499 * all operations other than the final multiply will be exact, 2500 * it is not necessary to declare this method strictfp. 2501 */ 2502 return (float)((double)f*powerOfTwoD(scaleFactor)); 2503 } 2504 2505 // Constants used in scalb 2506 static double twoToTheDoubleScaleUp = powerOfTwoD(512); 2507 static double twoToTheDoubleScaleDown = powerOfTwoD(-512); 2508 2509 /** 2510 * Returns a floating-point power of two in the normal range. 2511 */ powerOfTwoD(int n)2512 static double powerOfTwoD(int n) { 2513 assert(n >= DoubleConsts.MIN_EXPONENT && n <= DoubleConsts.MAX_EXPONENT); 2514 return Double.longBitsToDouble((((long)n + (long)DoubleConsts.EXP_BIAS) << 2515 (DoubleConsts.SIGNIFICAND_WIDTH-1)) 2516 & DoubleConsts.EXP_BIT_MASK); 2517 } 2518 2519 /** 2520 * Returns a floating-point power of two in the normal range. 2521 */ powerOfTwoF(int n)2522 static float powerOfTwoF(int n) { 2523 assert(n >= FloatConsts.MIN_EXPONENT && n <= FloatConsts.MAX_EXPONENT); 2524 return Float.intBitsToFloat(((n + FloatConsts.EXP_BIAS) << 2525 (FloatConsts.SIGNIFICAND_WIDTH-1)) 2526 & FloatConsts.EXP_BIT_MASK); 2527 } 2528 } 2529