< prev index next >

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

Print this page




   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 &plusmn;{@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-accumulate of the three arguments;
1455      * that is, returns the exact product of the first two arguments
1456      * summed with the third argument and then rounded once to the
1457      * nearest {@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 fusedMac(a, 1.0, c)} returns the same
1483      * result as ({@code a + c}).  However,
1484      * {@code fusedMac(a, b, +0.0)} does <em>not</em> always return the
1485      * same result as ({@code a * b}) since
1486      * {@code fusedMac(-0.0, +0.0, +0.0)} is {@code +0.0} while
1487      * ({@code 0.0 * +0.0}) is {@code -0.0}; {@code fusedMac(a, b, -0.0)} is
1488      * equivalent to ({@code a * b}) however.
1489      *
1490      * @param a a value
1491      * @param b a value
1492      * @param c a value
1493      *
1494      * @return (<i>a</i>&nbsp;&times;&nbsp;<i>b</i>&nbsp;+&nbsp;<i>c</i>)
1495      * computed, as if with unlimited range and precision, and rounded
1496      * once to the nearest {@code double} value
1497      */
1498     // @HotSpotIntrinsicCandidate
1499     public static double fusedMac(double a, double b, double c) {
1500         if (!Double.isFinite(a) ||
1501             !Double.isFinite(b) ||
1502             !Double.isFinite(c)) {
1503             // Infinite and NaN arithmetic is not quite the same with
1504             // two roundings as opposed to just one. With two
1505             // roundings, the product and overflow and if the addend
1506             // is infinite, a spurious NaN can be produced.
1507             
1508             if (Double.isNaN(a) || Double.isNaN(b) || Double.isNaN(c)) {
1509                 return Double.NaN;
1510             } else { // One or more infinities in the input
1511                 if ((Double.isInfinite(a) && b == 0.0) ||
1512                     (Double.isInfinite(b) && a == 0.0)) {
1513                     return Double.NaN;
1514                 } else {
1515                     double product = a * b;
1516                     double result = product + c;
1517                     if (Double.isInfinite(product) &&
1518                         (!Double.isInfinite(a) && !Double.isInfinite(b))) {
1519                         // Intermediate overflow; might cause a
1520                         // spurious NaN with added to infinite c.
1521                         return c;
1522                     }
1523                     return result;
1524                 }
1525             }
1526         } if (a == 1.0 || // Could just return b + c
1527               b == 1.0 || // Could just return a + c
1528               a == 0.0 || // Handle any signed zero issues
1529               b == 0.0 || // Handle any signed zero issues
1530               c == 0.0) { // Could be +0.0 or -0.0)
1531             // The special cases of a == 1.0, b == 1.0, and c == 0.0
1532             // are handled as double operations rather than falling
1533             // back on BigDecimal. The case where a == 1.0 or b == 1.0
1534             // would be handled correctly by the BigDecimal code
1535             // below, unlike the signed zero case where the exact
1536             // product is -0.0 and c is -0.0.
1537 
1538             // As noted above, if c is zero, it must still be added in
1539             // since a negative zero can change the sign of the final
1540             // result if the product is zero. At the cost of
1541             // additional checks on a and b, the addition of a zero c
1542             // could be avoided.
1543 
1544             return a * b + c; 
1545         } else {
1546             // The set of values representable in BigDecimal includes
1547             // neither signed zero nor infinities nor NaN. The logic
1548             // above handles those cases. All finite double values are
1549             // representable in BigDecimal. The code below exactly
1550             // converts a, b, and c to their equivalent BigDecimal
1551             // numbers, exactly computes the product and sum as
1552             // appropriate, and then performs a single rounding to
1553             // double using the round to nearest rounding mode.
1554             return (((new BigDecimal(a)).multiply(new BigDecimal(b))).
1555                     add(new BigDecimal(c))).doubleValue();
1556         }
1557     }
1558 
1559     /**
1560      * Returns the fused multiply-accumulate of the three arguments;
1561      * that is, returns the exact product of the first two arguments
1562      * summed with the third argument and then rounded once to the
1563      * nearest {@code float}.
1564      *
1565      * The rounding is done using the {@linkplain
1566      * java.math.RoundingMode#HALF_EVEN round to nearest even
1567      * rounding mode}.
1568      *
1569      * In contrast, if {@code a * b + c} is evaluated as a regular
1570      * floating-point expression, two rounding errors are involved,
1571      * the first for the multiply operation, the second for the
1572      * addition operation.
1573      *
1574      * <p>Special cases:
1575      * <ul>
1576      * <li> If any argument is NaN, the result is NaN.
1577      *
1578      * <li> If one of the first two arguments is infinite and the
1579      * other is zero, the result is NaN.
1580      *
1581      * <li> If the exact product of the first two arguments is infinite
1582      * (in other words, at least one of the arguments is infinite and
1583      * the other is neither zero nor NaN) and the third argument is an
1584      * infinity of the opposite sign, the result is NaN.
1585      *
1586      * </ul>
1587      *
1588      * <p>Note that {@code fusedMac(a, 1.0f, c)} returns the same
1589      * result as ({@code a + c}).  However,
1590      * {@code fusedMac(a, b, +0.0f)} does <em>not</em> always return the
1591      * same result as ({@code a * b}) since
1592      * {@code fusedMac(-0.0f, +0.0f, +0.0f)} is {@code +0.0f} while
1593      * ({@code 0.0f * +0.0f}) is {@code -0.0f}; {@code fusedMac(a, b, -0.0f)} is
1594      * equivalent to ({@code a * b}) however.
1595      *
1596      * @param a a value
1597      * @param b a value
1598      * @param c a value
1599      *
1600      * @return (<i>a</i>&nbsp;&times;&nbsp;<i>b</i>&nbsp;+&nbsp;<i>c</i>)
1601      * computed, as if with unlimited range and precision, and rounded
1602      * once to the nearest {@code float} value
1603      */
1604     // @HotSpotIntrinsicCandidate
1605     public static float fusedMac(float a, float b, float c) {
1606         // Since double has more than twice the precision of float,
1607         // the multiply of a * b is exact in double. The add of c to
1608         // the product then has one rounded error. Since double
1609         // moreover has more than 2p + 2 precision compared to float,
1610         // the double rounding of (a*b + c) from the double format to
1611         // the float format is equivalent to rounding the result
1612         // directly to float precision.
1613         return (float)(((double) a * (double) b ) + (double) c);
1614     }
1615 
1616     /**
1617      * Returns the size of an ulp of the argument.  An ulp, unit in
1618      * the last place, of a {@code double} value is the positive
1619      * distance between this floating-point value and the {@code
1620      * double} value next larger in magnitude.  Note that for non-NaN
1621      * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
1622      *
1623      * <p>Special Cases:
1624      * <ul>
1625      * <li> If the argument is NaN, then the result is NaN.
1626      * <li> If the argument is positive or negative infinity, then the
1627      * result is positive infinity.
1628      * <li> If the argument is positive or negative zero, then the result is
1629      * {@code Double.MIN_VALUE}.
1630      * <li> If the argument is &plusmn;{@code Double.MAX_VALUE}, then
1631      * the result is equal to 2<sup>971</sup>.
1632      * </ul>
1633      *


< prev index next >