Class ArithmeticUtils
- java.lang.Object
-
- org.apache.commons.numbers.core.ArithmeticUtils
-
public final class ArithmeticUtils extends Object
Some useful, arithmetics related, additions to the built-in functions inMath.
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static intdivideUnsigned(int dividend, int divisor)Returns the unsigned quotient of dividing the first argument by the second where each argument and the result is interpreted as an unsigned value.static longdivideUnsigned(long dividend, long divisor)Returns the unsigned quotient of dividing the first argument by the second where each argument and the result is interpreted as an unsigned value.static intgcd(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 longgcd(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 booleanisPowerOfTwo(long n)Returns true if the argument is a power of two.static intlcm(int a, int b)Returns the least common multiple of the absolute value of two numbers, using the formulalcm(a,b) = (a / gcd(a,b)) * b.static longlcm(long a, long b)Returns the least common multiple of the absolute value of two numbers, using the formulalcm(a,b) = (a / gcd(a,b)) * b.static intpow(int k, int e)Raise an int to an int power.static longpow(long k, int e)Raise a long to an int power.static BigIntegerpow(BigInteger k, int e)Raise a BigInteger to an int power.static BigIntegerpow(BigInteger k, long e)Raise a BigInteger to a long power.static BigIntegerpow(BigInteger k, BigInteger e)Raise a BigInteger to a BigInteger power.static intremainderUnsigned(int dividend, int divisor)Returns the unsigned remainder from dividing the first argument by the second where each argument and the result is interpreted as an unsigned value.static longremainderUnsigned(long dividend, long divisor)Returns the unsigned remainder from dividing the first argument by the second where each argument and the result is interpreted as an unsigned value.
-
-
-
Method Detail
-
gcd
public 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. 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)andgcd(0, Integer.MIN_VALUE)throw anArithmeticException, because the result would be 2^31, which is too large for an int value. - The result of
gcd(x, x),gcd(0, x)andgcd(x, 0)is the absolute value ofx, except for the special cases above. - The invocation
gcd(0, 0)is the only one which returns0.
Two numbers are relatively prime, or coprime, if their gcd is 1.
- Parameters:
p- Number.q- Number.- Returns:
- the greatest common divisor (never negative).
- Throws:
ArithmeticException- if the result cannot be represented as a non-negativeintvalue.
- The invocations
-
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)andgcd(0L, Long.MIN_VALUE)throw anArithmeticException, because the result would be 2^63, which is too large for a long value. - The result of
gcd(x, x),gcd(0L, x)andgcd(x, 0L)is the absolute value ofx, except for the special cases above. - The invocation
gcd(0L, 0L)is the only one which returns0L.
Two numbers are relatively prime, or coprime, if their gcd is 1.
- Parameters:
p- Number.q- Number.- Returns:
- the greatest common divisor, never negative.
- Throws:
ArithmeticException- if the result cannot be represented as a non-negativelongvalue.
- The invocations
-
lcm
public static int lcm(int a, int b)
Returns the least common multiple of the absolute value of two numbers, using the formula
Special cases:lcm(a,b) = (a / gcd(a,b)) * b.- The invocations
lcm(Integer.MIN_VALUE, n)andlcm(n, Integer.MIN_VALUE), whereabs(n)is a power of 2, throw anArithmeticException, because the result would be 2^31, which is too large for an int value. - The result of
lcm(0, x)andlcm(x, 0)is0for anyx.
- Parameters:
a- Number.b- Number.- Returns:
- the least common multiple, never negative.
- Throws:
ArithmeticException- if the result cannot be represented as a non-negativeintvalue.
- The invocations
-
lcm
public static long lcm(long a, long b)
Returns the least common multiple of the absolute value of two numbers, using the formula
Special cases:lcm(a,b) = (a / gcd(a,b)) * b.- The invocations
lcm(Long.MIN_VALUE, n)andlcm(n, Long.MIN_VALUE), whereabs(n)is a power of 2, throw anArithmeticException, because the result would be 2^63, which is too large for an int value. - The result of
lcm(0L, x)andlcm(x, 0L)is0Lfor anyx.
- Parameters:
a- Number.b- Number.- Returns:
- the least common multiple, never negative.
- Throws:
ArithmeticException- if the result cannot be represented as a non-negativelongvalue.
- The invocations
-
pow
public static int pow(int k, int e)
Raise an int to an int power.Special cases:
k^0returns1(includingk=0)k^1returnsk(includingk=0)0^0returns10^ereturns01^ereturns1(-1)^ereturns-1 or 1ifeis odd or even
- Parameters:
k- Number to raise.e- Exponent (must be positive or zero).- Returns:
- \( k^e \)
- Throws:
IllegalArgumentException- ife < 0.ArithmeticException- if the result would overflow.
-
pow
public static long pow(long k, int e)
Raise a long to an int power.Special cases:
k^0returns1(includingk=0)k^1returnsk(includingk=0)0^0returns10^ereturns01^ereturns1(-1)^ereturns-1 or 1ifeis odd or even
- Parameters:
k- Number to raise.e- Exponent (must be positive or zero).- Returns:
- \( k^e \)
- Throws:
IllegalArgumentException- ife < 0.ArithmeticException- if the result would overflow.
-
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:
IllegalArgumentException- ife < 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:
IllegalArgumentException- ife < 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:
IllegalArgumentException- ife < 0.
-
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
-
remainderUnsigned
public static int remainderUnsigned(int dividend, int divisor)
Returns the unsigned remainder from dividing the first argument by the second where each argument and the result is interpreted as an unsigned value.Implementation note
In v1.0 this method did not use the
longdatatype. Modern 64-bit processors make use of thelongdatatype faster than an algorithm using theintdatatype. This method now delegates toInteger.remainderUnsigned(int, int)which useslongarithmetic; or from JDK 19 an intrinsic method.- Parameters:
dividend- the value to be divideddivisor- the value doing the dividing- Returns:
- the unsigned remainder of the first argument divided by the second argument.
- See Also:
Integer.remainderUnsigned(int, int)
-
remainderUnsigned
public static long remainderUnsigned(long dividend, long divisor)
Returns the unsigned remainder from dividing the first argument by the second where each argument and the result is interpreted as an unsigned value.Implementation note
This method does not use the
BigIntegerdatatype. The JDK implementation ofLong.remainderUnsigned(long, long)usesBigIntegerprior to JDK 17 and this method is 15-25x faster. From JDK 17 onwards the JDK implementation is as fast; or from JDK 19 even faster due to use of an intrinsic method.- Parameters:
dividend- the value to be divideddivisor- the value doing the dividing- Returns:
- the unsigned remainder of the first argument divided by the second argument.
- See Also:
Long.remainderUnsigned(long, long)
-
divideUnsigned
public static int divideUnsigned(int dividend, int divisor)
Returns the unsigned quotient of dividing the first argument by the second where each argument and the result is interpreted as an unsigned value.Note that in two's complement arithmetic, the three other basic arithmetic operations of add, subtract, and multiply are bit-wise identical if the two operands are regarded as both being signed or both being unsigned. Therefore separate
addUnsigned, etc. methods are not provided.Implementation note
In v1.0 this method did not use the
longdatatype. Modern 64-bit processors make use of thelongdatatype faster than an algorithm using theintdatatype. This method now delegates toInteger.divideUnsigned(int, int)which useslongarithmetic; or from JDK 19 an intrinsic method.- Parameters:
dividend- the value to be divideddivisor- the value doing the dividing- Returns:
- the unsigned quotient of the first argument divided by the second argument
- See Also:
Integer.divideUnsigned(int, int)
-
divideUnsigned
public static long divideUnsigned(long dividend, long divisor)
Returns the unsigned quotient of dividing the first argument by the second where each argument and the result is interpreted as an unsigned value.Note that in two's complement arithmetic, the three other basic arithmetic operations of add, subtract, and multiply are bit-wise identical if the two operands are regarded as both being signed or both being unsigned. Therefore separate
addUnsigned, etc. methods are not provided.Implementation note
This method does not use the
BigIntegerdatatype. The JDK implementation ofLong.divideUnsigned(long, long)usesBigIntegerprior to JDK 17 and this method is 15-25x faster. From JDK 17 onwards the JDK implementation is as fast; or from JDK 19 even faster due to use of an intrinsic method.- Parameters:
dividend- the value to be divideddivisor- the value doing the dividing- Returns:
- the unsigned quotient of the first argument divided by the second argument.
- See Also:
Long.divideUnsigned(long, long)
-
-