org.apache.commons.math3.util

## Class ArithmeticUtils

- java.lang.Object
- - org.apache.commons.math3.util.ArithmeticUtils

-     public final class ArithmeticUtils
      extends java.lang.Object

  Some useful, arithmetics related, additions to the built-in functions in `Math`.
  Version:
    $Id: ArithmeticUtils.java 1422313 2012-12-15 18:53:41Z psteitz $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static long[]` | `FACTORIALS` All long-representable factorials
    `(package private) static java.util.concurrent.atomic.AtomicReference<long[][]>` | `STIRLING_S2` Stirling numbers of the second kind.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `ArithmeticUtils()` Private constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `addAndCheck(int x, int y)` Add two integers, checking for overflow.
    `static long` | `addAndCheck(long a, long b)` Add two long integers, checking for overflow.
    `private static long` | `addAndCheck(long a, long b, Localizable pattern)` Add two long integers, checking for overflow.
    `static long` | `binomialCoefficient(int n, int k)` Returns an exact representation of the Binomial Coefficient, "`n choose k`", the number of `k`-element subsets that can be selected from an `n`-element set.
    `static double` | `binomialCoefficientDouble(int n, int k)` Returns a `double` representation of the Binomial Coefficient, "`n choose k`", the number of `k`-element subsets that can be selected from an `n`-element set.
    `static double` | `binomialCoefficientLog(int n, int k)` Returns the natural `log` of the Binomial Coefficient, "`n choose k`", the number of `k`-element subsets that can be selected from an `n`-element set.
    `private static void` | `checkBinomial(int n, int k)` Check binomial preconditions.
    `static long` | `factorial(int n)` Returns n!.
    `static double` | `factorialDouble(int n)` Compute n!, the factorial of `n` (the product of the numbers 1 to n), as a `double`.
    `static double` | `factorialLog(int n)` Compute the natural logarithm of the factorial of `n`.
    `static int` | `gcd(int p, int q)` Computes the greatest common divisor of the absolute value of two numbers, using a modified version of the "binary gcd" method.
    `static long` | `gcd(long p, long q)` Gets the greatest common divisor of the absolute value of two numbers, using the "binary gcd" method which avoids division and modulo operations.
    `private static int` | `gcdPositive(int a, int b)` Computes the greatest common divisor of two positive numbers (this precondition is not checked and the result is undefined if not fulfilled) using the "binary gcd" method which avoids division and modulo operations.
    `static boolean` | `isPowerOfTwo(long n)` Returns true if the argument is a power of two.
    `static int` | `lcm(int a, int b)` Returns the least common multiple of the absolute value of two numbers, using the formula `lcm(a,b) = (a / gcd(a,b)) * b`.
    `static long` | `lcm(long a, long b)` Returns the least common multiple of the absolute value of two numbers, using the formula `lcm(a,b) = (a / gcd(a,b)) * b`.
    `static int` | `mulAndCheck(int x, int y)` Multiply two integers, checking for overflow.
    `static long` | `mulAndCheck(long a, long b)` Multiply two long integers, checking for overflow.
    `static java.math.BigInteger` | `pow(java.math.BigInteger k, java.math.BigInteger e)` Raise a BigInteger to a BigInteger power.
    `static java.math.BigInteger` | `pow(java.math.BigInteger k, int e)` Raise a BigInteger to an int power.
    `static java.math.BigInteger` | `pow(java.math.BigInteger k, long e)` Raise a BigInteger to a long power.
    `static int` | `pow(int k, int e)` Raise an int to an int power.
    `static int` | `pow(int k, long e)` Raise an int to a long power.
    `static long` | `pow(long k, int e)` Raise a long to an int power.
    `static long` | `pow(long k, long e)` Raise a long to a long power.
    `static long` | `stirlingS2(int n, int k)` Returns the Stirling number of the second kind, "`S(n,k)`", the number of ways of partitioning an `n`-element set into `k` non-empty subsets.
    `static int` | `subAndCheck(int x, int y)` Subtract two integers, checking for overflow.
    `static long` | `subAndCheck(long a, long b)` Subtract two long integers, checking for overflow.

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

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

- - ### Field Detail

    - #### FACTORIALS

          static final long[] FACTORIALS

      All long-representable factorials

    - #### STIRLING_S2

          static final java.util.concurrent.atomic.AtomicReference<long[][]> STIRLING_S2

      Stirling numbers of the second kind.

  - ### Constructor Detail

    - #### ArithmeticUtils

          private ArithmeticUtils()

      Private constructor.

  - ### Method Detail

    - #### addAndCheck

          public static int addAndCheck(int x,
                        int y)
                                 throws MathArithmeticException

      Add two integers, checking for overflow.
      Parameters:
        `x` - an addend
        `y` - an addend
      Returns:
        the sum `x+y`
      Throws:
        `MathArithmeticException` - if the result can not be represented as an `int`.
      Since:
        1.1

    - #### addAndCheck

          public static long addAndCheck(long a,
                         long b)
                                  throws MathArithmeticException

      Add two long integers, checking for overflow.
      Parameters:
        `a` - an addend
        `b` - an addend
      Returns:
        the sum `a+b`
      Throws:
        `MathArithmeticException` - if the result can not be represented as an long
      Since:
        1.2

    - #### binomialCoefficient

          public static long binomialCoefficient(int n,
                                 int k)
                                          throws NotPositiveException,
                                                 NumberIsTooLargeException,
                                                 MathArithmeticException

      Returns an exact representation of the Binomial Coefficient, "`n choose k`", the number of `k`-element subsets that can be selected from an `n`-element set.

      Preconditions:

      - `0 <= k <= n` (otherwise `IllegalArgumentException` is thrown)
      - The result is small enough to fit into a `long`. The largest value of `n` for which all coefficients are `< Long.MAX_VALUE` is 66. If the computed value exceeds `Long.MAX_VALUE` an `ArithMeticException` is thrown.
      Parameters:
        `n` - the size of the set
        `k` - the size of the subsets to be counted
      Returns:
        `n choose k`
      Throws:
        `NotPositiveException` - if `n < 0`.
        `NumberIsTooLargeException` - if `k > n`.
        `MathArithmeticException` - if the result is too large to be represented by a long integer.

    - #### binomialCoefficientDouble

          public static double binomialCoefficientDouble(int n,
                                         int k)
                                                  throws NotPositiveException,
                                                         NumberIsTooLargeException,
                                                         MathArithmeticException

      Returns a `double` representation of the Binomial Coefficient, "`n choose k`", the number of `k`-element subsets that can be selected from an `n`-element set.

      Preconditions:

      - `0 <= k <= n` (otherwise `IllegalArgumentException` is thrown)
      - The result is small enough to fit into a `double`. The largest value of `n` for which all coefficients are < Double.MAX_VALUE is 1029. If the computed value exceeds Double.MAX_VALUE, Double.POSITIVE_INFINITY is returned
      Parameters:
        `n` - the size of the set
        `k` - the size of the subsets to be counted
      Returns:
        `n choose k`
      Throws:
        `NotPositiveException` - if `n < 0`.
        `NumberIsTooLargeException` - if `k > n`.
        `MathArithmeticException` - if the result is too large to be represented by a long integer.

    - #### binomialCoefficientLog

          public static double binomialCoefficientLog(int n,
                                      int k)
                                               throws NotPositiveException,
                                                      NumberIsTooLargeException,
                                                      MathArithmeticException

      Returns the natural `log` of the Binomial Coefficient, "`n choose k`", the number of `k`-element subsets that can be selected from an `n`-element set.

      Preconditions:

      - `0 <= k <= n` (otherwise `IllegalArgumentException` is thrown)
      Parameters:
        `n` - the size of the set
        `k` - the size of the subsets to be counted
      Returns:
        `n choose k`
      Throws:
        `NotPositiveException` - if `n < 0`.
        `NumberIsTooLargeException` - if `k > n`.
        `MathArithmeticException` - if the result is too large to be represented by a long integer.

    - #### factorial

          public static long factorial(int n)
                                throws NotPositiveException,
                                       MathArithmeticException

      Returns n!. Shorthand for `n` Factorial, the product of the numbers `1,...,n`.

      Preconditions:

      - `n >= 0` (otherwise `IllegalArgumentException` is thrown)
      - The result is small enough to fit into a `long`. The largest value of `n` for which `n!` < Long.MAX_VALUE} is 20. If the computed value exceeds `Long.MAX_VALUE` an `ArithMeticException` is thrown.
      Parameters:
        `n` - argument
      Returns:
        `n!`
      Throws:
        `MathArithmeticException` - if the result is too large to be represented by a `long`.
        `NotPositiveException` - if `n < 0`.
        `MathArithmeticException` - if `n > 20`: The factorial value is too large to fit in a `long`.

    - #### factorialDouble

          public static double factorialDouble(int n)
                                        throws NotPositiveException

      Compute n!, the factorial of `n` (the product of the numbers 1 to n), as a `double`. The result should be small enough to fit into a `double`: The largest `n` for which `n! < Double.MAX_VALUE` is 170. If the computed value exceeds `Double.MAX_VALUE`, `Double.POSITIVE_INFINITY` is returned.
      Parameters:
        `n` - Argument.
      Returns:
        `n!`
      Throws:
        `NotPositiveException` - if `n < 0`.

    - #### factorialLog

          public static double factorialLog(int n)
                                     throws NotPositiveException

      Compute the natural logarithm of the factorial of `n`.
      Parameters:
        `n` - Argument.
      Returns:
        `n!`
      Throws:
        `NotPositiveException` - if `n < 0`.

    - #### gcd

          public static int gcd(int p,
                int q)
                         throws MathArithmeticException

      Computes the greatest common divisor of the absolute value of two numbers, using a modified version of the "binary gcd" method. See Knuth 4.5.2 algorithm B. The algorithm is due to Josef Stein (1961).
      Special cases:
      - The invocations `gcd(Integer.MIN_VALUE, Integer.MIN_VALUE)`, `gcd(Integer.MIN_VALUE, 0)` and `gcd(0, Integer.MIN_VALUE)` throw an `ArithmeticException`, because the result would be 2^31, which is too large for an int value.
      - The result of `gcd(x, x)`, `gcd(0, x)` and `gcd(x, 0)` is the absolute value of `x`, except for the special cases above.
      - The invocation `gcd(0, 0)` is the only one which returns `0`.
      Parameters:
        `p` - Number.
        `q` - Number.
      Returns:
        the greatest common divisor (never negative).
      Throws:
        `MathArithmeticException` - if the result cannot be represented as a non-negative `int` value.
      Since:
        1.1

    - #### gcdPositive

          private static int gcdPositive(int a,
                        int b)

      Computes the greatest common divisor of two positive numbers (this precondition is not checked and the result is undefined if not fulfilled) using the "binary gcd" method which avoids division and modulo operations. See Knuth 4.5.2 algorithm B. The algorithm is due to Josef Stein (1961).
      Special cases:
      - The result of `gcd(x, x)`, `gcd(0, x)` and `gcd(x, 0)` is the value of `x`.
      - The invocation `gcd(0, 0)` is the only one which returns `0`.
      Parameters:
        `a` - Positive number.
        `b` - Positive number.
      Returns:
        the greatest common divisor.

    - #### gcd

          public static long gcd(long p,
                 long q)
                          throws MathArithmeticException

      Gets the greatest common divisor of the absolute value of two numbers, using the "binary gcd" method which avoids division and modulo operations. See Knuth 4.5.2 algorithm B. This algorithm is due to Josef Stein (1961).

      Special cases:
      - The invocations `gcd(Long.MIN_VALUE, Long.MIN_VALUE)`, `gcd(Long.MIN_VALUE, 0L)` and `gcd(0L, Long.MIN_VALUE)` throw an `ArithmeticException`, because the result would be 2^63, which is too large for a long value.
      - The result of `gcd(x, x)`, `gcd(0L, x)` and `gcd(x, 0L)` is the absolute value of `x`, except for the special cases above.
      - The invocation `gcd(0L, 0L)` is the only one which returns `0L`.
      Parameters:
        `p` - Number.
        `q` - Number.
      Returns:
        the greatest common divisor, never negative.
      Throws:
        `MathArithmeticException` - if the result cannot be represented as a non-negative `long` value.
      Since:
        2.1

    - #### lcm

          public static int lcm(int a,
                int b)
                         throws MathArithmeticException

      Returns the least common multiple of the absolute value of two numbers, using the formula `lcm(a,b) = (a / gcd(a,b)) * b`.

      Special cases:
      - The invocations `lcm(Integer.MIN_VALUE, n)` and `lcm(n, Integer.MIN_VALUE)`, where `abs(n)` is a power of 2, throw an `ArithmeticException`, because the result would be 2^31, which is too large for an int value.
      - The result of `lcm(0, x)` and `lcm(x, 0)` is `0` for any `x`.
      Parameters:
        `a` - Number.
        `b` - Number.
      Returns:
        the least common multiple, never negative.
      Throws:
        `MathArithmeticException` - if the result cannot be represented as a non-negative `int` value.
      Since:
        1.1

    - #### lcm

          public static long lcm(long a,
                 long b)
                          throws MathArithmeticException

      Returns the least common multiple of the absolute value of two numbers, using the formula `lcm(a,b) = (a / gcd(a,b)) * b`.

      Special cases:
      - The invocations `lcm(Long.MIN_VALUE, n)` and `lcm(n, Long.MIN_VALUE)`, where `abs(n)` is a power of 2, throw an `ArithmeticException`, because the result would be 2^63, which is too large for an int value.
      - The result of `lcm(0L, x)` and `lcm(x, 0L)` is `0L` for any `x`.
      Parameters:
        `a` - Number.
        `b` - Number.
      Returns:
        the least common multiple, never negative.
      Throws:
        `MathArithmeticException` - if the result cannot be represented as a non-negative `long` value.
      Since:
        2.1

    - #### mulAndCheck

          public static int mulAndCheck(int x,
                        int y)
                                 throws MathArithmeticException

      Multiply two integers, checking for overflow.
      Parameters:
        `x` - Factor.
        `y` - Factor.
      Returns:
        the product `x * y`.
      Throws:
        `MathArithmeticException` - if the result can not be represented as an `int`.
      Since:
        1.1

    - #### mulAndCheck

          public static long mulAndCheck(long a,
                         long b)
                                  throws MathArithmeticException

      Multiply two long integers, checking for overflow.
      Parameters:
        `a` - Factor.
        `b` - Factor.
      Returns:
        the product `a * b`.
      Throws:
        `MathArithmeticException` - if the result can not be represented as a `long`.
      Since:
        1.2

    - #### subAndCheck

          public static int subAndCheck(int x,
                        int y)
                                 throws MathArithmeticException

      Subtract two integers, checking for overflow.
      Parameters:
        `x` - Minuend.
        `y` - Subtrahend.
      Returns:
        the difference `x - y`.
      Throws:
        `MathArithmeticException` - if the result can not be represented as an `int`.
      Since:
        1.1

    - #### subAndCheck

          public static long subAndCheck(long a,
                         long b)
                                  throws MathArithmeticException

      Subtract two long integers, checking for overflow.
      Parameters:
        `a` - Value.
        `b` - Value.
      Returns:
        the difference `a - b`.
      Throws:
        `MathArithmeticException` - if the result can not be represented as a `long`.
      Since:
        1.2

    - #### pow

          public static int pow(int k,
                int e)
                         throws NotPositiveException

      Raise an int to an int power.
      Parameters:
        `k` - Number to raise.
        `e` - Exponent (must be positive or zero).
      Returns:
        ke
      Throws:
        `NotPositiveException` - if `e < 0`.

    - #### pow

          public static int pow(int k,
                long e)
                         throws NotPositiveException

      Raise an int to a long power.
      Parameters:
        `k` - Number to raise.
        `e` - Exponent (must be positive or zero).
      Returns:
        ke
      Throws:
        `NotPositiveException` - if `e < 0`.

    - #### pow

          public static long pow(long k,
                 int e)
                          throws NotPositiveException

      Raise a long to an int power.
      Parameters:
        `k` - Number to raise.
        `e` - Exponent (must be positive or zero).
      Returns:
        ke
      Throws:
        `NotPositiveException` - if `e < 0`.

    - #### pow

          public static long pow(long k,
                 long e)
                          throws NotPositiveException

      Raise a long to a long power.
      Parameters:
        `k` - Number to raise.
        `e` - Exponent (must be positive or zero).
      Returns:
        ke
      Throws:
        `NotPositiveException` - if `e < 0`.

    - #### pow

          public static java.math.BigInteger pow(java.math.BigInteger k,
                                 int e)
                                          throws NotPositiveException

      Raise a BigInteger to an int power.
      Parameters:
        `k` - Number to raise.
        `e` - Exponent (must be positive or zero).
      Returns:
        ke
      Throws:
        `NotPositiveException` - if `e < 0`.

    - #### pow

          public static java.math.BigInteger pow(java.math.BigInteger k,
                                 long e)
                                          throws NotPositiveException

      Raise a BigInteger to a long power.
      Parameters:
        `k` - Number to raise.
        `e` - Exponent (must be positive or zero).
      Returns:
        ke
      Throws:
        `NotPositiveException` - if `e < 0`.

    - #### pow

          public static java.math.BigInteger pow(java.math.BigInteger k,
                                 java.math.BigInteger e)
                                          throws NotPositiveException

      Raise a BigInteger to a BigInteger power.
      Parameters:
        `k` - Number to raise.
        `e` - Exponent (must be positive or zero).
      Returns:
        ke
      Throws:
        `NotPositiveException` - if `e < 0`.

    - #### stirlingS2

          public static long stirlingS2(int n,
                        int k)
                                 throws NotPositiveException,
                                        NumberIsTooLargeException,
                                        MathArithmeticException

      Returns the Stirling number of the second kind, "`S(n,k)`", the number of ways of partitioning an `n`-element set into `k` non-empty subsets.

      The preconditions are `0 <= k <= n` (otherwise `NotPositiveException` is thrown)

      Parameters:
        `n` - the size of the set
        `k` - the number of non-empty subsets
      Returns:
        `S(n,k)`
      Throws:
        `NotPositiveException` - if `k < 0`.
        `NumberIsTooLargeException` - if `k > n`.
        `MathArithmeticException` - if some overflow happens, typically for n exceeding 25 and k between 20 and n-2 (S(n,n-1) is handled specifically and does not overflow)
      Since:
        3.1

    - #### addAndCheck

          private static long addAndCheck(long a,
                         long b,
                         Localizable pattern)
                                   throws MathArithmeticException

      Add two long integers, checking for overflow.
      Parameters:
        `a` - Addend.
        `b` - Addend.
        `pattern` - Pattern to use for any thrown exception.
      Returns:
        the sum `a + b`.
      Throws:
        `MathArithmeticException` - if the result cannot be represented as a `long`.
      Since:
        1.2

    - #### checkBinomial

          private static void checkBinomial(int n,
                           int k)
                                     throws NumberIsTooLargeException,
                                            NotPositiveException

      Check binomial preconditions.
      Parameters:
        `n` - Size of the set.
        `k` - Size of the subsets to be counted.
      Throws:
        `NotPositiveException` - if `n < 0`.
        `NumberIsTooLargeException` - if `k > n`.

    - #### isPowerOfTwo

          public static boolean isPowerOfTwo(long n)

      Returns true if the argument is a power of two.
      Parameters:
        `n` - the number to test
      Returns:
        true if the argument is a power of two

Copyright (c) 2003-2013 Apache Software Foundation