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.

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) 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.
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) Deprecated. As of 3.3. Please use pow(int,int) instead.
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. Please use pow(long,int) instead.
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

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

@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 < 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! < 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

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,
                      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:

k^e

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:

k^e

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:

k^e

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:

k^e

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:

k^e

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

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

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