Package org.apache.commons.math3.util

# Class ArithmeticUtils

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

public final class ArithmeticUtils extends Object
Some useful, arithmetics related, additions to the built-in functions in `Math`.

## Method Summary

Modifier and Type
Method
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.
`static long`
`binomialCoefficient(int n, int k)`
Deprecated.
use `CombinatoricsUtils.binomialCoefficient(int, int)`
`static double`
`binomialCoefficientDouble(int n, int k)`
Deprecated.
use `CombinatoricsUtils.binomialCoefficientDouble(int, int)`
`static double`
`binomialCoefficientLog(int n, int k)`
Deprecated.
use `CombinatoricsUtils.binomialCoefficientLog(int, int)`
`static long`
`factorial(int n)`
Deprecated.
use `CombinatoricsUtils.factorial(int)`
`static double`
`factorialDouble(int n)`
Deprecated.
use `CombinatoricsUtils.factorialDouble(int)`
`static double`
`factorialLog(int n)`
Deprecated.
use `CombinatoricsUtils.factorialLog(int)`
`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.
`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 int`
`pow(int k, int e)`
Raise an int to an int power.
`static int`
`pow(int k, long e)`
Deprecated.
As of 3.3.
`static long`
`pow(long k, int e)`
Raise a long to an int power.
`static long`
`pow(long k, long e)`
Deprecated.
As of 3.3.
`static BigInteger`
`pow(BigInteger k, int e)`
Raise a BigInteger to an int power.
`static BigInteger`
`pow(BigInteger k, long e)`
Raise a BigInteger to a long power.
`static BigInteger`
`pow(BigInteger k, BigInteger e)`
Raise a BigInteger to a BigInteger power.
`static long`
`stirlingS2(int n, int k)`
Deprecated.
use `CombinatoricsUtils.stirlingS2(int, int)`
`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`

## Method Details

### 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

@Deprecated public static long binomialCoefficient(int n, int k) throws NotPositiveException, NumberIsTooLargeException, MathArithmeticException
Deprecated.
use `CombinatoricsUtils.binomialCoefficient(int, int)`
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

@Deprecated public static double binomialCoefficientDouble(int n, int k) throws NotPositiveException, NumberIsTooLargeException, MathArithmeticException
Deprecated.
use `CombinatoricsUtils.binomialCoefficientDouble(int, int)`
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 invalid input: '<' 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

@Deprecated public static double binomialCoefficientLog(int n, int k) throws NotPositiveException, NumberIsTooLargeException, MathArithmeticException
Deprecated.
use `CombinatoricsUtils.binomialCoefficientLog(int, int)`
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

@Deprecated public static long factorial(int n) throws NotPositiveException, MathArithmeticException
Deprecated.
use `CombinatoricsUtils.factorial(int)`
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!` invalid input: '<' 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

@Deprecated public static double factorialDouble(int n) throws NotPositiveException
Deprecated.
use `CombinatoricsUtils.factorialDouble(int)`
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

@Deprecated public static double factorialLog(int n) throws NotPositiveException
Deprecated.
use `CombinatoricsUtils.factorialLog(int)`
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

### 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, MathArithmeticException
Raise an int to an int power.

Parameters:
  `k` - Number to raise.
  `e` - Exponent (must be positive or zero).
Returns:
  \( k^e \)
Throws:
  `NotPositiveException` - if `e < 0`.
  `MathArithmeticException` - if the result would overflow.

### pow

@Deprecated public static int pow(int k, long e) throws NotPositiveException
Deprecated.
As of 3.3. Please use `pow(int,int)` instead.
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, MathArithmeticException
Raise a long to an int power.

Parameters:
  `k` - Number to raise.
  `e` - Exponent (must be positive or zero).
Returns:
  \( k^e \)
Throws:
  `NotPositiveException` - if `e < 0`.
  `MathArithmeticException` - if the result would overflow.

### pow

@Deprecated public static long pow(long k, long e) throws NotPositiveException
Deprecated.
As of 3.3. Please use `pow(long,int)` instead.
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 BigInteger pow(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 BigInteger pow(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 BigInteger pow(BigInteger k, 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

@Deprecated public static long stirlingS2(int n, int k) throws NotPositiveException, NumberIsTooLargeException, MathArithmeticException
Deprecated.
use `CombinatoricsUtils.stirlingS2(int, int)`
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

### 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