Class MathFunctions

    • Method Summary

      All Methods Static Methods Concrete 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.
    • Field Detail

      • 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), get­Exponent(double), Constant Field Values
      • MIN_NAN_ORDINAL

        public static final int MIN_NAN_ORDINAL
        The minimal ordinal value for Na­N numbers created by to­Nan­Float(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 Na­N numbers created by to­Nan­Float(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 next­Prime­Number(int) method. In the current implementation, this value is 65521. However this limit may change in any future Apache SIS version.
        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:
        next­Prime­Number(int), Constant Field Values
    • 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.
        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​.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
        See Also:
        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
        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).
        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.
        See Also:
        pow10(double), LOG10_2, Decimal­Functions
      • 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:
        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 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.
        See Also:
        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
        See Also:
        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.
        See Also:
        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
        See Also:
        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.
        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​.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.
        See Also:
        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:
        • [0x7F8000010x7FFFFFFF], with 0x7FC00000 as the bit fields of the standard Float​.Na­N value
        • [0x­FF8000010x­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.
        See Also:
        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.
      • 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 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
        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:
        Illegal­Argument­Exception - if the given value is outside the supported range.
        See Also:
        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
        See Also:
        Quad­Curve2D​.solve­Quadratic(double[]), Cubic­Curve2D​.solve­Cubic(double[])