DoubleMath
Date: 2016-05-24

com.google.common.math

## Class DoubleMath

- java.lang.Object
- - com.google.common.math.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

- - ### Method Summary

    Methods
    Modifier and Type | Method and 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(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 double` | `mean(long... 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(value="#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(value="#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(value="#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(value="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(value="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(value="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(value="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(value="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(value="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