Class MathFunctions

• Field Summary

Fields
Modifier and Type Field Description
`static int` `HIGHEST_SUPPORTED_PRIME_NUMBER`
The highest prime number supported by the `next­Prime­Number(int)` method.
`static double` `LOG10_2`
The logarithm of 2 in base 10, which is approximated by 0.3010299956639812.
`static int` `MAX_NAN_ORDINAL`
The maximal ordinal value for `Na­N` numbers created by `to­Nan­Float(int)`.
`static int` `MIN_NAN_ORDINAL`
The minimal ordinal value for `Na­N` numbers created by `to­Nan­Float(int)`.
`static double` `SQRT_2`
The square root of 2, which is approximated by 1.4142135623730951.
• Method Summary

All Methods
Modifier and Type Method Description
`static double` `acosh​(double x)`
Returns the inverse hyperbolic cosine of the given value.
`static double` `asinh​(double x)`
Returns the inverse hyperbolic sine of the given value.
`static double` `atanh​(double x)`
Returns the inverse hyperbolic tangent of the given value.
`static int[]` `commonDivisors​(int... numbers)`
Returns the positive divisors which are common to all the specified numbers.
`static int[]` `divisors​(int number)`
Returns the divisors of the specified number as positive integers.
`static boolean` ```epsilonEqual​(double v1, double v2, double ε)```
Returns `true` if the given values are equal or if their difference is not greater than the given threshold.
`static boolean` ```epsilonEqual​(float v1, float v2, float ε)```
Returns `true` if the given values are equal or if their difference is not greater than the given threshold.
`static int` `getExponent​(double value)`
Returns the unbiased exponent used in the representation of a `double`, with correction for sub-normal numbers.
`static boolean` `isNegative​(double value)`
Returns `true` if the given value is negative, including negative zero.
`static boolean` `isNegativeZero​(double value)`
Returns `true` if the given value is the negative zero (`-0.0`).
`static boolean` `isPositive​(double value)`
Returns `true` if the given value is positive, excluding negative zero.
`static boolean` `isPositiveZero​(double value)`
Returns `true` if the given value is the positive zero (`+0.0`).
`static boolean` ```isSameSign​(double v1, double v2)```
Returns `true` if the given values have the same sign, differentiating positive and negative zeros.
`static double` `magnitude​(double... vector)`
Returns the magnitude of the given vector.
`static int` `nextPrimeNumber​(int number)`
Returns the first prime number equals or greater than the given value.
`static double[]` `polynomialRoots​(double... coefficients)`
Returns the real (non-complex) roots of a polynomial equation having the given coefficients.
`static long` ```pow​(long base, int exponent)```
Computes the result of `base` argument raised to the power given by `exponent` argument.
`static double` `pow10​(double x)`
Computes 10 raised to the power of x.
`static double` `pow10​(int x)`
Computes 10 raised to the power of x.
`static double` ```quadrupleToDouble​(long l0, long l1)```
Converts two long bits values containing a IEEE 754 quadruple precision floating point number to a double precision floating point number.
`static float` `toNanFloat​(int ordinal)`
Returns a NaN number for the specified ordinal value.
`static int` `toNanOrdinal​(float value)`
Returns the ordinal value of the given NaN number.
`static double` `truncate​(double value)`
Truncates the given value toward zero.
`static double` ```xorSign​(double value, double sign)```
Returns the first floating-point argument with the sign reversed if the second floating-point argument is negative.
• Methods inherited from class Object

`clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait`
• Method Detail

• truncate

`public static double truncate​(double value)`
Truncates the given value toward zero. Invoking this method is equivalent to invoking `Math​.floor(double)` if the value is positive, or `Math​.ceil(double)` if the value is negative.
Parameters:
`value` - the value to truncate.
Returns:
the largest in magnitude (further from zero) integer value which is equals or less in magnitude than the given value.
• magnitude

`public static double magnitude​(double... vector)`
Returns the magnitude of the given vector. This is defined by:
`sqrt(vector[0]² + vector[1]² + … + vector[length-1]²)`
If the given vector contains a NaN value, then the result is NaN.
Implementation note
In the special case where only one element is different than zero, this method returns directly the absolute value of that element without computing `sqrt(v²)`, in order to avoid rounding error. This special case has been implemented because this method is often invoked for computing the length of offset vectors, typically aligned with the axes of a Cartesian coordinate system.
Parameters:
`vector` - the vector for which to compute the magnitude.
Returns:
the magnitude of the given vector as a positive number, of NaN.
`Math​.hypot(double, double)`
• getExponent

