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