Class DoubleMath


  • @GwtCompatible(emulated=true)
    public final class DoubleMath
    extends java.lang.Object
    A class for arithmetic on doubles that is not covered by Math.
    Since:
    11.0
    Author:
    Louis Wasserman
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static double factorial​(int n)
      Returns n!, that is, the product of the first n positive integers, 1 if n == 0, or n!, or Double.POSITIVE_INFINITY if n! > Double.MAX_VALUE.
      static int fuzzyCompare​(double a, double b, double tolerance)
      Compares a and b "fuzzily," with a tolerance for nearly-equal values.
      static boolean fuzzyEquals​(double a, double b, double tolerance)
      Returns true if a and b are within tolerance of each other.
      static boolean isMathematicalInteger​(double x)
      Returns true if x represents a mathematical integer.
      static boolean isPowerOfTwo​(double x)
      Returns true if x is exactly equal to 2^k for some finite integer k.
      static double log2​(double x)
      Returns the base 2 logarithm of a double value.
      static int log2​(double x, java.math.RoundingMode mode)
      Returns the base 2 logarithm of a double value, rounded with the specified rounding mode to an int.
      static double mean​(double... values)
      Returns the arithmetic mean of values.
      static double mean​(int... values)
      Returns the arithmetic mean of values.
      static double mean​(long... values)
      Returns the arithmetic mean of values.
      static double mean​(java.lang.Iterable<? extends java.lang.Number> values)
      Returns the arithmetic mean of values.
      static double mean​(java.util.Iterator<? extends java.lang.Number> values)
      Returns the arithmetic mean of values.
      static java.math.BigInteger roundToBigInteger​(double x, java.math.RoundingMode mode)
      Returns the BigInteger value that is equal to x rounded with the specified rounding mode, if possible.
      static int roundToInt​(double x, java.math.RoundingMode mode)
      Returns the int value that is equal to x rounded with the specified rounding mode, if possible.
      static long roundToLong​(double x, java.math.RoundingMode mode)
      Returns the long value that is equal to x rounded with the specified rounding mode, if possible.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • roundToInt

        @GwtIncompatible("#roundIntermediate")
        public static int roundToInt​(double x,
                                     java.math.RoundingMode mode)
        Returns the int value that is equal to x rounded with the specified rounding mode, if possible.
        Throws:
        java.lang.ArithmeticException - if
        • x is infinite or NaN
        • x, after being rounded to a mathematical integer using the specified rounding mode, is either less than Integer.MIN_VALUE or greater than Integer.MAX_VALUE
        • x is not a mathematical integer and mode is RoundingMode.UNNECESSARY
      • roundToLong

        @GwtIncompatible("#roundIntermediate")
        public static long roundToLong​(double x,
                                       java.math.RoundingMode mode)
        Returns the long value that is equal to x rounded with the specified rounding mode, if possible.
        Throws:
        java.lang.ArithmeticException - if
        • x is infinite or NaN
        • x, after being rounded to a mathematical integer using the specified rounding mode, is either less than Long.MIN_VALUE or greater than Long.MAX_VALUE
        • x is not a mathematical integer and mode is RoundingMode.UNNECESSARY
      • roundToBigInteger

        @GwtIncompatible("#roundIntermediate, java.lang.Math.getExponent, com.google.common.math.DoubleUtils")
        public static java.math.BigInteger roundToBigInteger​(double x,
                                                             java.math.RoundingMode mode)
        Returns the BigInteger value that is equal to x rounded with the specified rounding mode, if possible.
        Throws:
        java.lang.ArithmeticException - if
        • x is infinite or NaN
        • x is not a mathematical integer and mode is RoundingMode.UNNECESSARY
      • isPowerOfTwo

        @GwtIncompatible("com.google.common.math.DoubleUtils")
        public static boolean isPowerOfTwo​(double x)
        Returns true if x is exactly equal to 2^k for some finite integer k.
      • log2

        public static double log2​(double x)
        Returns the base 2 logarithm of a double value.

        Special cases:

        • If x is NaN or less than zero, the result is NaN.
        • If x is positive infinity, the result is positive infinity.
        • If x is positive or negative zero, the result is negative infinity.

        The computed result is within 1 ulp of the exact result.

        If the result of this method will be immediately rounded to an int, log2(double, RoundingMode) is faster.

      • log2

        @GwtIncompatible("java.lang.Math.getExponent, com.google.common.math.DoubleUtils")
        public static int log2​(double x,
                               java.math.RoundingMode mode)
        Returns the base 2 logarithm of a double value, rounded with the specified rounding mode to an int.

        Regardless of the rounding mode, this is faster than (int) log2(x).

        Throws:
        java.lang.IllegalArgumentException - if x <= 0.0, x is NaN, or x is infinite
      • isMathematicalInteger

        @GwtIncompatible("java.lang.Math.getExponent, com.google.common.math.DoubleUtils")
        public static boolean isMathematicalInteger​(double x)
        Returns true if x represents a mathematical integer.

        This is equivalent to, but not necessarily implemented as, the expression !Double.isNaN(x) && !Double.isInfinite(x) && x == Math.rint(x).

      • factorial

        public static double factorial​(int n)
        Returns n!, that is, the product of the first n positive integers, 1 if n == 0, or n!, or Double.POSITIVE_INFINITY if n! > Double.MAX_VALUE.

        The result is within 1 ulp of the true value.

        Throws:
        java.lang.IllegalArgumentException - if n < 0
      • fuzzyEquals

        public static boolean fuzzyEquals​(double a,
                                          double b,
                                          double tolerance)
        Returns true if a and b are within tolerance of each other.

        Technically speaking, this is equivalent to Math.abs(a - b) <= tolerance || Double.valueOf(a).equals(Double.valueOf(b)).

        Notable special cases include:

        • All NaNs are fuzzily equal.
        • If a == b, then a and b are always fuzzily equal.
        • Positive and negative zero are always fuzzily equal.
        • If tolerance is zero, and neither a nor b is NaN, then a and b are fuzzily equal if and only if a == b.
        • With Double.POSITIVE_INFINITY tolerance, all non-NaN values are fuzzily equal.
        • With finite tolerance, Double.POSITIVE_INFINITY and Double.NEGATIVE_INFINITY are fuzzily equal only to themselves.
        • This is reflexive and symmetric, but not transitive, so it is not an equivalence relation and not suitable for use in Object.equals(java.lang.Object) implementations.

        Throws:
        java.lang.IllegalArgumentException - if tolerance is < 0 or NaN
        Since:
        13.0
      • fuzzyCompare

        public static int fuzzyCompare​(double a,
                                       double b,
                                       double tolerance)
        Compares a and b "fuzzily," with a tolerance for nearly-equal values.

        This method is equivalent to fuzzyEquals(a, b, tolerance) ? 0 : Double.compare(a, b). In particular, like Double.compare(double, double), it treats all NaN values as equal and greater than all other values (including Double.POSITIVE_INFINITY).

        This is not a total ordering and is not suitable for use in Comparable.compareTo(T) implementations. In particular, it is not transitive.

        Throws:
        java.lang.IllegalArgumentException - if tolerance is < 0 or NaN
        Since:
        13.0
      • mean

        @GwtIncompatible("com.google.common.math.DoubleUtils")
        public static double mean​(double... values)
        Returns the arithmetic mean of values.

        If these values are a sample drawn from a population, this is also an unbiased estimator of the arithmetic mean of the population.

        Parameters:
        values - a nonempty series of values
        Throws:
        java.lang.IllegalArgumentException - if values is empty or contains any non-finite value
      • mean

        public static double mean​(int... values)
        Returns the arithmetic mean of values.

        If these values are a sample drawn from a population, this is also an unbiased estimator of the arithmetic mean of the population.

        Parameters:
        values - a nonempty series of values
        Throws:
        java.lang.IllegalArgumentException - if values is empty
      • mean

        public static double mean​(long... values)
        Returns the arithmetic mean of values.

        If these values are a sample drawn from a population, this is also an unbiased estimator of the arithmetic mean of the population.

        Parameters:
        values - a nonempty series of values, which will be converted to double values (this may cause loss of precision for longs of magnitude over 2^53 (slightly over 9e15))
        Throws:
        java.lang.IllegalArgumentException - if values is empty
      • mean

        @GwtIncompatible("com.google.common.math.DoubleUtils")
        public static double mean​(java.lang.Iterable<? extends java.lang.Number> values)
        Returns the arithmetic mean of values.

        If these values are a sample drawn from a population, this is also an unbiased estimator of the arithmetic mean of the population.

        Parameters:
        values - a nonempty series of values, which will be converted to double values (this may cause loss of precision)
        Throws:
        java.lang.IllegalArgumentException - if values is empty or contains any non-finite value
      • mean

        @GwtIncompatible("com.google.common.math.DoubleUtils")
        public static double mean​(java.util.Iterator<? extends java.lang.Number> values)
        Returns the arithmetic mean of values.

        If these values are a sample drawn from a population, this is also an unbiased estimator of the arithmetic mean of the population.

        Parameters:
        values - a nonempty series of values, which will be converted to double values (this may cause loss of precision)
        Throws:
        java.lang.IllegalArgumentException - if values is empty or contains any non-finite value