/*

* Copyright (c) 1994, 2021, 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.vm.annotation.IntrinsicCandidate;

/**

* The class {@code Math} contains methods for performing basic

* numeric operations such as the elementary exponential, logarithm,

* square root, and trigonometric functions.

*

* <p>Unlike some of the numeric methods of class

* {@link java.lang.StrictMath 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.

*

* <p>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}.

*

* <p>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 <i>ulps</i>, 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 <i>correctly

* rounded</i>. 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

* <i>semi-monotonic</i>: 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.

*

* <p>

* 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 whose names end with

* {@code Exact} throw an {@code ArithmeticException} when the results overflow.

*

* <h2><a id=Ieee754RecommendedOps>IEEE 754 Recommended

* Operations</a></h2>

*

* The 2019 revision of the IEEE 754 floating-point standard includes

* a section of recommended operations and the semantics of those

* operations if they are included in a programming environment. The

* recommended operations present in this class include {@link sin

* sin}, {@link cos cos}, {@link tan tan}, {@link asin asin}, {@link

* acos acos}, {@link atan atan}, {@link exp exp}, {@link expm1

* expm1}, {@link log log}, {@link log10 log10}, {@link log1p log1p},

* {@link sinh sinh}, {@link cosh cosh}, {@link tanh tanh}, {@link

* hypot hypot}, and {@link pow pow}. (The {@link sqrt sqrt}

* operation is a required part of IEEE 754 from a different section

* of the standard.) The special case behavior of the recommended

* operations generally follows the guidance of the IEEE 754

* standard. However, the {@code pow} method defines different

* behavior for some arguments, as noted in its {@linkplain pow

* specification}. The IEEE 754 standard defines its operations to be

* correctly rounded, which is a more stringent quality of

* implementation condition than required for most of the methods in

* question that are also included in this class.

*

* @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

* <i>e</i>, the base of the natural logarithms.

*/

public static final double E = 2.7182818284590452354;

/**

* The {@code double} value that is closer than any other to

* <i>pi</i>, 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:

* <ul><li>If the argument is NaN or an infinity, then the

* result is NaN.

* <li>If the argument is zero, then the result is a zero with the

* same sign as the argument.</ul>

*

* <p>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.

*/

@IntrinsicCandidate

public static double sin(double a) {

return StrictMath.sin(a); // default impl. delegates to StrictMath

}

/**

* Returns the trigonometric cosine of an angle. Special cases:

* <ul><li>If the argument is NaN or an infinity, then the

* result is NaN.

* <li>If the argument is zero, then the result is {@code 1.0}.

*</ul>

*

* <p>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.

*/

@IntrinsicCandidate

public static double cos(double a) {

return StrictMath.cos(a); // default impl. delegates to StrictMath

}

/**

* Returns the trigonometric tangent of an angle. Special cases:

* <ul><li>If the argument is NaN or an infinity, then the result

* is NaN.

* <li>If the argument is zero, then the result is a zero with the

* same sign as the argument.</ul>

*

* <p>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.

*/

@IntrinsicCandidate

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 -<i>pi</i>/2 through <i>pi</i>/2. Special cases:

* <ul><li>If the argument is NaN or its absolute value is greater

* than 1, then the result is NaN.

* <li>If the argument is zero, then the result is a zero with the

* same sign as the argument.</ul>

*

* <p>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 <i>pi</i>. Special case:

* <ul><li>If the argument is NaN or its absolute value is greater

* than 1, then the result is NaN.

* <li>If the argument is {@code 1.0}, the result is positive zero.

* </ul>

*

* <p>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 -<i>pi</i>/2 through <i>pi</i>/2. Special cases:

* <ul><li>If the argument is NaN, then the result is NaN.

* <li>If the argument is zero, then the result is a zero with the

* same sign as the argument.

