8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.lang; 27 28 import java.util.Random; 29 import jdk.internal.math.FloatConsts; 30 import jdk.internal.math.DoubleConsts; 31 import jdk.internal.HotSpotIntrinsicCandidate; 32 33 /** 34 * The class {@code Math} contains methods for performing basic 35 * numeric operations such as the elementary exponential, logarithm, 36 * square root, and trigonometric functions. 37 * 38 * <p>Unlike some of the numeric methods of class 39 * {@code StrictMath}, all implementations of the equivalent 40 * functions of class {@code Math} are not defined to return the 41 * bit-for-bit same results. This relaxation permits 42 * better-performing implementations where strict reproducibility is 43 * not required. 44 * 45 * <p>By default many of the {@code Math} methods simply call 46 * the equivalent method in {@code StrictMath} for their 47 * implementation. Code generators are encouraged to use 1430 * value. If either value is NaN, then the result is NaN. Unlike 1431 * the numerical comparison operators, this method considers 1432 * negative zero to be strictly smaller than positive zero. If one 1433 * argument is positive zero and the other is negative zero, the 1434 * result is negative zero. 1435 * 1436 * @param a an argument. 1437 * @param b another argument. 1438 * @return the smaller of {@code a} and {@code b}. 1439 */ 1440 public static double min(double a, double b) { 1441 if (a != a) 1442 return a; // a is NaN 1443 if ((a == 0.0d) && 1444 (b == 0.0d) && 1445 (Double.doubleToRawLongBits(b) == negativeZeroDoubleBits)) { 1446 // Raw conversion ok since NaN can't map to -0.0. 1447 return b; 1448 } 1449 return (a <= b) ? a : b; 1450 } 1451 1452 /** 1453 * Returns the size of an ulp of the argument. An ulp, unit in 1454 * the last place, of a {@code double} value is the positive 1455 * distance between this floating-point value and the {@code 1456 * double} value next larger in magnitude. Note that for non-NaN 1457 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1458 * 1459 * <p>Special Cases: 1460 * <ul> 1461 * <li> If the argument is NaN, then the result is NaN. 1462 * <li> If the argument is positive or negative infinity, then the 1463 * result is positive infinity. 1464 * <li> If the argument is positive or negative zero, then the result is 1465 * {@code Double.MIN_VALUE}. 1466 * <li> If the argument is ±{@code Double.MAX_VALUE}, then 1467 * the result is equal to 2<sup>971</sup>. 1468 * </ul> 1469 * | ```
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.lang;
27
28 import java.math.BigDecimal;
29 import java.util.Random;
30 import jdk.internal.math.FloatConsts;
31 import jdk.internal.math.DoubleConsts;
32 import jdk.internal.HotSpotIntrinsicCandidate;
33
34 /**
35 * The class {@code Math} contains methods for performing basic
36 * numeric operations such as the elementary exponential, logarithm,
37 * square root, and trigonometric functions.
38 *
39 * <p>Unlike some of the numeric methods of class
40 * {@code StrictMath}, all implementations of the equivalent
41 * functions of class {@code Math} are not defined to return the
42 * bit-for-bit same results. This relaxation permits
43 * better-performing implementations where strict reproducibility is
44 * not required.
45 *
46 * <p>By default many of the {@code Math} methods simply call
47 * the equivalent method in {@code StrictMath} for their
48 * implementation. Code generators are encouraged to use
``` 1431 * value. If either value is NaN, then the result is NaN. Unlike 1432 * the numerical comparison operators, this method considers 1433 * negative zero to be strictly smaller than positive zero. If one 1434 * argument is positive zero and the other is negative zero, the 1435 * result is negative zero. 1436 * 1437 * @param a an argument. 1438 * @param b another argument. 1439 * @return the smaller of {@code a} and {@code b}. 1440 */ 1441 public static double min(double a, double b) { 1442 if (a != a) 1443 return a; // a is NaN 1444 if ((a == 0.0d) && 1445 (b == 0.0d) && 1446 (Double.doubleToRawLongBits(b) == negativeZeroDoubleBits)) { 1447 // Raw conversion ok since NaN can't map to -0.0. 1448 return b; 1449 } 1450 return (a <= b) ? a : b; 1451 } 1452 1453 /** 1454 * Returns the fused multiply add of the three arguments; that is, 1455 * returns the exact product of the first two arguments summed 1456 * with the third argument and then rounded once to the nearest 1457 * {@code double}. 1458 * 1459 * The rounding is done using the {@linkplain 1460 * java.math.RoundingMode#HALF_EVEN round to nearest even 1461 * rounding mode}. 1462 * 1463 * In contrast, if {@code a * b + c} is evaluated as a regular 1464 * floating-point expression, two rounding errors are involved, 1465 * the first for the multiply operation, the second for the 1466 * addition operation. 1467 * 1468 * <p>Special cases: 1469 * <ul> 1470 * <li> If any argument is NaN, the result is NaN. 1471 * 1472 * <li> If one of the first two arguments is infinite and the 1473 * other is zero, the result is NaN. 1474 * 1475 * <li> If the exact product of the first two arguments is infinite 1476 * (in other words, at least one of the arguments is infinite and 1477 * the other is neither zero nor NaN) and the third argument is an 1478 * infinity of the opposite sign, the result is NaN. 1479 * 1480 * </ul> 1481 * 1482 * <p>Note that {@code fma(a, 1.0, c)} returns the same 1483 * result as ({@code a + c}). However, 1484 * {@code fma(a, b, +0.0)} does <em>not</em> always return the 1485 * same result as ({@code a * b}) since 1486 * {@code fma(-0.0, +0.0, +0.0)} is {@code +0.0} while 1487 * ({@code -0.0 * +0.0}) is {@code -0.0}; {@code fma(a, b, -0.0)} is 1488 * equivalent to ({@code a * b}) however. 1489 * 1490 * @apiNote This method corresponds to the fusedMultiplyAdd 1491 * operation defined in IEEE 754-2008. 1492 * 1493 * @param a a value 1494 * @param b a value 1495 * @param c a value 1496 * 1497 * @return (<i>a</i> × <i>b</i> + <i>c</i>) 1498 * computed, as if with unlimited range and precision, and rounded 1499 * once to the nearest {@code double} value 1500 */ 1501 // @HotSpotIntrinsicCandidate 1502 public static double fma(double a, double b, double c) { 1503 /* 1504 * Infinity and NaN arithmetic is not quite the same with two 1505 * roundings as opposed to just one so the simple expression 1506 * "a * b + c" cannot always be used to compute the correct 1507 * result. With two roundings, the product can overflow and 1508 * if the addend is infinite, a spurious NaN can be produced 1509 * if the infinity from the overflow and the infinite addend 1510 * have opposite signs. 1511 */ 1512 1513 // First, screen for and handle non-finite input values whose 1514 // arithmetic is not supported by BigDecimal. 1515 if (Double.isNaN(a) || Double.isNaN(b) || Double.isNaN(c)) { 1516 return Double.NaN; 1517 } else { // All inputs non-NaN 1518 boolean infiniteA = Double.isInfinite(a); 1519 boolean infiniteB = Double.isInfinite(b); 1520 boolean infiniteC = Double.isInfinite(c); 1521 double result; 1522 1523 if (infiniteA || infiniteB || infiniteC) { 1524 if (infiniteA && b == 0.0 || 1525 infiniteB && a == 0.0 ) { 1526 return Double.NaN; 1527 } 1528 // Store product in a double field to cause an 1529 // overflow even if non-strictfp evaluation is being 1530 // used. 1531 double product = a * b; 1532 if (Double.isInfinite(product) && !infiniteA && !infiniteB) { 1533 // Intermediate overflow; might cause a 1534 // spurious NaN if added to infinite c. 1535 assert Double.isInfinite(c); 1536 return c; 1537 } else { 1538 result = product + c; 1539 assert !Double.isFinite(result); 1540 return result; 1541 } 1542 } else { // All inputs finite 1543 BigDecimal product = (new BigDecimal(a)).multiply(new BigDecimal(b)); 1544 if (c == 0.0) { // Positive or negative zero 1545 // If the product is an exact zero, use a 1546 // floating-point expression to compute the sign 1547 // of the zero final result. The product is an 1548 // exact zero if and only if at least one of a and 1549 // b is zero. 1550 if (a == 0.0 || b == 0.0) { 1551 return a * b + c; 1552 } else { 1553 // The sign of a zero addend doesn't matter if 1554 // the product is nonzero. The sign of a zero 1555 // addend is not factored in the result if the 1556 // exact product is nonzero but underflows to 1557 // zero; see IEEE-754 2008 section 6.3 "The 1558 // sign bit". 1559 return product.doubleValue(); 1560 } 1561 } else { 1562 return product.add(new BigDecimal(c)).doubleValue(); 1563 } 1564 } 1565 } 1566 } 1567 1568 /** 1569 * Returns the fused multiply add of the three arguments; that is, 1570 * returns the exact product of the first two arguments summed 1571 * with the third argument and then rounded once to the nearest 1572 * {@code float}. 1573 * 1574 * The rounding is done using the {@linkplain 1575 * java.math.RoundingMode#HALF_EVEN round to nearest even 1576 * rounding mode}. 1577 * 1578 * In contrast, if {@code a * b + c} is evaluated as a regular 1579 * floating-point expression, two rounding errors are involved, 1580 * the first for the multiply operation, the second for the 1581 * addition operation. 1582 * 1583 * <p>Special cases: 1584 * <ul> 1585 * <li> If any argument is NaN, the result is NaN. 1586 * 1587 * <li> If one of the first two arguments is infinite and the 1588 * other is zero, the result is NaN. 1589 * 1590 * <li> If the exact product of the first two arguments is infinite 1591 * (in other words, at least one of the arguments is infinite and 1592 * the other is neither zero nor NaN) and the third argument is an 1593 * infinity of the opposite sign, the result is NaN. 1594 * 1595 * </ul> 1596 * 1597 * <p>Note that {@code fma(a, 1.0f, c)} returns the same 1598 * result as ({@code a + c}). However, 1599 * {@code fma(a, b, +0.0f)} does <em>not</em> always return the 1600 * same result as ({@code a * b}) since 1601 * {@code fma(-0.0f, +0.0f, +0.0f)} is {@code +0.0f} while 1602 * ({@code -0.0f * +0.0f}) is {@code -0.0f}; {@code fma(a, b, -0.0f)} is 1603 * equivalent to ({@code a * b}) however. 1604 * 1605 * @apiNote This method corresponds to the fusedMultiplyAdd 1606 * operation defined in IEEE 754-2008. 1607 * 1608 * @param a a value 1609 * @param b a value 1610 * @param c a value 1611 * 1612 * @return (<i>a</i> × <i>b</i> + <i>c</i>) 1613 * computed, as if with unlimited range and precision, and rounded 1614 * once to the nearest {@code float} value 1615 */ 1616 // @HotSpotIntrinsicCandidate 1617 public static float fma(float a, float b, float c) { 1618 /* 1619 * Since the double format has more than twice the precision 1620 * of the float format, the multiply of a * b is exact in 1621 * double. The add of c to the product then incurs one 1622 * rounding error. Since the double format moreover has more 1623 * than (2p + 2) precision bits compared to the p bits of the 1624 * float format, the two roundings of (a * b + c), first to 1625 * the double format and then secondarily to the float format, 1626 * are equivalent to rounding the intermediate result directly 1627 * to the float format. 1628 * 1629 * In terms of strictfp vs default-fp concerns related to 1630 * overflow and underflow, since 1631 * 1632 * (Float.MAX_VALUE * Float.MAX_VALUE) << Double.MAX_VALUE 1633 * (Float.MIN_VALUE * Float.MIN_VALUE) >> Double.MIN_VALUE 1634 * 1635 * neither the multiply nor add will overflow or underflow in 1636 * double. Therefore, it is not necessary for this method to 1637 * be declared strictfp to have reproducible 1638 * behavior. However, it is necessary to explicitly store down 1639 * to a float variable to avoid returning a value in the float 1640 * extended value set. 1641 */ 1642 float result = (float)(((double) a * (double) b ) + (double) c); 1643 return result; 1644 } 1645 1646 /** 1647 * Returns the size of an ulp of the argument. An ulp, unit in 1648 * the last place, of a {@code double} value is the positive 1649 * distance between this floating-point value and the {@code 1650 * double} value next larger in magnitude. Note that for non-NaN 1651 * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>. 1652 * 1653 * <p>Special Cases: 1654 * <ul> 1655 * <li> If the argument is NaN, then the result is NaN. 1656 * <li> If the argument is positive or negative infinity, then the 1657 * result is positive infinity. 1658 * <li> If the argument is positive or negative zero, then the result is 1659 * {@code Double.MIN_VALUE}. 1660 * <li> If the argument is ±{@code Double.MAX_VALUE}, then 1661 * the result is equal to 2<sup>971</sup>. 1662 * </ul> 1663 * |