`public static int getExponent​(double value)`
Returns the unbiased exponent used in the representation of a `double`, with correction for sub-normal numbers. This method is related to `Math​.get­Exponent(double)` in the following ways:
• For NaN and all values equal or greater than `Double​.MIN_NORMAL` in magnitude (including infinities), this method returns results that are identical to `Math​.get­Exponent(double)`.
• For values smaller than `Double​.MIN_NORMAL` in magnitude (including zero), the correction for sub-normal numbers results in return values smaller than what `Math​.get­Exponent(double)` would return.
Special cases:
Identities
For any p values in the [-1075 … 1024] range and value = 2p:
• `get­Exponent(Math​.scalb(1.0, p)) == p`
• `Math​.scalb(1.0, get­Exponent(value)) == value`
• `Math​.floor(LOG10_2 * get­Exponent(value)) == Math​.floor(Math​.log10(value))`
Parameters:
`value` - the value for which to get the exponent.
Returns:
the unbiased exponent, corrected for sub-normal numbers if needed. Values will be in the [-1075 … 1024] range, inclusive.
Since:
0.4
`Math​.get­Exponent(double)`, `Math​.scalb(double, int)`
• pow

```public static long pow​(long base,
int exponent)```
Computes the result of `base` argument raised to the power given by `exponent` argument. This method computes the same value than `Math​.pow(double, double)` but using only integer arithmetic. The result must be representable as a 64 bits integers (`long` primitive type), otherwise an `Arithmetic­Exception` is thrown. The result is guaranteed exact, in contrast to results represented as `double` floating point values which may be approximate for magnitudes greater than 252. This method may also be faster.
Implementation note: this method uses exponentiation by squaring technic.
The type of the `base` argument is `long` for convenience, since this method is used in contexts where relatively large integers are handled. However any value greater than the capacity of `int` type is guaranteed to fail with `Arithmetic­Exception` unless `exponent` is 0 or 1. Likewise any `exponent` value greater than 62 is guaranteed to fail unless `base` is 0 or 1.
Parameters:
`base` - the value to raise to an exponent.
`exponent` - the exponent, as zero or positive number.
Returns:
the value baseexponent as a 64 bits integer.
Throws:
`Arithmetic­Exception` - if the given exponent is negative, or if the result overflow integer arithmetic.
Since:
1.0
`Math​.pow(double, double)`
• pow10

`public static double pow10​(int x)`
Computes 10 raised to the power of x. This method is faster and slightly more accurate than invoking `Math​.pow(10, x)`.
Note: This method has been defined because the standard `Math​.pow(10, x)` method does not always return the closest IEEE floating point representation. Slight departures (1 or 2 ULP) are often allowed in math functions for performance reasons. The most accurate calculations are usually not necessary, but the base 10 is a special case since it is used for scaling axes or formatting human-readable output.
Special cases:
• If x is equals or lower than -324, then the result is 0.
• If x is equals or greater than 309, then the result is positive infinity.
• If x is in the [0 … 18] range inclusive, then the result is exact.
• For all other x values, the result is the closest IEEE 754 approximation.
Parameters:
`x` - the exponent.
Returns:
10 raised to the given exponent.
`pow10(double)`, `LOG10_2`, `Decimal­Functions`
• asinh

`public static double asinh​(double x)`
Returns the inverse hyperbolic sine of the given value. This is the inverse of the `Math​.sinh(double)` method.
Parameters:
`x` - the value for which to compute the inverse hyperbolic sine.
Returns:
the inverse hyperbolic sine of the given value.
Since:
0.6
`Math​.sinh(double)`
• acosh

`public static double acosh​(double x)`
Returns the inverse hyperbolic cosine of the given value. This is the inverse of the `Math​.cosh(double)` method.
Parameters:
`x` - the value for which to compute the inverse hyperbolic cosine.
Returns:
the inverse hyperbolic cosine of the given value.
Since:
0.6
`Math​.cosh(double)`
• atanh

`public static double atanh​(double x)`
Returns the inverse hyperbolic tangent of the given value. This is the inverse of the `Math​.tanh(double)` method. The range of input values shall be in the [-1 … 1]. Special cases:
Parameters:
`x` - the value for which to compute the inverse hyperbolic tangent.
Returns:
the inverse hyperbolic tangent of the given value.
`Math​.tanh(double)`
• isPositive

