Class XMath


  • public final class XMath
    extends Object
    Simple mathematical functions in addition to the ones provided in Math.
    Since:
    2.5
    Author:
    Martin Desruisseaux (IRD)
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static int countDecimalFractionDigits​(double value)
      Counts the fraction digits in the string representation of the specified value.
      static int[] divisors​(int number)
      Returns the divisors of the specified number as positive integers.
      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 int primeNumber​(int index)
      Returns the ith prime number.
      static double roundIfAlmostInteger​(double value, int maxULP)
      Rounds the specified value, providing that the difference between the original value and the rounded value is not greater than the specified amount of floating point units.
      static byte sgn​(byte x)
      Returns the sign of x.
      static int sgn​(double x)
      Returns the sign of x.
      static int sgn​(float x)
      Returns the sign of x.
      static int sgn​(int x)
      Returns the sign of x.
      static int sgn​(long x)
      Returns the sign of x.
      static short sgn​(short x)
      Returns the sign of x.
      static float toNaN​(int index)
      Returns a NaN number for the specified index.
      static double trimDecimalFractionDigits​(double value, int maxULP, int n)
      Tries to remove at least n fraction digits in the decimal representation of the specified value.
    • Method Detail

      • pow10

        public static double pow10​(double x)
        Computes 10 raised to the power of x. This method delegates to pow10(int) if x is an integer, or to Math.pow(double, double) otherwise.
        Parameters:
        x - The exponent.
        Returns:
        10 raised to the given exponent.
      • pow10

        public static double pow10​(int x)
        Computes 10 raised to the power of x. This method tries to be slightly more accurate than Math.pow(10,x), sometime at the cost of performance.

        The Math.pow(10,x) method doesn't always return the closest IEEE floating point representation. More accurate calculations are slower and usually not necessary, but the base 10 is a special case since it is used for scaling axes or formatting human-readable output, in which case the precision may matter.

        Parameters:
        x - The exponent.
        Returns:
        10 raised to the given exponent.
      • sgn

        public static int sgn​(double x)
        Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero or NaN and +1 if x is positive.
        Parameters:
        x - The number from which to get the sign.
        Returns:
        +1 if x is positive, -1 if negative, or 0 otherwise.
        See Also:
        Math.signum(double)
      • sgn

        public static int sgn​(float x)
        Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero or NaN and +1 if x is positive.
        Parameters:
        x - The number from which to get the sign.
        Returns:
        +1 if x is positive, -1 if negative, or 0 otherwise.
        See Also:
        Math.signum(float)
      • sgn

        public static int sgn​(long x)
        Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero and +1 if x is positive.
        Parameters:
        x - The number from which to get the sign.
        Returns:
        +1 if x is positive, -1 if negative, or 0 otherwise.
      • sgn

        public static int sgn​(int x)
        Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero and +1 if x is positive.
        Parameters:
        x - The number from which to get the sign.
        Returns:
        +1 if x is positive, -1 if negative, or 0 otherwise.
      • sgn

        public static short sgn​(short x)
        Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero and +1 if x is positive.
        Parameters:
        x - The number from which to get the sign.
        Returns:
        +1 if x is positive, -1 if negative, or 0 otherwise.
      • sgn

        public static byte sgn​(byte x)
        Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero and +1 if x is positive.
        Parameters:
        x - The number from which to get the sign.
        Returns:
        +1 if x is positive, -1 if negative, or 0 otherwise.
      • roundIfAlmostInteger

        public static double roundIfAlmostInteger​(double value,
                                                  int maxULP)
        Rounds the specified value, providing that the difference between the original value and the rounded value is not greater than the specified amount of floating point units. This method can be used for hiding floating point error likes 2.9999999996.
        Parameters:
        value - The value to round.
        maxULP - The maximal change allowed in ULPs (Unit in the Last Place).
        Returns:
        The rounded value, of value if it was not close enough to an integer.
      • trimDecimalFractionDigits

        public static double trimDecimalFractionDigits​(double value,
                                                       int maxULP,
                                                       int n)
        Tries to remove at least n fraction digits in the decimal representation of the specified value. This method tries small changes to value, by adding or substracting up to maxULP (Unit in the Last Place). If there is no small change that remove at least n fraction digits, then the value is returned unchanged. This method is used for hiding rounding errors, like in conversions from radians to degrees.

        Example: XMath.trimLastDecimalDigits(-61.500000000000014, 12, 4) returns -61.5.

        Parameters:
        value - The value to fix.
        maxULP - The maximal change allowed in ULPs (Unit in the Last Place). A typical value is 4.
        n - The minimum amount of fraction digits.
        Returns:
        The trimmed value, or the unchanged value if there is no small change that remove at least n fraction digits.
      • countDecimalFractionDigits

        public static int countDecimalFractionDigits​(double value)
        Counts the fraction digits in the string representation of the specified value. This method is equivalent to a calling Double.toString(value) and counting the number of digits after the decimal separator.
        Parameters:
        value - The value for which to count the fraction digits.
        Returns:
        The number of fraction digits.
      • toNaN

        public static float toNaN​(int index)
                           throws IndexOutOfBoundsException
        Returns a NaN number for the specified index. Valid NaN numbers have bit fields ranging from 0x7f800001 through 0x7fffffff or 0xff800001 through 0xffffffff. The standard Float.NaN has bit fields 0x7fc00000. See Float.intBitsToFloat(int) for more details on NaN bit values.
        Parameters:
        index - The index, from -2097152 to 2097151 inclusive.
        Returns:
        One of the legal NaN values as a float.
        Throws:
        IndexOutOfBoundsException - if the specified index is out of bounds.
        See Also:
        Float.intBitsToFloat(int)
      • primeNumber

        public static int primeNumber​(int index)
                               throws IndexOutOfBoundsException
        Returns the ith prime number. This method returns (2,3,5,7,11...) for index (0,1,2,3,4...). This method is designed for relatively small prime numbers only; don't use it for large values.
        Parameters:
        index - The prime number index, starting at index 0 for prime number 2.
        Returns:
        The prime number at the specified index.
        Throws:
        IndexOutOfBoundsException - if the specified index is too large.
        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.