# Class MathFunctions

Object
MathFunctions

public final class MathFunctions extends Object
Simple mathematical functions in addition to the ones provided in `Math`. Some methods in this class are very similar to the standard `Math` methods or could be implemented with straightforward formulas. However, the methods in this class put an emphasis on:

- Rounding errors: `magnitude`, `pow10`.
- Distinguishing positive zero from negative zero: `isPositive`, `isNegative`, `isSameSign`, `xorSign`.
- Distinguishing the different kinds of NaN numbers: `toNanFloat`, `toNanOrdinal`.

Some additional functions not found in `Math` are: `atanh`, `nextPrimeNumber`.

Since:
  0.3
See Also:
  - `DecimalFunctions`
  - `Numbers`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `HIGHEST_SUPPORTED_PRIME_NUMBER`
  The highest prime number supported by the `nextPrimeNumber(int)` method.
  `static final double`
  `LOG10_2`
  The logarithm of 2 in base 10, which is approximated by 0.3010299956639812.
  `static final int`
  `MAX_NAN_ORDINAL`
  The maximal ordinal value for `NaN` numbers created by `toNanFloat(int)`.
  `static final int`
  `MIN_NAN_ORDINAL`
  The minimal ordinal value for `NaN` numbers created by `toNanFloat(int)`.
  `static final double`
  `SQRT_2`
  The square root of 2, which is approximated by 1.4142135623730951.

- ## Method Summary

  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 double`
  `average(long x, long y)`
  Computes the averages of two signed integers without overflow.
  `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, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### SQRT_2

    public static final double SQRT_2
    The square root of 2, which is approximated by 1.4142135623730951.
    See Also:
      - `Math​.sqrt(double)`
      - Constant Field Values

  - ### LOG10_2

    public static final double LOG10_2
    The logarithm of 2 in base 10, which is approximated by 0.3010299956639812. This constant is useful for converting a power of 2 to a power of 10 as below:

        double exp10 = exp2 * LOG10_2;

    Since:
      0.4
    See Also:
      - `Math​.log10(double)`
      - `getExponent(double)`
      - Constant Field Values

  - ### MIN_NAN_ORDINAL

    public static final int MIN_NAN_ORDINAL
    The minimal ordinal value for `NaN` numbers created by `toNanFloat(int)`. The current value is -2097152.
    Since:
      1.0
    See Also:
      - Constant Field Values

  - ### MAX_NAN_ORDINAL

    public static final int MAX_NAN_ORDINAL
    The maximal ordinal value for `NaN` numbers created by `toNanFloat(int)`. The current value is 2097151.
    Since:
      1.0
    See Also:
      - Constant Field Values

  - ### HIGHEST_SUPPORTED_PRIME_NUMBER

    public static final int HIGHEST_SUPPORTED_PRIME_NUMBER
    The highest prime number supported by the `nextPrimeNumber(int)` method. In the current implementation, this value is 65521. However, this limit may change in any future Apache SIS version.

    #### Implementation note

    The current value is the highest prime number representable as an unsigned 16 bits integer. This is enough for current needs because 16 bits prime numbers are sufficient for finding the divisors of any 32 bits integers.
    See Also:
      - `nextPrimeNumber(int)`
      - Constant Field Values