`public static boolean isPositive​(double value)`
Returns `true` if the given value is positive, excluding negative zero. Special cases:
• If the value is `+0.0`, returns `true`
• If the value is `-0.0`, returns `false`
• If the value is `Na­N`, returns `false`
As seen from the above cases, this method distinguishes positive zero from negative zero. The handling of zero values is the difference between invoking `is­Positive(double)` and testing if (value >= 0).
Parameters:
`value` - the value to test.
Returns:
`true` if the given value is positive, excluding negative zero.
`is­Positive­Zero(double)`, `is­Negative(double)`
• isPositiveZero

`public static boolean isPositiveZero​(double value)`
Returns `true` if the given value is the positive zero (`+0.0`). This method returns `false` for the negative zero (`-0.0`). This method is equivalent to the following code, but potentially faster:
`return (value == 0) && isPositive(value);`
Parameters:
`value` - the value to test.
Returns:
`true` if the given value is +0.0 (not -0.0).
Since:
0.4
`is­Positive(double)`, `is­Negative­Zero(double)`
• isNegative

`public static boolean isNegative​(double value)`
Returns `true` if the given value is negative, including negative zero. Special cases:
• If the value is `+0.0`, returns `false`
• If the value is `-0.0`, returns `true`
• If the value is `Na­N`, returns `false`
As seen from the above cases, this method distinguishes positive zero from negative zero. The handling of zero values is the difference between invoking `is­Negative(double)` and testing if (value < 0).
Parameters:
`value` - the value to test.
Returns:
`true` if the given value is negative, including negative zero.
`is­Negative­Zero(double)`, `is­Positive(double)`
• isNegativeZero

`public static boolean isNegativeZero​(double value)`
Returns `true` if the given value is the negative zero (`-0.0`). This method returns `false` for the positive zero (`+0.0`). This method is equivalent to the following code, but potentially faster:
`return (value == 0) && isNegative(value);`
Parameters:
`value` - the value to test.
Returns:
`true` if the given value is -0.0 (not +0.0).
Since:
0.4
`is­Negative(double)`, `is­Positive­Zero(double)`
• isSameSign

```public static boolean isSameSign​(double v1,
double v2)```
Returns `true` if the given values have the same sign, differentiating positive and negative zeros. Special cases:
• `+0.0` and `-0.0` are considered to have opposite sign
• If any value is `Na­N`, returns `false`
Parameters:
`v1` - the first value.
`v2` - the second value, to compare the sign with the first value.
Returns:
`true` if the given values are not NaN and have the same sign.
`Math​.signum(double)`
• xorSign

```public static double xorSign​(double value,
double sign)```
Returns the first floating-point argument with the sign reversed if the second floating-point argument is negative. This method is similar to `Math​.copy­Sign(value, sign)` except that the sign is combined with an exclusive or operation instead than being copied.

This method makes no guarantee about whether `Na­N` values are handled as positive or negative numbers. This is the same policy than `Math​.copy­Sign(double, double)`.

Parameters:
`value` - the parameter providing the value that may need a sign change.
`sign` - the parameter providing the sign to xor with the value.
Returns:
the provided value with its sign reversed if the `sign` parameter is negative.
`Math​.copy­Sign(double, double)`
• epsilonEqual

```public static boolean epsilonEqual​(float v1,
float v2,
float ε)```
Returns `true` if the given values are equal or if their difference is not greater than the given threshold. More specifically:
• If both values are positive infinity, or if both values are negative infinity, then this method returns `true`.
• If both values are NaN, then this method returns `true`. Note that this method does not differentiate the various NaN values.
• Otherwise, this method returns the result of the `abs(v1 - v2) <= ε` comparison.
Parameters:
`v1` - the first value to compare.
`v2` - the second value to compare.
`\u03b5` - the tolerance threshold, which must be positive.
Returns:
`true` if both values are equal given the tolerance threshold.
• epsilonEqual

```public static boolean epsilonEqual​(double v1,
double v2,
double ε)```
Returns `true` if the given values are equal or if their difference is not greater than the given threshold. More specifically:
• If both values are positive infinity, or if both values are negative infinity, then this method returns `true`.
• If both values are NaN, then this method returns `true`. Note that this method does not differentiate the various NaN values.
• Otherwise, this method returns the result of the `abs(v1 - v2) <= ε` comparison.
Parameters:
`v1` - the first value to compare.
`v2` - the second value to compare.
`\u03b5` - the tolerance threshold, which must be positive.
Returns:
`true` if both values are equal given the tolerance threshold.
• toNanFloat

