com.google.common.math

## Class LongMath

- java.lang.Object
- - com.google.common.math.LongMath

-     @GwtCompatible(emulated=true)
      public final class LongMath
      extends java.lang.Object

  A class for arithmetic on values of type `long`. Where possible, methods are defined and named analogously to their `BigInteger` counterparts.

  The implementations of many methods in this class are based on material from Henry S. Warren, Jr.'s Hacker's Delight, (Addison Wesley, 2002).

  Similar functionality for `int` and for `BigInteger` can be found in `IntMath` and `BigIntegerMath` respectively. For other common operations on `long` values, see `Longs`.

  Since:
    11.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static long` | `binomial(int n, int k)` Returns `n` choose `k`, also known as the binomial coefficient of `n` and `k`, or `Long.MAX_VALUE` if the result does not fit in a `long`.
    `static long` | `checkedAdd(long a, long b)` Returns the sum of `a` and `b`, provided it does not overflow.
    `static long` | `checkedMultiply(long a, long b)` Returns the product of `a` and `b`, provided it does not overflow.
    `static long` | `checkedPow(long b, int k)` Returns the `b` to the `k`th power, provided it does not overflow.
    `static long` | `checkedSubtract(long a, long b)` Returns the difference of `a` and `b`, provided it does not overflow.
    `static long` | `divide(long p, long q, java.math.RoundingMode mode)` Returns the result of dividing `p` by `q`, rounding using the specified `RoundingMode`.
    `static long` | `factorial(int n)` Returns `n!`, that is, the product of the first `n` positive integers, `1` if `n == 0`, or `Long.MAX_VALUE` if the result does not fit in a `long`.
    `static long` | `gcd(long a, long b)` Returns the greatest common divisor of `a, b`.
    `static boolean` | `isPowerOfTwo(long x)` Returns `true` if `x` represents a power of two.
    `static int` | `log10(long x, java.math.RoundingMode mode)` Returns the base-10 logarithm of `x`, rounded according to the specified rounding mode.
    `static int` | `log2(long x, java.math.RoundingMode mode)` Returns the base-2 logarithm of `x`, rounded according to the specified rounding mode.
    `static long` | `mean(long x, long y)` Returns the arithmetic mean of `x` and `y`, rounded toward negative infinity.
    `static int` | `mod(long x, int m)` Returns `x mod m`, a non-negative value less than `m`.
    `static long` | `mod(long x, long m)` Returns `x mod m`, a non-negative value less than `m`.
    `static long` | `pow(long b, int k)` Returns `b` to the `k`th power.
    `static long` | `sqrt(long x, java.math.RoundingMode mode)` Returns the square root of `x`, rounded with the specified rounding mode.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### isPowerOfTwo

          public static boolean isPowerOfTwo(long x)

      Returns `true` if `x` represents a power of two.

      This differs from `Long.bitCount(x) == 1`, because `Long.bitCount(Long.MIN_VALUE) == 1`, but `Long.MIN_VALUE` is not a power of two.

    - #### log2

          public static int log2(long x,
                 java.math.RoundingMode mode)

      Returns the base-2 logarithm of `x`, rounded according to the specified rounding mode.
      Throws:
        `java.lang.IllegalArgumentException` - if `x <= 0`
        `java.lang.ArithmeticException` - if `mode` is `RoundingMode.UNNECESSARY` and `x` is not a power of two

    - #### log10

          @GwtIncompatible(value="TODO")
          public static int log10(long x,
                                       java.math.RoundingMode mode)

      Returns the base-10 logarithm of `x`, rounded according to the specified rounding mode.
      Throws:
        `java.lang.IllegalArgumentException` - if `x <= 0`
        `java.lang.ArithmeticException` - if `mode` is `RoundingMode.UNNECESSARY` and `x` is not a power of ten

    - #### pow

          @GwtIncompatible(value="TODO")
          public static long pow(long b,
                                      int k)

      Returns `b` to the `k`th power. Even if the result overflows, it will be equal to `BigInteger.valueOf(b).pow(k).longValue()`. This implementation runs in `O(log k)` time.
      Throws:
        `java.lang.IllegalArgumentException` - if `k < 0`

    - #### sqrt

          @GwtIncompatible(value="TODO")
          public static long sqrt(long x,
                                       java.math.RoundingMode mode)

      Returns the square root of `x`, rounded with the specified rounding mode.
      Throws:
        `java.lang.IllegalArgumentException` - if `x < 0`
        `java.lang.ArithmeticException` - if `mode` is `RoundingMode.UNNECESSARY` and `sqrt(x)` is not an integer

    - #### divide

          @GwtIncompatible(value="TODO")
          public static long divide(long p,
                                         long q,
                                         java.math.RoundingMode mode)

      Returns the result of dividing `p` by `q`, rounding using the specified `RoundingMode`.
      Throws:
        `java.lang.ArithmeticException` - if `q == 0`, or if `mode == UNNECESSARY` and `a` is not an integer multiple of `b`

    - #### mod

          @GwtIncompatible(value="TODO")
          public static int mod(long x,
                                     int m)

      Returns `x mod m`, a non-negative value less than `m`. This differs from `x % m`, which might be negative.

      For example:

           mod(7, 4) == 3
           mod(-7, 4) == 1
           mod(-1, 4) == 3
           mod(-8, 4) == 0
           mod(8, 4) == 0

      Throws:
        `java.lang.ArithmeticException` - if `m <= 0`
      See Also:
        Remainder Operator

    - #### mod

          @GwtIncompatible(value="TODO")
          public static long mod(long x,
                                      long m)

      Returns `x mod m`, a non-negative value less than `m`. This differs from `x % m`, which might be negative.

      For example:

           mod(7, 4) == 3
           mod(-7, 4) == 1
           mod(-1, 4) == 3
           mod(-8, 4) == 0
           mod(8, 4) == 0

      Throws:
        `java.lang.ArithmeticException` - if `m <= 0`
      See Also:
        Remainder Operator

    - #### gcd

          public static long gcd(long a,
                 long b)

      Returns the greatest common divisor of `a, b`. Returns `0` if `a == 0 && b == 0`.
      Throws:
        `java.lang.IllegalArgumentException` - if `a < 0` or `b < 0`

    - #### checkedAdd

          @GwtIncompatible(value="TODO")
          public static long checkedAdd(long a,
                                             long b)

      Returns the sum of `a` and `b`, provided it does not overflow.
      Throws:
        `java.lang.ArithmeticException` - if `a + b` overflows in signed `long` arithmetic

    - #### checkedSubtract

          @GwtIncompatible(value="TODO")
          public static long checkedSubtract(long a,
                                                  long b)

      Returns the difference of `a` and `b`, provided it does not overflow.
      Throws:
        `java.lang.ArithmeticException` - if `a - b` overflows in signed `long` arithmetic

    - #### checkedMultiply

          @GwtIncompatible(value="TODO")
          public static long checkedMultiply(long a,
                                                  long b)

      Returns the product of `a` and `b`, provided it does not overflow.
      Throws:
        `java.lang.ArithmeticException` - if `a * b` overflows in signed `long` arithmetic

    - #### checkedPow

          @GwtIncompatible(value="TODO")
          public static long checkedPow(long b,
                                             int k)

      Returns the `b` to the `k`th power, provided it does not overflow.
      Throws:
        `java.lang.ArithmeticException` - if `b` to the `k`th power overflows in signed `long` arithmetic

    - #### factorial

          @GwtIncompatible(value="TODO")
          public static long factorial(int n)

      Returns `n!`, that is, the product of the first `n` positive integers, `1` if `n == 0`, or `Long.MAX_VALUE` if the result does not fit in a `long`.
      Throws:
        `java.lang.IllegalArgumentException` - if `n < 0`

    - #### binomial

          public static long binomial(int n,
                      int k)

      Returns `n` choose `k`, also known as the binomial coefficient of `n` and `k`, or `Long.MAX_VALUE` if the result does not fit in a `long`.
      Throws:
        `java.lang.IllegalArgumentException` - if `n < 0`, `k < 0`, or `k > n`

    - #### mean

          public static long mean(long x,
                  long y)

      Returns the arithmetic mean of `x` and `y`, rounded toward negative infinity. This method is resilient to overflow.
      Since:
        14.0