* <li>If the argument is {@linkplain Double#isInfinite infinite},

* then the result is the closest value to <i>pi</i>/2 with the

* same sign as the input.

* </ul>

*

* <p>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

* <i>not</i> 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 <i>e</i> raised to the power of a

* {@code double} value. Special cases:

* <ul><li>If the argument is NaN, the result is NaN.

* <li>If the argument is positive infinity, then the result is

* positive infinity.

* <li>If the argument is negative infinity, then the result is

* positive zero.

* <li>If the argument is zero, then the result is {@code 1.0}.

* </ul>

*

* <p>The computed result must be within 1 ulp of the exact result.

* Results must be semi-monotonic.

*

* @param a the exponent to raise <i>e</i> to.

* @return the value <i>e</i>^{{@code a}},

* where <i>e</i> is the base of the natural logarithms.

*/

@IntrinsicCandidate

public static double exp(double a) {

return StrictMath.exp(a); // default impl. delegates to StrictMath

}

/**

* Returns the natural logarithm (base <i>e</i>) of a {@code double}

* value. Special cases:

* <ul><li>If the argument is NaN or less than zero, then the result

* is NaN.

* <li>If the argument is positive infinity, then the result is

* positive infinity.

* <li>If the argument is positive zero or negative zero, then the

* result is negative infinity.

* <li>If the argument is {@code 1.0}, then the result is positive

* zero.

* </ul>

*

* <p>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&nbsp;{@code a}, the natural logarithm of

* {@code a}.

*/

@IntrinsicCandidate

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:

*

* <ul><li>If the argument is NaN or less than zero, then the result

* is NaN.

* <li>If the argument is positive infinity, then the result is

* positive infinity.

* <li>If the argument is positive zero or negative zero, then the

* result is negative infinity.

* <li>If the argument is equal to 10^<i>n</i> for

* integer <i>n</i>, then the result is <i>n</i>. In particular,

* if the argument is {@code 1.0} (10⁰), then the

* result is positive zero.

* </ul>

*

* <p>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

*/

@IntrinsicCandidate

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:

* <ul><li>If the argument is NaN or less than zero, then the result

* is NaN.

* <li>If the argument is positive infinity, then the result is positive

* infinity.

* <li>If the argument is positive zero or negative zero, then the

* result is the same as the argument.</ul>

* Otherwise, the result is the {@code double} value closest to

* the true mathematical square root of the argument value.

*

* @param a a value.

* @return the positive square root of {@code a}.

* If the argument is NaN or less than zero, the result is NaN.

*/

@IntrinsicCandidate

public static double sqrt(double a) {

return StrictMath.sqrt(a); // default impl. delegates to StrictMath

// Note that hardware sqrt instructions

// frequently can be directly used by JITs

// and should be much faster than doing

// Math.sqrt in software.

}

/**

* Returns the cube root of a {@code double} value. For

* positive finite {@code x}, {@code cbrt(-x) ==

* -cbrt(x)}; that is, the cube root of a negative value is

* the negative of the cube root of that value's magnitude.

*

* Special cases:

*

* <ul>

*

* <li>If the argument is NaN, then the result is NaN.

*

* <li>If the argument is infinite, then the result is an infinity

* with the same sign as the argument.

*

* <li>If the argument is zero, then the result is a zero with the

* same sign as the argument.

*

* </ul>

*

* <p>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

* <code>f1&nbsp;-&nbsp;f2</code>&nbsp;&times;&nbsp;<i>n</i>,

* where <i>n</i> 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 <i>n</i> 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:

* <ul><li>If either argument is NaN, or the first argument is infinite,

* or the second argument is positive zero or negative zero, then the

* result is NaN.

* <li>If the first argument is finite and the second argument is

* infinite, then the result is the same as the first argument.</ul>

*

* @param f1 the dividend.

* @param f2 the divisor.

* @return the remainder when {@code f1} is divided by

* {@code f2}.

*/

public static double IEEEremainder(double f1, double f2) {

return StrictMath.IEEEremainder(f1, f2); // delegate to StrictMath

}

/**

* Returns the smallest (closest to negative infinity)

* {@code double} value that is greater than or equal to the

* argument and is equal to a mathematical integer. Special cases:

* <ul><li>If the argument value is already equal to a

* mathematical integer, then the result is the same as the

* argument. <li>If the argument is NaN or an infinity or

* positive zero or negative zero, then the result is the same as

* the argument. <li>If the argument value is less than zero but

* greater than -1.0, then the result is negative zero.</ul> Note

* that the value of {@code Math.ceil(x)} is exactly the

* value of {@code -Math.floor(-x)}.

*

*

* @param a a value.

* @return the smallest (closest to negative infinity)

* floating-point value that is greater than or equal to

* the argument and is equal to a mathematical integer.

*/

@IntrinsicCandidate

public static double ceil(double a) {

return StrictMath.ceil(a); // default impl. delegates to StrictMath

}

/**

* Returns the largest (closest to positive infinity)

* {@code double} value that is less than or equal to the

* argument and is equal to a mathematical integer. Special cases:

* <ul><li>If the argument value is already equal to a

* mathematical integer, then the result is the same as the

* argument. <li>If the argument is NaN or an infinity or

* positive zero or negative zero, then the result is the same as

* the argument.</ul>

*

* @param a a value.

* @return the largest (closest to positive infinity)

* floating-point value that less than or equal to the argument

* and is equal to a mathematical integer.

*/

@IntrinsicCandidate

public static double floor(double a) {

return StrictMath.floor(a); // default impl. delegates to StrictMath

}

/**

* Returns the {@code double} value that is closest in value

* to the argument and is equal to a mathematical integer. If two

* {@code double} values that are mathematical integers are

* equally close, the result is the integer value that is

* even. Special cases:

* <ul><li>If the argument value is already equal to a mathematical

* integer, then the result is the same as the argument.

* <li>If the argument is NaN or an infinity or positive zero or negative

* zero, then the result is the same as the argument.</ul>

*

* @param a a {@code double} value.

* @return the closest floating-point value to {@code a} that is

* equal to a mathematical integer.

*/

@IntrinsicCandidate

public static double rint(double a) {

return StrictMath.rint(a); // default impl. delegates to StrictMath

}

/**

* Returns the angle <i>theta</i> from the conversion of rectangular

* coordinates ({@code x},&nbsp;{@code y}) to polar

* coordinates (r,&nbsp;<i>theta</i>).

* This method computes the phase <i>theta</i> by computing an arc tangent

* of {@code y/x} in the range of -<i>pi</i> to <i>pi</i>. Special

* cases:

* <ul><li>If either argument is NaN, then the result is NaN.

* <li>If the first argument is positive zero and the second argument

* is positive, or the first argument is positive and finite and the

* second argument is positive infinity, then the result is positive

* zero.

* <li>If the first argument is negative zero and the second argument

* is positive, or the first argument is negative and finite and the

* second argument is positive infinity, then the result is negative zero.

* <li>If the first argument is positive zero and the second argument

* is negative, or the first argument is positive and finite and the

* second argument is negative infinity, then the result is the

* {@code double} value closest to <i>pi</i>.

* <li>If the first argument is negative zero and the second argument

* is negative, or the first argument is negative and finite and the

* second argument is negative infinity, then the result is the

* {@code double} value closest to -<i>pi</i>.

* <li>If the first argument is positive and the second argument is

* positive zero or negative zero, or the first argument is positive

* infinity and the second argument is finite, then the result is the

* {@code double} value closest to <i>pi</i>/2.

* <li>If the first argument is negative and the second argument is

* positive zero or negative zero, or the first argument is negative

* infinity and the second argument is finite, then the result is the

* {@code double} value closest to -<i>pi</i>/2.

* <li>If both arguments are positive infinity, then the result is the

* {@code double} value closest to <i>pi</i>/4.

* <li>If the first argument is positive infinity and the second argument

* is negative infinity, then the result is the {@code double}

* value closest to 3*<i>pi</i>/4.

* <li>If the first argument is negative infinity and the second argument

* is positive infinity, then the result is the {@code double} value

* closest to -<i>pi</i>/4.

* <li>If both arguments are negative infinity, then the result is the

* {@code double} value closest to -3*<i>pi</i>/4.</ul>

*

* <p>The computed result must be within 2 ulps of the exact result.

* Results must be semi-monotonic.

*

* @apiNote

* For <i>y</i> with a positive sign and finite nonzero

* <i>x</i>, the exact mathematical value of {@code atan2} is

* equal to:

* <ul>

* <li>If <i>x</i> {@literal >} 0, atan(abs(<i>y</i>/<i>x</i>))

* <li>If <i>x</i> {@literal <} 0, &pi; - atan(abs(<i>y</i>/<i>x</i>))

* </ul>

*

* @param y the ordinate coordinate

* @param x the abscissa coordinate

* @return the <i>theta</i> component of the point

* (<i>r</i>,&nbsp;<i>theta</i>)

* in polar coordinates that corresponds to the point

* (<i>x</i>,&nbsp;<i>y</i>) in Cartesian coordinates.

*/

@IntrinsicCandidate

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:

*

* <ul><li>If the second argument is positive or negative zero, then the

* result is 1.0.

* <li>If the second argument is 1.0, then the result is the same as the

* first argument.

* <li>If the second argument is NaN, then the result is NaN.

* <li>If the first argument is NaN and the second argument is nonzero,

* then the result is NaN.

*

* <li>If

* <ul>

* <li>the absolute value of the first argument is greater than 1

* and the second argument is positive infinity, or

* <li>the absolute value of the first argument is less than 1 and

* the second argument is negative infinity,

* </ul>

* then the result is positive infinity.

*

* <li>If

* <ul>

* <li>the absolute value of the first argument is greater than 1 and

* the second argument is negative infinity, or

* <li>the absolute value of the

* first argument is less than 1 and the second argument is positive

* infinity,

* </ul>

* then the result is positive zero.

*

* <li>If the absolute value of the first argument equals 1 and the

* second argument is infinite, then the result is NaN.

*

* <li>If

* <ul>

* <li>the first argument is positive zero and the second argument

* is greater than zero, or

* <li>the first argument is positive infinity and the second

* argument is less than zero,

* </ul>

* then the result is positive zero.

*

* <li>If

* <ul>

* <li>the first argument is positive zero and the second argument

* is less than zero, or

* <li>the first argument is positive infinity and the second

* argument is greater than zero,

* </ul>

* then the result is positive infinity.

*

* <li>If

* <ul>

* <li>the first argument is negative zero and the second argument

* is greater than zero but not a finite odd integer, or

* <li>the first argument is negative infinity and the second

* argument is less than zero but not a finite odd integer,

* </ul>

* then the result is positive zero.

*

* <li>If

* <ul>

* <li>the first argument is negative zero and the second argument

* is a positive finite odd integer, or

* <li>the first argument is negative infinity and the second

* argument is a negative finite odd integer,

* </ul>

* then the result is negative zero.

*

* <li>If

* <ul>

* <li>the first argument is negative zero and the second argument

* is less than zero but not a finite odd integer, or

* <li>the first argument is negative infinity and the second

* argument is greater than zero but not a finite odd integer,

* </ul>

* then the result is positive infinity.

*

* <li>If

* <ul>

* <li>the first argument is negative zero and the second argument

* is a negative finite odd integer, or

* <li>the first argument is negative infinity and the second

* argument is a positive finite odd integer,

* </ul>

* then the result is negative infinity.

*

* <li>If the first argument is finite and less than zero

* <ul>

* <li> if the second argument is a finite even integer, the

* result is equal to the result of raising the absolute value of

* the first argument to the power of the second argument

*

* <li>if the second argument is a finite odd integer, the result

* is equal to the negative of the result of raising the absolute

* value of the first argument to the power of the second

* argument

*

* <li>if the second argument is finite and not an integer, then

* the result is NaN.

* </ul>

*

* <li>If both arguments are integers, then the result is exactly equal

* to the mathematical result of raising the first argument to the power

* of the second argument if that result can in fact be represented

* exactly as a {@code double} value.</ul>

*

* <p>(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.)

*

* <p>The computed result must be within 1 ulp of the exact result.

* Results must be semi-monotonic.

*

* @apiNote

* The special cases definitions of this method differ from the

* special case definitions of the IEEE 754 recommended {@code

* pow} operation for &plusmn;{@code 1.0} raised to an infinite

* power. This method treats such cases as indeterminate and

* specifies a NaN is returned. The IEEE 754 specification treats

* the infinite power as a large integer (large-magnitude

* floating-point numbers are numerically integers, specifically

* even integers) and therefore specifies {@code 1.0} be returned.

*

* @param a the base.

* @param b the exponent.

* @return the value {@code a}^{{@code b}}.

*/

@IntrinsicCandidate

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.

*

* <p>

* Special cases:

* <ul><li>If the argument is NaN, the result is 0.

* <li>If the argument is negative infinity or any value less than or

* equal to the value of {@code Integer.MIN_VALUE}, the result is

* equal to the value of {@code Integer.MIN_VALUE}.

* <li>If the argument is positive infinity or any value greater than or

* equal to the value of {@code Integer.MAX_VALUE}, the result is

* equal to the value of {@code Integer.MAX_VALUE}.</ul>

*

* @param a a floating-point value to be rounded to an integer.

* @return the value of the argument rounded to the nearest

* {@code int} value.

* @see java.lang.Integer#MAX_VALUE

* @see java.lang.Integer#MIN_VALUE

*/

public static int round(float a) {

int intBits = Float.floatToRawIntBits(a);

int biasedExp = (intBits & FloatConsts.EXP_BIT_MASK)

>> (FloatConsts.SIGNIFICAND_WIDTH - 1);

int shift = (FloatConsts.SIGNIFICAND_WIDTH - 2

+ FloatConsts.EXP_BIAS) - biasedExp;

if ((shift & -32) == 0) { // shift >= 0 && shift < 32

// a is a finite number such that pow(2,-32) <= ulp(a) < 1

int r = ((intBits & FloatConsts.SIGNIF_BIT_MASK)

| (FloatConsts.SIGNIF_BIT_MASK + 1));

if (intBits < 0) {

r = -r;

}

// In the comments below each Java expression evaluates to the value

// the corresponding mathematical expression:

// (r) evaluates to a / ulp(a)

// (r >> shift) evaluates to floor(a * 2)

// ((r >> shift) + 1) evaluates to floor((a + 1/2) * 2)

// (((r >> shift) + 1) >> 1) evaluates to floor(a + 1/2)

return ((r >> shift) + 1) >> 1;

} else {

// a is either

// - a finite number with abs(a) < exp(2,FloatConsts.SIGNIFICAND_WIDTH-32) < 1/2

// - a finite number with ulp(a) >= 1 and hence a is a mathematical integer

// - an infinity or NaN

return (int) a;

}

}

/**

* Returns the closest {@code long} to the argument, with ties

* rounding to positive infinity.

*

* <p>Special cases:

* <ul><li>If the argument is NaN, the result is 0.

* <li>If the argument is negative infinity or any value less than or

* equal to the value of {@code Long.MIN_VALUE}, the result is

* equal to the value of {@code Long.MIN_VALUE}.

* <li>If the argument is positive infinity or any value greater than or

* equal to the value of {@code Long.MAX_VALUE}, the result is

* equal to the value of {@code Long.MAX_VALUE}.</ul>

*

* @param a a floating-point value to be rounded to a

* {@code long}.

* @return the value of the argument rounded to the nearest

* {@code long} value.

* @see java.lang.Long#MAX_VALUE

* @see java.lang.Long#MIN_VALUE

*/

public static long round(double a) {

long longBits = Double.doubleToRawLongBits(a);

long biasedExp = (longBits & DoubleConsts.EXP_BIT_MASK)

>> (DoubleConsts.SIGNIFICAND_WIDTH - 1);

long shift = (DoubleConsts.SIGNIFICAND_WIDTH - 2

+ DoubleConsts.EXP_BIAS) - biasedExp;

if ((shift & -64) == 0) { // shift >= 0 && shift < 64

// a is a finite number such that pow(2,-64) <= ulp(a) < 1

long r = ((longBits & DoubleConsts.SIGNIF_BIT_MASK)

| (DoubleConsts.SIGNIF_BIT_MASK + 1));

if (longBits < 0) {

r = -r;

}

// In the comments below each Java expression evaluates to the value

// the corresponding mathematical expression:

// (r) evaluates to a / ulp(a)

// (r >> shift) evaluates to floor(a * 2)

// ((r >> shift) + 1) evaluates to floor((a + 1/2) * 2)

// (((r >> shift) + 1) >> 1) evaluates to floor(a + 1/2)

return ((r >> shift) + 1) >> 1;

} else {

// a is either

// - a finite number with abs(a) < exp(2,DoubleConsts.SIGNIFICAND_WIDTH-64) < 1/2

// - a finite number with ulp(a) >= 1 and hence a is a mathematical integer

// - an infinity or NaN

return (long) a;

}

}

private static final class RandomNumberGeneratorHolder {

static final Random randomNumberGenerator = new Random();

}

/**

* Returns a {@code double} value with a positive sign, greater

* than or equal to {@code 0.0} and less than {@code 1.0}.

* Returned values are chosen pseudorandomly with (approximately)

* uniform distribution from that range.

*

* <p>When this method is first called, it creates a single new

* pseudorandom-number generator, exactly as if by the expression

*

* <blockquote>{@code new java.util.Random()}</blockquote>

*

* This new pseudorandom-number generator is used thereafter for

* all calls to this method and is used nowhere else.

*

* <p>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

*

* <blockquote><pre>{@code

* double f = Math.random()/Math.nextDown(1.0);

* double x = x1*(1.0 - f) + x2*f;

* }</pre></blockquote>

*

* @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

*/

@IntrinsicCandidate

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

*/

@IntrinsicCandidate

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

*/

@IntrinsicCandidate

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 from 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

*/

@IntrinsicCandidate

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 from 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

*/

@IntrinsicCandidate

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 9

*/

public static long multiplyExact(long x, int y) {

return multiplyExact(x, (long)y);

}

/**

* 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

*/

@IntrinsicCandidate

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");

}