org.apache.commons.math.util
Class ArithmeticUtils

java.lang.Object
  org.apache.commons.math.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 1182787 2011-10-13 11:20:48Z celestin $

Method Summary

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) 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.
static long	factorial(int n) Returns n!.
static double	factorialDouble(int n) Compute n!
static double	factorialLog(int n) Compute the natural logarithm of the factorial of n.
static int	gcd(int p, int 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 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 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	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 Detail

addAndCheck

public static int addAndCheck(int x,
                              int y)

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)

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)

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:

MathIllegalArgumentException - if preconditions are not met.

MathArithmeticException - if the result is too large to be represented by a long integer.

binomialCoefficientDouble

public 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.

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:

java.lang.IllegalArgumentException - if preconditions are not met.

binomialCoefficientLog

public 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.

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:

java.lang.IllegalArgumentException - if preconditions are not met.

factorial

public static long factorial(int n)

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)

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)

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)

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(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)

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)

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)

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)

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)

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)

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)

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