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 in Math.
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static class 
    Exception.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final String
    Negative exponent exception message part 1.
    private static final String
    Negative exponent exception message part 2.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Private constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    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.
    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
    pow(int k, int e)
    Raise an int to an int power.
    static long
    pow(long k, int e)
    Raise a long to an int 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 BigInteger
    Raise a BigInteger to a BigInteger power.
    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.
    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.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • NEGATIVE_EXPONENT_1

      private static final String NEGATIVE_EXPONENT_1
      Negative exponent exception message part 1.
      See Also:
    • NEGATIVE_EXPONENT_2

      private static final String NEGATIVE_EXPONENT_2
      Negative exponent exception message part 2.
      See Also:
  • Constructor Details

    • ArithmeticUtils

      private ArithmeticUtils()
      Private constructor.
  • Method Details

    • 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) 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.

      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-negative int value.
    • 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.

      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-negative long value.
    • 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:
      ArithmeticException - if the result cannot be represented as a non-negative int value.
    • 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:
      ArithmeticException - if the result cannot be represented as a non-negative long value.
    • pow

      public static int pow(int k, int e)
      Raise an int to an int power.

      Special cases:

      • k^0 returns 1 (including k=0)
      • k^1 returns k (including k=0)
      • 0^0 returns 1
      • 0^e returns 0
      • 1^e returns 1
      • (-1)^e returns -1 or 1 if e is odd or even
      Parameters:
      k - Number to raise.
      e - Exponent (must be positive or zero).
      Returns:
      \( k^e \)
      Throws:
      IllegalArgumentException - if e < 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^0 returns 1 (including k=0)
      • k^1 returns k (including k=0)
      • 0^0 returns 1
      • 0^e returns 0
      • 1^e returns 1
      • (-1)^e returns -1 or 1 if e is odd or even
      Parameters:
      k - Number to raise.
      e - Exponent (must be positive or zero).
      Returns:
      \( k^e \)
      Throws:
      IllegalArgumentException - if e < 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 - 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:
      IllegalArgumentException - 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:
      IllegalArgumentException - if e < 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 long datatype. Modern 64-bit processors make use of the long datatype faster than an algorithm using the int datatype. This method now delegates to Integer.remainderUnsigned(int, int) which uses long arithmetic; or from JDK 19 an intrinsic method.

      Parameters:
      dividend - the value to be divided
      divisor - the value doing the dividing
      Returns:
      the unsigned remainder of the first argument divided by the second argument.
      See Also:
    • 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 BigInteger datatype. The JDK implementation of Long.remainderUnsigned(long, long) uses BigInteger prior 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 divided
      divisor - the value doing the dividing
      Returns:
      the unsigned remainder of the first argument divided by the second argument.
      See Also:
    • 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 long datatype. Modern 64-bit processors make use of the long datatype faster than an algorithm using the int datatype. This method now delegates to Integer.divideUnsigned(int, int) which uses long arithmetic; or from JDK 19 an intrinsic method.

      Parameters:
      dividend - the value to be divided
      divisor - the value doing the dividing
      Returns:
      the unsigned quotient of the first argument divided by the second argument
      See Also:
    • 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 BigInteger datatype. The JDK implementation of Long.divideUnsigned(long, long) uses BigInteger prior 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 divided
      divisor - the value doing the dividing
      Returns:
      the unsigned quotient of the first argument divided by the second argument.
      See Also: