org.apache.commons.math3.util
Class ArithmeticUtils

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

public final class ArithmeticUtils
extends Object

Some useful, arithmetics related, additions to the built-in functions in Math.

Version:
$Id: ArithmeticUtils.java 1244107 2012-02-14 16:17:55Z erans $

Field Summary
(package private) static long[] FACTORIALS
          All long-representable factorials
 
Constructor Summary
private ArithmeticUtils()
          Private constructor.
 
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.
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)
           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 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 BigInteger pow(BigInteger k, BigInteger e)
          Raise a BigInteger to a BigInteger power.
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 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 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

Constructor Detail

ArithmeticUtils

private ArithmeticUtils()
Private constructor.

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:

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

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.

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:

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.

factorial

public static long factorial(int n)
Returns n!. Shorthand for n Factorial, the product of the numbers 1,...,n.

Preconditions:

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:

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:

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:

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:

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

pow

public static int pow(int k,
                      int e)
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)
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)
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)
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)
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)
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)
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.

addAndCheck

private static long addAndCheck(long a,
                                long b,
                                Localizable pattern)
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)
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