```public static float toNanFloat​(int ordinal)
throws IllegalArgumentException```
Returns a NaN number for the specified ordinal value. Valid NaN numbers in Java can have bit fields in the ranges listed below:
• [`0x7F800001``0x7FFFFFFF`], with `0x7FC00000` as the bit fields of the standard `Float​.Na­N` value
• [`0x­FF800001``0x­FFFFFFFF`]
Some of those bits, named the payload, can be used for storing custom information. This method maps some of the payload values to each ordinal value.

This method guarantees that `to­Nan­Float(0)` returns the standard `Float​.Na­N` value. For all other `ordinal` values, the relationship to the payload values is implementation dependent and may change in any future version of the SIS library. The current implementation restricts the range of allowed ordinal values to a smaller one than the range of all possible values.

Parameters:
`ordinal` - the NaN ordinal value, from -2097152 to 2097151 inclusive.
Returns:
one of the legal NaN values as a float.
Throws:
`Illegal­Argument­Exception` - if the specified ordinal is out of range.
`Float​.int­Bits­To­Float(int)`
• toNanOrdinal

```public static int toNanOrdinal​(float value)
throws IllegalArgumentException```
Returns the ordinal value of the given NaN number. This method is the converse of `to­Nan­Float(int)`.

If the given float is the standard `Float​.Na­N` value, then this method returns 0. For all other values, the relationship between the float payload and the returned ordinal is implementation dependent and may change in any future Apache SIS version.

Parameters:
`value` - the value from which to get the NaN ordinal value.
Returns:
the NaN ordinal value of the given floating point value.
Throws:
`Illegal­Argument­Exception` - if the given value is not a NaN value, or does not use a supported bits pattern.

```public static double quadrupleToDouble​(long l0,
long l1)```
Converts two long bits values containing a IEEE 754 quadruple precision floating point number to a double precision floating point number. About 17 decimal digits of precision may be lost due to the `double` type having only half the capacity of quadruple precision type.

Some quadruple precision values can not be represented in double precision and are mapped to `double` values as below:

Parameters:
`l0` - upper part of the quadruple precision floating point number.
`l1` - lower part of the quadruple precision floating point number.
Returns:
double precision approximation.
Since:
0.7

```public static int nextPrimeNumber​(int number)
throws IllegalArgumentException```
Returns the first prime number equals or greater than the given value. Current implementation accepts only values in the [2 … 65521] range.
Parameters:
`number` - the number for which to find the next prime.
Returns:
the given number if it is a prime number, or the next prime number otherwise.
Throws:
`Illegal­Argument­Exception` - if the given value is outside the supported range.
`Big­Integer​.is­Probable­Prime(int)`
• divisors

`public static int[] divisors​(int number)`
Returns the divisors of the specified number as positive integers. For any value other than `O` (which returns an empty array), the first element in the returned array is always `1` and the last element is always the absolute value of `number`.
Parameters:
`number` - the number for which to compute the divisors.
Returns:
the divisors in strictly increasing order.
• commonDivisors

`public static int[] commonDivisors​(int... numbers)`
Returns the positive divisors which are common to all the specified numbers. The returned array always starts with value 1, unless the given value is 0 in which case this method returns an empty array.
Parameters:
`numbers` - the numbers for which to compute the divisors, in any order.
Returns:
the divisors common to all the given numbers, in strictly increasing order.
• polynomialRoots

`public static double[] polynomialRoots​(double... coefficients)`
Returns the real (non-complex) roots of a polynomial equation having the given coefficients. This method returns the x values for which y=0 in the following equation:
y = c0 + c1x + c2x2 + c3x3 + … + cnxn
Current implementation can resolve polynomials described by a maximum of 5 coefficients, ignoring leading and trailing zeros. They correspond to linear, quadratic, cubic and quartic polynomials.
Parameters:
`coefficients` - the c0, c1, c2, … cn coefficients, in that order.
Returns:
the non-complex roots, or an empty array if none.
Throws:
`Unsupported­Operation­Exception` - if given arguments contain more non-zero coefficients than this method can handle.
Since:
1.0
`Quad­Curve2D​.solve­Quadratic(double[])`, `Cubic­Curve2D​.solve­Cubic(double[])`