- ## Method Details

  - ### average

    public static double average(long x, long y)
    Computes the averages of two signed integers without overflow. The calculation is performed with `long` arithmetic before to convert the result to the `double` floating point number. This function may be more accurate than the classical (x+y)/2 formula when x and/or y are very large, because it will avoid the lost of last digits before averaging. If exactly one of x and y is odd, the result will contain the 0.5 fraction digit.

    #### Reference

    This function is adapted from The Aggregate Magic Algorithms from University of Kentucky.
    Parameters:
      `x` - the first value to average.
      `y` - the second value to average.
    Returns:
      average of given values without integer overflow.
    Since:
      1.1

  - ### 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 equal 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.
    See Also:
      - `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​.getExponent(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​.getExponent(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​.getExponent(double)` would return.
    Special cases:
    - If the argument is NaN or infinite, then the result is `Double​.MAX_EXPONENT` + 1.
    - If the argument is `Double​.MAX_VALUE`, then the result is 1023.
    - If the argument is `Double​.MIN_NORMAL`, then the result is -1022.
    - If the argument is `Double​.MIN_VALUE`, then the result is -1074.
    - If the argument is zero, then the result is -1075.

    #### Identities

    For any p values in the [-1075 … 1024] range and value = 2p:
    - `getExponent(Math​.scalb(1.0, p)) == p`
    - `Math​.scalb(1.0, getExponent(value)) == value`
    - `Math​.floor(LOG10_2 * getExponent(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
    See Also:
      - `Math​.getExponent(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 as `Math​.pow(double, double)` but using only integer arithmetic. The result must be representable as a 64 bits integers (`long` primitive type), otherwise an `ArithmeticException` 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.

    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 `ArithmeticException` unless `exponent` is 0 or 1. Likewise any `exponent` value greater than 62 is guaranteed to fail unless `base` is 0 or 1.

    #### Reference

    This method uses exponentiation by squaring technic.
    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:
      `ArithmeticException` - if the given exponent is negative, or if the result overflow integer arithmetic.
    Since:
      1.0
    See Also:
      - `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)`. Special cases:
    - If x is equal or lower than -324, then the result is 0.
    - If x is equal 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.

    #### Purpose

    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.
    Parameters:
      `x` - the exponent.
    Returns:
      10 raised to the given exponent.
    See Also:
      - `pow10(double)`
      - `LOG10_2`
      - `DecimalFunctions`

  - ### pow10

    public static double pow10(double x)
    Computes 10 raised to the power of x. Invoking this method is equivalent to invoking `Math​.pow(10, x)`, but is slightly more accurate in the special case where the given argument is an integer.
    Parameters:
      `x` - the exponent.
    Returns:
      10 raised to the given exponent.
    See Also:
      - `pow10(int)`
      - `Math​.pow(double, double)`
      - `Math​.log10(double)`

  - ### 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
    See Also:
      - `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
    See Also:
      - `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:
    - For x = NaN, this method returns a NaN value.
    - For x = -1, this method returns negative infinity.
    - For x = +1, this method returns positive infinity.
    Parameters:
      `x` - the value for which to compute the inverse hyperbolic tangent.
    Returns:
      the inverse hyperbolic tangent of the given value.
    See Also:
      - `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 `NaN`, 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 `isPositive(double)` and testing if (value >= 0).
    Parameters:
      `value` - the value to test.
    Returns:
      `true` if the given value is positive, excluding negative zero.
    See Also:
      - `isPositiveZero(double)`
      - `isNegative(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
    See Also:
      - `isPositive(double)`
      - `isNegativeZero(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 `NaN`, 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 `isNegative(double)` and testing if (value < 0).
    Parameters:
      `value` - the value to test.
    Returns:
      `true` if the given value is negative, including negative zero.
    See Also:
      - `isNegativeZero(double)`
      - `isPositive(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
    See Also:
      - `isNegative(double)`
      - `isPositiveZero(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 `NaN`, 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.
    See Also:
      - `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​.copySign(value, sign)` except that the sign is combined with an exclusive or operation instead of being copied.

    This method makes no guarantee about whether `NaN` values are handled as positive or negative numbers. This is the same policy as `Math​.copySign(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.
    See Also:
      - `Math​.copySign(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.
      `ε` - 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.
      `ε` - 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​.NaN` value
    - [`0xFF800001` … `0xFFFFFFFF`]
    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 `toNanFloat(0)` returns the standard `Float​.NaN` 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:
      `IllegalArgumentException` - if the specified ordinal is out of range.
    See Also:
      - `Float​.intBitsToFloat(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 `toNanFloat(int)`.

    If the given float is the standard `Float​.NaN` 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:
      `IllegalArgumentException` - if the given value is not a NaN value, or does not use a supported bits pattern.

  - ### quadrupleToDouble

    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 cannot be represented in double precision and are mapped to `double` values as below:

    - Values having a magnitude less than `Double​.MIN_VALUE` are mapped to positive or negative zero.
    - Values having a magnitude greater than `Double​.MAX_VALUE` are mapped to `Double​.POSITIVE_INFINITY` or `Double​.NEGATIVE_INFINITY`.
    - All NaN values are currently collapsed to the single "canonical" `Double​.NaN` value (this policy may be revisited in future SIS version).
    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
    See Also:
      - Quadruple-precision floating-point format on Wikipedia

  - ### nextPrimeNumber

    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:
      `IllegalArgumentException` - if the given value is outside the supported range.
    See Also:
      - `BigInteger​.isProbablePrime(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 + c1⋅x + c2⋅x2 + c3⋅x3 + … + cn⋅xn

    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:
      `UnsupportedOperationException` - if given arguments contain more non-zero coefficients than this method can handle.
    Since:
      1.0
    See Also:
      - `QuadCurve2D​.solveQuadratic(double[])`
      - `CubicCurve2D​.solveCubic(double[])`