/* * Copyright (c) 1994, 2016, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.lang; import java.math.BigDecimal; import java.util.Random; import jdk.internal.math.FloatConsts; import jdk.internal.math.DoubleConsts; import jdk.internal.HotSpotIntrinsicCandidate; /** * The class {@code Math} contains methods for performing basic * numeric operations such as the elementary exponential, logarithm, * square root, and trigonometric functions. * *
Unlike some of the numeric methods of class * {@code StrictMath}, all implementations of the equivalent * functions of class {@code Math} are not defined to return the * bit-for-bit same results. This relaxation permits * better-performing implementations where strict reproducibility is * not required. * *
By default many of the {@code Math} methods simply call * the equivalent method in {@code StrictMath} for their * implementation. Code generators are encouraged to use * platform-specific native libraries or microprocessor instructions, * where available, to provide higher-performance implementations of * {@code Math} methods. Such higher-performance * implementations still must conform to the specification for * {@code Math}. * *
The quality of implementation specifications concern two * properties, accuracy of the returned result and monotonicity of the * method. Accuracy of the floating-point {@code Math} methods is * measured in terms of ulps, units in the last place. For a * given floating-point format, an {@linkplain #ulp(double) ulp} of a * specific real number value is the distance between the two * floating-point values bracketing that numerical value. When * discussing the accuracy of a method as a whole rather than at a * specific argument, the number of ulps cited is for the worst-case * error at any argument. If a method always has an error less than * 0.5 ulps, the method always returns the floating-point number * nearest the exact result; such a method is correctly * rounded. A correctly rounded method is generally the best a * floating-point approximation can be; however, it is impractical for * many floating-point methods to be correctly rounded. Instead, for * the {@code Math} class, a larger error bound of 1 or 2 ulps is * allowed for certain methods. Informally, with a 1 ulp error bound, * when the exact result is a representable number, the exact result * should be returned as the computed result; otherwise, either of the * two floating-point values which bracket the exact result may be * returned. For exact results large in magnitude, one of the * endpoints of the bracket may be infinite. Besides accuracy at * individual arguments, maintaining proper relations between the * method at different arguments is also important. Therefore, most * methods with more than 0.5 ulp errors are required to be * semi-monotonic: whenever the mathematical function is * non-decreasing, so is the floating-point approximation, likewise, * whenever the mathematical function is non-increasing, so is the * floating-point approximation. Not all approximations that have 1 * ulp accuracy will automatically meet the monotonicity requirements. * *
* The platform uses signed two's complement integer arithmetic with * int and long primitive types. The developer should choose * the primitive type to ensure that arithmetic operations consistently * produce correct results, which in some cases means the operations * will not overflow the range of values of the computation. * The best practice is to choose the primitive type and algorithm to avoid * overflow. In cases where the size is {@code int} or {@code long} and * overflow errors need to be detected, the methods {@code addExact}, * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact} * throw an {@code ArithmeticException} when the results overflow. * For other arithmetic operations such as divide, absolute value, * increment, decrement, and negation overflow occurs only with * a specific minimum or maximum value and should be checked against * the minimum or maximum as appropriate. * * @author unascribed * @author Joseph D. Darcy * @since 1.0 */ public final class Math { /** * Don't let anyone instantiate this class. */ private Math() {} /** * The {@code double} value that is closer than any other to * e, the base of the natural logarithms. */ public static final double E = 2.7182818284590452354; /** * The {@code double} value that is closer than any other to * pi, the ratio of the circumference of a circle to its * diameter. */ public static final double PI = 3.14159265358979323846; /** * Constant by which to multiply an angular value in degrees to obtain an * angular value in radians. */ private static final double DEGREES_TO_RADIANS = 0.017453292519943295; /** * Constant by which to multiply an angular value in radians to obtain an * angular value in degrees. */ private static final double RADIANS_TO_DEGREES = 57.29577951308232; /** * Returns the trigonometric sine of an angle. Special cases: *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param a an angle, in radians. * @return the sine of the argument. */ @HotSpotIntrinsicCandidate public static double sin(double a) { return StrictMath.sin(a); // default impl. delegates to StrictMath } /** * Returns the trigonometric cosine of an angle. Special cases: *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param a an angle, in radians. * @return the cosine of the argument. */ @HotSpotIntrinsicCandidate public static double cos(double a) { return StrictMath.cos(a); // default impl. delegates to StrictMath } /** * Returns the trigonometric tangent of an angle. Special cases: *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param a an angle, in radians. * @return the tangent of the argument. */ @HotSpotIntrinsicCandidate public static double tan(double a) { return StrictMath.tan(a); // default impl. delegates to StrictMath } /** * Returns the arc sine of a value; the returned angle is in the * range -pi/2 through pi/2. Special cases: *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param a the value whose arc sine is to be returned. * @return the arc sine of the argument. */ public static double asin(double a) { return StrictMath.asin(a); // default impl. delegates to StrictMath } /** * Returns the arc cosine of a value; the returned angle is in the * range 0.0 through pi. Special case: *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param a the value whose arc cosine is to be returned. * @return the arc cosine of the argument. */ public static double acos(double a) { return StrictMath.acos(a); // default impl. delegates to StrictMath } /** * Returns the arc tangent of a value; the returned angle is in the * range -pi/2 through pi/2. Special cases: *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param a the value whose arc tangent is to be returned. * @return the arc tangent of the argument. */ public static double atan(double a) { return StrictMath.atan(a); // default impl. delegates to StrictMath } /** * Converts an angle measured in degrees to an approximately * equivalent angle measured in radians. The conversion from * degrees to radians is generally inexact. * * @param angdeg an angle, in degrees * @return the measurement of the angle {@code angdeg} * in radians. * @since 1.2 */ public static double toRadians(double angdeg) { return angdeg * DEGREES_TO_RADIANS; } /** * Converts an angle measured in radians to an approximately * equivalent angle measured in degrees. The conversion from * radians to degrees is generally inexact; users should * not expect {@code cos(toRadians(90.0))} to exactly * equal {@code 0.0}. * * @param angrad an angle, in radians * @return the measurement of the angle {@code angrad} * in degrees. * @since 1.2 */ public static double toDegrees(double angrad) { return angrad * RADIANS_TO_DEGREES; } /** * Returns Euler's number e raised to the power of a * {@code double} value. Special cases: *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param a the exponent to raise e to. * @return the value e{@code a}, * where e is the base of the natural logarithms. */ @HotSpotIntrinsicCandidate public static double exp(double a) { return StrictMath.exp(a); // default impl. delegates to StrictMath } /** * Returns the natural logarithm (base e) of a {@code double} * value. Special cases: *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param a a value * @return the value ln {@code a}, the natural logarithm of * {@code a}. */ @HotSpotIntrinsicCandidate public static double log(double a) { return StrictMath.log(a); // default impl. delegates to StrictMath } /** * Returns the base 10 logarithm of a {@code double} value. * Special cases: * *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param a a value * @return the base 10 logarithm of {@code a}. * @since 1.5 */ @HotSpotIntrinsicCandidate public static double log10(double a) { return StrictMath.log10(a); // default impl. delegates to StrictMath } /** * Returns the correctly rounded positive square root of a * {@code double} value. * Special cases: *
The computed result must be within 1 ulp of the exact result.
*
* @param a a value.
* @return the cube root of {@code a}.
* @since 1.5
*/
public static double cbrt(double a) {
return StrictMath.cbrt(a);
}
/**
* Computes the remainder operation on two arguments as prescribed
* by the IEEE 754 standard.
* The remainder value is mathematically equal to
* f1 - f2
× n,
* where n is the mathematical integer closest to the exact
* mathematical value of the quotient {@code f1/f2}, and if two
* mathematical integers are equally close to {@code f1/f2},
* then n is the integer that is even. If the remainder is
* zero, its sign is the same as the sign of the first argument.
* Special cases:
*
The computed result must be within 2 ulps of the exact result. * Results must be semi-monotonic. * * @param y the ordinate coordinate * @param x the abscissa coordinate * @return the theta component of the point * (r, theta) * in polar coordinates that corresponds to the point * (x, y) in Cartesian coordinates. */ @HotSpotIntrinsicCandidate public static double atan2(double y, double x) { return StrictMath.atan2(y, x); // default impl. delegates to StrictMath } /** * Returns the value of the first argument raised to the power of the * second argument. Special cases: * *
(In the foregoing descriptions, a floating-point value is * considered to be an integer if and only if it is finite and a * fixed point of the method {@link #ceil ceil} or, * equivalently, a fixed point of the method {@link #floor * floor}. A value is a fixed point of a one-argument * method if and only if the result of applying the method to the * value is equal to the value.) * *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param a the base. * @param b the exponent. * @return the value {@code a}{@code b}. */ @HotSpotIntrinsicCandidate public static double pow(double a, double b) { return StrictMath.pow(a, b); // default impl. delegates to StrictMath } /** * Returns the closest {@code int} to the argument, with ties * rounding to positive infinity. * *
* Special cases: *
Special cases: *
When this method is first called, it creates a single new * pseudorandom-number generator, exactly as if by the expression * *
{@code new java.util.Random()}* * This new pseudorandom-number generator is used thereafter for * all calls to this method and is used nowhere else. * *
This method is properly synchronized to allow correct use by * more than one thread. However, if many threads need to generate * pseudorandom numbers at a great rate, it may reduce contention * for each thread to have its own pseudorandom-number generator. * * @apiNote * As the largest {@code double} value less than {@code 1.0} * is {@code Math.nextDown(1.0)}, a value {@code x} in the closed range * {@code [x1,x2]} where {@code x1<=x2} may be defined by the statements * *
* * @return a pseudorandom {@code double} greater than or equal * to {@code 0.0} and less than {@code 1.0}. * @see #nextDown(double) * @see Random#nextDouble() */ public static double random() { return RandomNumberGeneratorHolder.randomNumberGenerator.nextDouble(); } /** * Returns the sum of its arguments, * throwing an exception if the result overflows an {@code int}. * * @param x the first value * @param y the second value * @return the result * @throws ArithmeticException if the result overflows an int * @since 1.8 */ @HotSpotIntrinsicCandidate public static int addExact(int x, int y) { int r = x + y; // HD 2-12 Overflow iff both arguments have the opposite sign of the result if (((x ^ r) & (y ^ r)) < 0) { throw new ArithmeticException("integer overflow"); } return r; } /** * Returns the sum of its arguments, * throwing an exception if the result overflows a {@code long}. * * @param x the first value * @param y the second value * @return the result * @throws ArithmeticException if the result overflows a long * @since 1.8 */ @HotSpotIntrinsicCandidate public static long addExact(long x, long y) { long r = x + y; // HD 2-12 Overflow iff both arguments have the opposite sign of the result if (((x ^ r) & (y ^ r)) < 0) { throw new ArithmeticException("long overflow"); } return r; } /** * Returns the difference of the arguments, * throwing an exception if the result overflows an {@code int}. * * @param x the first value * @param y the second value to subtract from the first * @return the result * @throws ArithmeticException if the result overflows an int * @since 1.8 */ @HotSpotIntrinsicCandidate public static int subtractExact(int x, int y) { int r = x - y; // HD 2-12 Overflow iff the arguments have different signs and // the sign of the result is different than the sign of x if (((x ^ y) & (x ^ r)) < 0) { throw new ArithmeticException("integer overflow"); } return r; } /** * Returns the difference of the arguments, * throwing an exception if the result overflows a {@code long}. * * @param x the first value * @param y the second value to subtract from the first * @return the result * @throws ArithmeticException if the result overflows a long * @since 1.8 */ @HotSpotIntrinsicCandidate public static long subtractExact(long x, long y) { long r = x - y; // HD 2-12 Overflow iff the arguments have different signs and // the sign of the result is different than the sign of x if (((x ^ y) & (x ^ r)) < 0) { throw new ArithmeticException("long overflow"); } return r; } /** * Returns the product of the arguments, * throwing an exception if the result overflows an {@code int}. * * @param x the first value * @param y the second value * @return the result * @throws ArithmeticException if the result overflows an int * @since 1.8 */ @HotSpotIntrinsicCandidate public static int multiplyExact(int x, int y) { long r = (long)x * (long)y; if ((int)r != r) { throw new ArithmeticException("integer overflow"); } return (int)r; } /** * Returns the product of the arguments, * throwing an exception if the result overflows a {@code long}. * * @param x the first value * @param y the second value * @return the result * @throws ArithmeticException if the result overflows a long * @since 1.8 */ @HotSpotIntrinsicCandidate public static long multiplyExact(long x, long y) { long r = x * y; long ax = Math.abs(x); long ay = Math.abs(y); if (((ax | ay) >>> 31 != 0)) { // Some bits greater than 2^31 that might cause overflow // Check the result using the divide operator // and check for the special case of Long.MIN_VALUE * -1 if (((y != 0) && (r / y != x)) || (x == Long.MIN_VALUE && y == -1)) { throw new ArithmeticException("long overflow"); } } return r; } /** * Returns the argument incremented by one, throwing an exception if the * result overflows an {@code int}. * * @param a the value to increment * @return the result * @throws ArithmeticException if the result overflows an int * @since 1.8 */ @HotSpotIntrinsicCandidate public static int incrementExact(int a) { if (a == Integer.MAX_VALUE) { throw new ArithmeticException("integer overflow"); } return a + 1; } /** * Returns the argument incremented by one, throwing an exception if the * result overflows a {@code long}. * * @param a the value to increment * @return the result * @throws ArithmeticException if the result overflows a long * @since 1.8 */ @HotSpotIntrinsicCandidate public static long incrementExact(long a) { if (a == Long.MAX_VALUE) { throw new ArithmeticException("long overflow"); } return a + 1L; } /** * Returns the argument decremented by one, throwing an exception if the * result overflows an {@code int}. * * @param a the value to decrement * @return the result * @throws ArithmeticException if the result overflows an int * @since 1.8 */ @HotSpotIntrinsicCandidate public static int decrementExact(int a) { if (a == Integer.MIN_VALUE) { throw new ArithmeticException("integer overflow"); } return a - 1; } /** * Returns the argument decremented by one, throwing an exception if the * result overflows a {@code long}. * * @param a the value to decrement * @return the result * @throws ArithmeticException if the result overflows a long * @since 1.8 */ @HotSpotIntrinsicCandidate public static long decrementExact(long a) { if (a == Long.MIN_VALUE) { throw new ArithmeticException("long overflow"); } return a - 1L; } /** * Returns the negation of the argument, throwing an exception if the * result overflows an {@code int}. * * @param a the value to negate * @return the result * @throws ArithmeticException if the result overflows an int * @since 1.8 */ @HotSpotIntrinsicCandidate public static int negateExact(int a) { if (a == Integer.MIN_VALUE) { throw new ArithmeticException("integer overflow"); } return -a; } /** * Returns the negation of the argument, throwing an exception if the * result overflows a {@code long}. * * @param a the value to negate * @return the result * @throws ArithmeticException if the result overflows a long * @since 1.8 */ @HotSpotIntrinsicCandidate public static long negateExact(long a) { if (a == Long.MIN_VALUE) { throw new ArithmeticException("long overflow"); } return -a; } /** * Returns the value of the {@code long} argument; * throwing an exception if the value overflows an {@code int}. * * @param value the long value * @return the argument as an int * @throws ArithmeticException if the {@code argument} overflows an int * @since 1.8 */ public static int toIntExact(long value) { if ((int)value != value) { throw new ArithmeticException("integer overflow"); } return (int)value; } /** * Returns the largest (closest to positive infinity) * {@code int} value that is less than or equal to the algebraic quotient. * There is one special case, if the dividend is the * {@linkplain Integer#MIN_VALUE Integer.MIN_VALUE} and the divisor is {@code -1}, * then integer overflow occurs and * the result is equal to the {@code Integer.MIN_VALUE}. *{@code * double f = Math.random()/Math.nextDown(1.0); * double x = x1*(1.0 - f) + x2*f; * }
* Normal integer division operates under the round to zero rounding mode * (truncation). This operation instead acts under the round toward * negative infinity (floor) rounding mode. * The floor rounding mode gives different results than truncation * when the exact result is negative. *
* Normal integer division operates under the round to zero rounding mode * (truncation). This operation instead acts under the round toward * negative infinity (floor) rounding mode. * The floor rounding mode gives different results than truncation * when the exact result is negative. *
* For examples, see {@link #floorDiv(int, int)}. * * @param x the dividend * @param y the divisor * @return the largest (closest to positive infinity) * {@code long} value that is less than or equal to the algebraic quotient. * @throws ArithmeticException if the divisor {@code y} is zero * @see #floorMod(long, long) * @see #floor(double) * @since 1.8 */ public static long floorDiv(long x, long y) { long r = x / y; // if the signs are different and modulo not zero, round down if ((x ^ y) < 0 && (r * y != x)) { r--; } return r; } /** * Returns the floor modulus of the {@code int} arguments. *
* The floor modulus is {@code x - (floorDiv(x, y) * y)}, * has the same sign as the divisor {@code y}, and * is in the range of {@code -abs(y) < r < +abs(y)}. * *
* The relationship between {@code floorDiv} and {@code floorMod} is such that: *
* The difference in values between {@code floorMod} and * the {@code %} operator is due to the difference between * {@code floorDiv} that returns the integer less than or equal to the quotient * and the {@code /} operator that returns the integer closest to zero. *
* Examples: *
* If the signs of arguments are unknown and a positive modulus * is needed it can be computed as {@code (floorMod(x, y) + abs(y)) % abs(y)}. * * @param x the dividend * @param y the divisor * @return the floor modulus {@code x - (floorDiv(x, y) * y)} * @throws ArithmeticException if the divisor {@code y} is zero * @see #floorDiv(int, int) * @since 1.8 */ public static int floorMod(int x, int y) { int r = x - floorDiv(x, y) * y; return r; } /** * Returns the floor modulus of the {@code long} arguments. *
* The floor modulus is {@code x - (floorDiv(x, y) * y)}, * has the same sign as the divisor {@code y}, and * is in the range of {@code -abs(y) < r < +abs(y)}. * *
* The relationship between {@code floorDiv} and {@code floorMod} is such that: *
* For examples, see {@link #floorMod(int, int)}. * * @param x the dividend * @param y the divisor * @return the floor modulus {@code x - (floorDiv(x, y) * y)} * @throws ArithmeticException if the divisor {@code y} is zero * @see #floorDiv(long, long) * @since 1.8 */ public static long floorMod(long x, long y) { return x - floorDiv(x, y) * y; } /** * Returns the absolute value of an {@code int} value. * If the argument is not negative, the argument is returned. * If the argument is negative, the negation of the argument is returned. * *
Note that if the argument is equal to the value of * {@link Integer#MIN_VALUE}, the most negative representable * {@code int} value, the result is that same value, which is * negative. * * @param a the argument whose absolute value is to be determined * @return the absolute value of the argument. */ public static int abs(int a) { return (a < 0) ? -a : a; } /** * Returns the absolute value of a {@code long} value. * If the argument is not negative, the argument is returned. * If the argument is negative, the negation of the argument is returned. * *
Note that if the argument is equal to the value of * {@link Long#MIN_VALUE}, the most negative representable * {@code long} value, the result is that same value, which * is negative. * * @param a the argument whose absolute value is to be determined * @return the absolute value of the argument. */ public static long abs(long a) { return (a < 0) ? -a : a; } /** * Returns the absolute value of a {@code float} value. * If the argument is not negative, the argument is returned. * If the argument is negative, the negation of the argument is returned. * Special cases: *
{@code Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))} * * @param a the argument whose absolute value is to be determined * @return the absolute value of the argument. */ public static float abs(float a) { return (a <= 0.0F) ? 0.0F - a : a; } /** * Returns the absolute value of a {@code double} value. * If the argument is not negative, the argument is returned. * If the argument is negative, the negation of the argument is returned. * Special cases: *
{@code Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)} * * @param a the argument whose absolute value is to be determined * @return the absolute value of the argument. */ @HotSpotIntrinsicCandidate public static double abs(double a) { return (a <= 0.0D) ? 0.0D - a : a; } /** * Returns the greater of two {@code int} values. That is, the * result is the argument closer to the value of * {@link Integer#MAX_VALUE}. If the arguments have the same value, * the result is that same value. * * @param a an argument. * @param b another argument. * @return the larger of {@code a} and {@code b}. */ @HotSpotIntrinsicCandidate public static int max(int a, int b) { return (a >= b) ? a : b; } /** * Returns the greater of two {@code long} values. That is, the * result is the argument closer to the value of * {@link Long#MAX_VALUE}. If the arguments have the same value, * the result is that same value. * * @param a an argument. * @param b another argument. * @return the larger of {@code a} and {@code b}. */ public static long max(long a, long b) { return (a >= b) ? a : b; } // Use raw bit-wise conversions on guaranteed non-NaN arguments. private static long negativeZeroFloatBits = Float.floatToRawIntBits(-0.0f); private static long negativeZeroDoubleBits = Double.doubleToRawLongBits(-0.0d); /** * Returns the greater of two {@code float} values. That is, * the result is the argument closer to positive infinity. If the * arguments have the same value, the result is that same * value. If either value is NaN, then the result is NaN. Unlike * the numerical comparison operators, this method considers * negative zero to be strictly smaller than positive zero. If one * argument is positive zero and the other negative zero, the * result is positive zero. * * @param a an argument. * @param b another argument. * @return the larger of {@code a} and {@code b}. */ public static float max(float a, float b) { if (a != a) return a; // a is NaN if ((a == 0.0f) && (b == 0.0f) && (Float.floatToRawIntBits(a) == negativeZeroFloatBits)) { // Raw conversion ok since NaN can't map to -0.0. return b; } return (a >= b) ? a : b; } /** * Returns the greater of two {@code double} values. That * is, the result is the argument closer to positive infinity. If * the arguments have the same value, the result is that same * value. If either value is NaN, then the result is NaN. Unlike * the numerical comparison operators, this method considers * negative zero to be strictly smaller than positive zero. If one * argument is positive zero and the other negative zero, the * result is positive zero. * * @param a an argument. * @param b another argument. * @return the larger of {@code a} and {@code b}. */ public static double max(double a, double b) { if (a != a) return a; // a is NaN if ((a == 0.0d) && (b == 0.0d) && (Double.doubleToRawLongBits(a) == negativeZeroDoubleBits)) { // Raw conversion ok since NaN can't map to -0.0. return b; } return (a >= b) ? a : b; } /** * Returns the smaller of two {@code int} values. That is, * the result the argument closer to the value of * {@link Integer#MIN_VALUE}. If the arguments have the same * value, the result is that same value. * * @param a an argument. * @param b another argument. * @return the smaller of {@code a} and {@code b}. */ @HotSpotIntrinsicCandidate public static int min(int a, int b) { return (a <= b) ? a : b; } /** * Returns the smaller of two {@code long} values. That is, * the result is the argument closer to the value of * {@link Long#MIN_VALUE}. If the arguments have the same * value, the result is that same value. * * @param a an argument. * @param b another argument. * @return the smaller of {@code a} and {@code b}. */ public static long min(long a, long b) { return (a <= b) ? a : b; } /** * Returns the smaller of two {@code float} values. That is, * the result is the value closer to negative infinity. If the * arguments have the same value, the result is that same * value. If either value is NaN, then the result is NaN. Unlike * the numerical comparison operators, this method considers * negative zero to be strictly smaller than positive zero. If * one argument is positive zero and the other is negative zero, * the result is negative zero. * * @param a an argument. * @param b another argument. * @return the smaller of {@code a} and {@code b}. */ public static float min(float a, float b) { if (a != a) return a; // a is NaN if ((a == 0.0f) && (b == 0.0f) && (Float.floatToRawIntBits(b) == negativeZeroFloatBits)) { // Raw conversion ok since NaN can't map to -0.0. return b; } return (a <= b) ? a : b; } /** * Returns the smaller of two {@code double} values. That * is, the result is the value closer to negative infinity. If the * arguments have the same value, the result is that same * value. If either value is NaN, then the result is NaN. Unlike * the numerical comparison operators, this method considers * negative zero to be strictly smaller than positive zero. If one * argument is positive zero and the other is negative zero, the * result is negative zero. * * @param a an argument. * @param b another argument. * @return the smaller of {@code a} and {@code b}. */ public static double min(double a, double b) { if (a != a) return a; // a is NaN if ((a == 0.0d) && (b == 0.0d) && (Double.doubleToRawLongBits(b) == negativeZeroDoubleBits)) { // Raw conversion ok since NaN can't map to -0.0. return b; } return (a <= b) ? a : b; } /** * Returns the fused multiply add of the three arguments; that is, * returns the exact product of the first two arguments summed * with the third argument and then rounded once to the nearest * {@code double}. * * The rounding is done using the {@linkplain * java.math.RoundingMode#HALF_EVEN round to nearest even * rounding mode}. * * In contrast, if {@code a * b + c} is evaluated as a regular * floating-point expression, two rounding errors are involved, * the first for the multiply operation, the second for the * addition operation. * *
Special cases: *
Note that {@code fusedMac(a, 1.0, c)} returns the same * result as ({@code a + c}). However, * {@code fusedMac(a, b, +0.0)} does not always return the * same result as ({@code a * b}) since * {@code fusedMac(-0.0, +0.0, +0.0)} is {@code +0.0} while * ({@code -0.0 * +0.0}) is {@code -0.0}; {@code fusedMac(a, b, -0.0)} is * equivalent to ({@code a * b}) however. * * @apiNote This method corresponds to the fusedMultiplyAdd * operation defined in IEEE 754-2008. * * @param a a value * @param b a value * @param c a value * * @return (a × b + c) * computed, as if with unlimited range and precision, and rounded * once to the nearest {@code double} value */ // @HotSpotIntrinsicCandidate public static double fma(double a, double b, double c) { /* * Infinity and NaN arithmetic is not quite the same with two * roundings as opposed to just one so the simple expression * "a * b + c" cannot always be used to compute the correct * result. With two roundings, the product can overflow and * if the addend is infinite, a spurious NaN can be produced * if the infinity from the overflow and the infinite addend * have opposite signs. */ // First, screen for and handle non-finite input values whose // arithmetic is not supported by BigDecimal. if (Double.isNaN(a) || Double.isNaN(b) || Double.isNaN(c)) { return Double.NaN; } else { // All inputs non-NaN boolean infiniteA = Double.isInfinite(a); boolean infiniteB = Double.isInfinite(b); boolean infiniteC = Double.isInfinite(c); double result; if (infiniteA || infiniteB || infiniteC) { if (infiniteA && b == 0.0 || infiniteB && a == 0.0 ) { return Double.NaN; } // Store product in a double field to cause an // overflow even if non-strictfp evaluation is being // used. double product = a * b; if (Double.isInfinite(product) && !infiniteA && !infiniteB) { // Intermediate overflow; might cause a // spurious NaN if added to infinite c. assert Double.isInfinite(c); return c; } else { result = product + c; assert !Double.isFinite(result); return result; } } else { // All inputs finite BigDecimal product = (new BigDecimal(a)).multiply(new BigDecimal(b)); if (c == 0.0) { // Positive or negative zero double tmp = product.doubleValue(); // If the product is an exact zero, use a // floating-point expression to compute the sign // of the zero final result. if (tmp == 0.0 && a == 0.0 || b == 0.0) { return a * b + c; } else { // The sign of a zero addend doesn't matter if // the product is nonzero. The sign of a zero // addend is not factored in the result if the // exact product is nonzero but underflows to // zero; see IEEE 754 2008 section 6.3 "The // sign bit". return tmp; } } else { return product.add(new BigDecimal(c)).doubleValue(); } } } } /** * Returns the fused multiply add of the three arguments; that is, * returns the exact product of the first two arguments summed * with the third argument and then rounded once to the nearest * {@code float}. * * The rounding is done using the {@linkplain * java.math.RoundingMode#HALF_EVEN round to nearest even * rounding mode}. * * In contrast, if {@code a * b + c} is evaluated as a regular * floating-point expression, two rounding errors are involved, * the first for the multiply operation, the second for the * addition operation. * *
Special cases: *
Note that {@code fusedMac(a, 1.0f, c)} returns the same
* result as ({@code a + c}). However,
* {@code fusedMac(a, b, +0.0f)} does not always return the
* same result as ({@code a * b}) since
* {@code fusedMac(-0.0f, +0.0f, +0.0f)} is {@code +0.0f} while
* ({@code -0.0f * +0.0f}) is {@code -0.0f}; {@code fusedMac(a, b, -0.0f)} is
* equivalent to ({@code a * b}) however.
*
* @apiNote This method corresponds to the fusedMultiplyAdd
* operation defined in IEEE 754-2008.
*
* @param a a value
* @param b a value
* @param c a value
*
* @return (a × b + c)
* computed, as if with unlimited range and precision, and rounded
* once to the nearest {@code float} value
*/
// @HotSpotIntrinsicCandidate
public static float fma(float a, float b, float c) {
/*
* Since the double format has more than twice the precision
* of the float format, the multiply of a * b is exact in
* double. The add of c to the product then incurs one
* rounding error. Since the double format moreover has more
* than (2p + 2) precision bits compared to the p bits of the
* float format, the two roundings of (a * b + c), first to
* the double format and then secondarily to the float format,
* are equivalent to rounding the intermediate result directly
* to the float format.
*
* In terms of strictfp vs default-fp concerns related to
* overflow and underflow, since
*
* (Float.MAX_VALUE * Float.MAX_VALUE) << Double.MAX_VALUE
* (Float.MIN_VALUE * Float.MIN_VALUE) >> Double.MIN_VALUE
*
* neither the multiply nor add will overflow or underflow in
* double. Therefore, it is not necessary for this method to
* be declared strictfp to have reproducible
* behavior. However, it is necessary to explicitly store down
* to a float variable to avoid returning a value in the float
* extended value set.
*/
float result = (float)(((double) a * (double) b ) + (double) c);
return result;
}
/**
* Returns the size of an ulp of the argument. An ulp, unit in
* the last place, of a {@code double} value is the positive
* distance between this floating-point value and the {@code
* double} value next larger in magnitude. Note that for non-NaN
* x, ulp(-x) == ulp(x)
.
*
*
Special Cases: *
ulp(-x) == ulp(x)
.
*
* Special Cases: *
Special Cases: *
Special Cases: *
Special cases: *
The computed result must be within 2.5 ulps of the exact result. * * @param x The number whose hyperbolic sine is to be returned. * @return The hyperbolic sine of {@code x}. * @since 1.5 */ public static double sinh(double x) { return StrictMath.sinh(x); } /** * Returns the hyperbolic cosine of a {@code double} value. * The hyperbolic cosine of x is defined to be * (ex + e-x)/2 * where e is {@linkplain Math#E Euler's number}. * *
Special cases: *
The computed result must be within 2.5 ulps of the exact result. * * @param x The number whose hyperbolic cosine is to be returned. * @return The hyperbolic cosine of {@code x}. * @since 1.5 */ public static double cosh(double x) { return StrictMath.cosh(x); } /** * Returns the hyperbolic tangent of a {@code double} value. * The hyperbolic tangent of x is defined to be * (ex - e-x)/(ex + e-x), * in other words, {@linkplain Math#sinh * sinh(x)}/{@linkplain Math#cosh cosh(x)}. Note * that the absolute value of the exact tanh is always less than * 1. * *
Special cases: *
The computed result must be within 2.5 ulps of the exact result. * The result of {@code tanh} for any finite input must have * an absolute value less than or equal to 1. Note that once the * exact result of tanh is within 1/2 of an ulp of the limit value * of ±1, correctly signed ±{@code 1.0} should * be returned. * * @param x The number whose hyperbolic tangent is to be returned. * @return The hyperbolic tangent of {@code x}. * @since 1.5 */ public static double tanh(double x) { return StrictMath.tanh(x); } /** * Returns sqrt(x2 +y2) * without intermediate overflow or underflow. * *
Special cases: *
The computed result must be within 1 ulp of the exact * result. If one parameter is held constant, the results must be * semi-monotonic in the other parameter. * * @param x a value * @param y a value * @return sqrt(x2 +y2) * without intermediate overflow or underflow * @since 1.5 */ public static double hypot(double x, double y) { return StrictMath.hypot(x, y); } /** * Returns ex -1. Note that for values of * x near 0, the exact sum of * {@code expm1(x)} + 1 is much closer to the true * result of ex than {@code exp(x)}. * *
Special cases: *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. The result of * {@code expm1} for any finite input must be greater than or * equal to {@code -1.0}. Note that once the exact result of * e{@code x} - 1 is within 1/2 * ulp of the limit value -1, {@code -1.0} should be * returned. * * @param x the exponent to raise e to in the computation of * e{@code x} -1. * @return the value e{@code x} - 1. * @since 1.5 */ public static double expm1(double x) { return StrictMath.expm1(x); } /** * Returns the natural logarithm of the sum of the argument and 1. * Note that for small values {@code x}, the result of * {@code log1p(x)} is much closer to the true result of ln(1 * + {@code x}) than the floating-point evaluation of * {@code log(1.0+x)}. * *
Special cases: * *
The computed result must be within 1 ulp of the exact result. * Results must be semi-monotonic. * * @param x a value * @return the value ln({@code x} + 1), the natural * log of {@code x} + 1 * @since 1.5 */ public static double log1p(double x) { return StrictMath.log1p(x); } /** * Returns the first floating-point argument with the sign of the * second floating-point argument. Note that unlike the {@link * StrictMath#copySign(double, double) StrictMath.copySign} * method, this method does not require NaN {@code sign} * arguments to be treated as positive values; implementations are * permitted to treat some NaN arguments as positive and other NaN * arguments as negative to allow greater performance. * * @param magnitude the parameter providing the magnitude of the result * @param sign the parameter providing the sign of the result * @return a value with the magnitude of {@code magnitude} * and the sign of {@code sign}. * @since 1.6 */ public static double copySign(double magnitude, double sign) { return Double.longBitsToDouble((Double.doubleToRawLongBits(sign) & (DoubleConsts.SIGN_BIT_MASK)) | (Double.doubleToRawLongBits(magnitude) & (DoubleConsts.EXP_BIT_MASK | DoubleConsts.SIGNIF_BIT_MASK))); } /** * Returns the first floating-point argument with the sign of the * second floating-point argument. Note that unlike the {@link * StrictMath#copySign(float, float) StrictMath.copySign} * method, this method does not require NaN {@code sign} * arguments to be treated as positive values; implementations are * permitted to treat some NaN arguments as positive and other NaN * arguments as negative to allow greater performance. * * @param magnitude the parameter providing the magnitude of the result * @param sign the parameter providing the sign of the result * @return a value with the magnitude of {@code magnitude} * and the sign of {@code sign}. * @since 1.6 */ public static float copySign(float magnitude, float sign) { return Float.intBitsToFloat((Float.floatToRawIntBits(sign) & (FloatConsts.SIGN_BIT_MASK)) | (Float.floatToRawIntBits(magnitude) & (FloatConsts.EXP_BIT_MASK | FloatConsts.SIGNIF_BIT_MASK))); } /** * Returns the unbiased exponent used in the representation of a * {@code float}. Special cases: * *
* Special cases: *
* Special cases: *
Special Cases: *
Special Cases: *
Special Cases: *
Special Cases: *
Special cases: *
Special cases: *