Package org.jscience.mathematics.number

Class LargeInteger

java.lang.Object
java.lang.Number
org.jscience.mathematics.number.Number<LargeInteger>
org.jscience.mathematics.number.LargeInteger
All Implemented Interfaces:
Serializable, Comparable<LargeInteger>, javolution.lang.Immutable, javolution.lang.Realtime, javolution.lang.ValueType, javolution.xml.XMLSerializable, GroupAdditive<LargeInteger>, Ring<LargeInteger>, Structure<LargeInteger>
public final class LargeInteger extends Number<LargeInteger>

This class represents an immutable integer number of arbitrary size.

It has the following advantages over the java.math.BigInteger class:

  • Optimized for 64 bits architectures. But still runs significantly faster on 32 bits processors.
  • Real-time compliant for improved performance and predictability (no garbage generated when executing in StackContext).
  • Improved algorithms (e.g. Concurrent Karabutsa multiplication in O(nLog3) instead of O(n2).

Note: This class uses ConcurrentContext to accelerate calculations on multi-cores systems.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final LargeInteger
    ONE
    The large integer representing the multiplicative identity.
    static final javolution.lang.Configurable<Integer>
    PRIME_CERTAINTY
    Holds the certainty required when testing for primality (default 100, the probability for a composite to pass the primality test is less than 2-100).
    static final LargeInteger
    ZERO
    The large integer representing the additive identity.

  • Method Summary

    Modifier and Type
    Method
    Description
    LargeInteger
    abs()
    Returns the absolute value of this large integer.
    int
    bitLength()
    Returns the minimal number of bits to represent this large integer in the minimal two's-complement (sign excluded).
    int
    compareTo(long value)
    Compares this large integer to the specified long value.
    int
    compareTo(LargeInteger that)
    Compares two large integers numerically.
    LargeInteger
    copy()
    Returns a copy of this number allocated by the calling thread (possibly on the stack).
    int
    digitLength()
    Returns the minimal number of decimal digits necessary to represent this large integer (sign excluded).
    LargeInteger
    divide(int divisor)
    Returns this large integer divided by the specified int divisor.
    LargeInteger
    divide(LargeInteger that)
    Returns this large integer divided by the one specified (integer division).
    double
    doubleValue()
    Returns the value of this large integer as a double.
    boolean
    equals(long value)
    Compares this large integer against the specified long value.
    boolean
    equals(Object that)
    Compares this large integer against the specified object.
    static Appendable
    format(LargeInteger li, int radix, Appendable out)
    Formats the specified large integer in the specified radix and into the specified Appendable argument.
    LargeInteger
    gcd(LargeInteger that)
    Returns the greatest common divisor of this large integer and the one specified.
    int
    getLowestSetBit()
    Returns the index of the lowest-order one bit in this large integer or -1 if this.equals(ZERO).
    LargeInteger
    getRemainder()
    Returns the final undivided part after division that is less or of lower degree than the divisor.
    int
    hashCode()
    Returns the hash code for this large integer number.
    LargeInteger
    inverseScaled(int precision)
    Returns a scaled approximation of 1 / this.
    boolean
    isEven()
    Indicates if this large integer is an even number.
    boolean
    isLargerThan(LargeInteger that)
    Indicates if this large integer is larger than the one specified in absolute value.
    boolean
    isNegative()
    Indicates if this large integer is less than ZERO.
    boolean
    isOdd()
    Indicates if this large integer is an odd number.
    boolean
    isPositive()
    Indicates if this large integer is greater than ZERO (ZEROis not included).
    boolean
    isPowerOfTwo()
    Indicates if this number is a power of two (equals to 2 (bitLength() - 1)).
    boolean
    isProbablyPrime()
    Indicates if this large integer is probably prime.
    boolean
    isZero()
    Indicates if this large integer is equal to ZERO.
    long
    longValue()
    Returns the low order bits of this large integer as a long.
    LargeInteger
    minus(long value)
    Returns the difference between this large integer and the specified value
    LargeInteger
    minus(LargeInteger that)
    Returns the difference between this large integer and the one specified.
    LargeInteger
    mod(LargeInteger m)
    Returns this large integer modulo the specified large integer.
    LargeInteger
    modInverse(LargeInteger m)
    Returns the large integer whose value is (this-1 mod m) .
    LargeInteger
    modPow(LargeInteger exp, LargeInteger m)
    Returns this large integer raised at the specified exponent modulo the specified modulus.
    LargeInteger
    opposite()
    Returns the opposite of this large integer.
    static LargeInteger
    parse(CharSequence csq, int radix, javolution.text.TextFormat.Cursor cursor)
    Parses the specified character sequence from the specified position as a large integer in the specified radix.
    LargeInteger
    plus(long value)
    Returns the sum of this large integer with the specified long integer (convenience method)
    LargeInteger
    plus(LargeInteger that)
    Returns the sum of this large integer with the one specified.
    LargeInteger
    remainder(LargeInteger that)
    Returns the remainder of the division of this large integer with the one specified (convenience method equivalent to this.divide(that).getRemainder()).
    LargeInteger
    shiftLeft(int n)
    Returns the value of this large integer after performing a binary shift to left.
    LargeInteger
    shiftRight(int n)
    Returns the value of this large integer after performing a binary shift to right with sign extension (-1 >> 1 == -1).
    LargeInteger
    sqrt()
    Returns the integer square root of this integer.
    LargeInteger
    times(long multiplier)
    Returns the product of this large integer with the specified long multiplier.
    LargeInteger
    times(LargeInteger that)
    Returns the product of this large integer with the one specified.
    LargeInteger
    times10pow(int n)
    Returns the value of this large integer after multiplication by a power of ten.
    LargeInteger
    times2pow(int n)
    Returns the value of this large integer after multiplication by a power of two.
    int
    toByteArray(byte[] bytes, int offset)
    Returns the two's-complement binary representation of this large integer.
    javolution.text.Text
    toText()
    Returns the text representation of this number using the current format.
    javolution.text.Text
    toText(int radix)
    Returns the text representation of this number in the specified radix.
    static LargeInteger
    valueOf(byte[] bytes, int offset, int length)
    Returns the large integer of specified two's-complement binary representation.
    static LargeInteger
    valueOf(long value)
    Returns the large integer of specified long value.
    static LargeInteger
    valueOf(CharSequence csq)
    Returns the large integer for the specified character sequence using the current format.
    static LargeInteger
    valueOf(CharSequence csq, int radix)
    Returns the large integer for the specified character sequence in the specified radix.
    static LargeInteger
    valueOf(BigInteger bigInteger)
    Returns the large integer corresponding to the specified java.math.BigInteger instance.

    Methods inherited from class org.jscience.mathematics.number.Number

    byteValue, floatValue, intValue, isGreaterThan, isLessThan, pow, shortValue, toString

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • PRIME_CERTAINTY

      public static final javolution.lang.Configurable<Integer> PRIME_CERTAINTY
      Holds the certainty required when testing for primality (default 100, the probability for a composite to pass the primality test is less than 2-100).

    • ZERO

      public static final LargeInteger ZERO
      The large integer representing the additive identity.

    • ONE

      public static final LargeInteger ONE
      The large integer representing the multiplicative identity.

  • Method Details

    • valueOf

      public static LargeInteger valueOf(long value)
      Returns the large integer of specified long value.
      Parameters:
      value - the long value.
      Returns:
      the corresponding large integer number.

    • valueOf

      public static LargeInteger valueOf(byte[] bytes, int offset, int length)
      Returns the large integer of specified two's-complement binary representation. The input array is assumed to be in big-endian byte-order: the most significant byte is at the offset position.
      Parameters:
      bytes - the binary representation (two's-complement).
      offset - the offset at which to start reading the bytes.
      length - the maximum number of bytes to read.
      Returns:
      the corresponding large integer number.
      Throws:
      IndexOutOfBoundsException - if offset + length > bytes.length
      See Also:

    • toByteArray

      public int toByteArray(byte[] bytes, int offset)
      Returns the two's-complement binary representation of this large integer. The output array is in big-endian byte-order: the most significant byte is at the offset position.
      Parameters:
      bytes - the bytes to hold the binary representation (two's-complement) of this large integer.
      offset - the offset at which to start writing the bytes.
      Returns:
      the number of bytes written.
      Throws:
      IndexOutOfBoundsException - if bytes.length < (bitLength() >> 3) + 1
      See Also:

    • valueOf

      public static LargeInteger valueOf(CharSequence csq)
      Returns the large integer for the specified character sequence using the current format.
      Parameters:
      csq - the character sequence to parse.
      Returns:
      TextFormat.getInstance(LargeInteger.class).parse(csq)
      Throws:
      NumberFormatException - if error when parsing.

    • valueOf

      public static LargeInteger valueOf(CharSequence csq, int radix)
      Returns the large integer for the specified character sequence in the specified radix.
      Parameters:
      csq - the character sequence to parse.
      radix - the radix of the representation.
      Returns:
      LargeInteger.parse(csq, radix, cursor)
      Throws:
      NumberFormatException - if error when parsing.

    • valueOf

      public static LargeInteger valueOf(BigInteger bigInteger)
      Returns the large integer corresponding to the specified java.math.BigInteger instance.
      Parameters:
      bigInteger - the big integer instance.
      Returns:
      the large integer having the same value.

    • isPositive

      public boolean isPositive()
      Indicates if this large integer is greater than ZERO (ZEROis not included).
      Returns:
      this > ZERO

    • isNegative

      public boolean isNegative()
      Indicates if this large integer is less than ZERO.
      Returns:
      this < ZERO

    • isZero

      public boolean isZero()
      Indicates if this large integer is equal to ZERO.
      Returns:
      this == ZERO

    • isEven

      public boolean isEven()
      Indicates if this large integer is an even number.
      Returns:
      (this & 1) == ZERO

    • isOdd

      public boolean isOdd()
      Indicates if this large integer is an odd number.
      Returns:
      (this & 1) != ZERO

    • isProbablyPrime

      public boolean isProbablyPrime()
      Indicates if this large integer is probably prime.
      Returns:
      true if this large integer is probable prime; false otherwise.

    • bitLength

      public int bitLength()
      Returns the minimal number of bits to represent this large integer in the minimal two's-complement (sign excluded).
      Returns:
      the length of this integer in bits (sign excluded).

    • digitLength

      public int digitLength()
      Returns the minimal number of decimal digits necessary to represent this large integer (sign excluded).
      Returns:
      the maximum number of digits.

    • isPowerOfTwo

      public boolean isPowerOfTwo()
      Indicates if this number is a power of two (equals to 2 (bitLength() - 1)).
      Returns:
      true if this number is a power of two; false otherwise.

    • getLowestSetBit

      public int getLowestSetBit()
      Returns the index of the lowest-order one bit in this large integer or -1 if this.equals(ZERO).
      Returns:
      the index of the rightmost bit set or -1

    • getRemainder

      public LargeInteger getRemainder()
      Returns the final undivided part after division that is less or of lower degree than the divisor. This value is only set by the divide(org.jscience.mathematics.number.LargeInteger) operation and is not considered as part of this large integer (ignored by all methods).
      Returns:
      the remainder of the division for which this large integer is the quotient.

    • isLargerThan

      public boolean isLargerThan(LargeInteger that)
      Indicates if this large integer is larger than the one specified in absolute value.
      Specified by:
      isLargerThan in class Number<LargeInteger>
      Parameters:
      that - the integer to be compared with.
      Returns:
      this.abs().compareTo(that.abs()) > 0.

    • abs

      public LargeInteger abs()
      Returns the absolute value of this large integer.
      Returns:
      |this|.

    • opposite

      public LargeInteger opposite()
      Returns the opposite of this large integer.
      Returns:
      -this.

    • plus

      public LargeInteger plus(long value)
      Returns the sum of this large integer with the specified long integer (convenience method)
      Parameters:
      value - the long integer being added.
      Returns:
      this + value.

    • plus

      public LargeInteger plus(LargeInteger that)
      Returns the sum of this large integer with the one specified.
      Parameters:
      that - the integer to be added.
      Returns:
      this + that.

    • minus

      public LargeInteger minus(LargeInteger that)
      Returns the difference between this large integer and the one specified.
      Overrides:
      minus in class Number<LargeInteger>
      Parameters:
      that - the integer to be subtracted.
      Returns:
      this - that.

    • minus

      public LargeInteger minus(long value)
      Returns the difference between this large integer and the specified value
      Parameters:
      value - the value to be subtracted.
      Returns:
      this - value.

    • times

      public LargeInteger times(LargeInteger that)
      Returns the product of this large integer with the one specified.
      Parameters:
      that - the large integer multiplier.
      Returns:
      this · that.

    • times

      public LargeInteger times(long multiplier)
      Returns the product of this large integer with the specified long multiplier.
      Parameters:
      multiplier - the long multiplier.
      Returns:
      this · multiplier.

    • divide

      public LargeInteger divide(LargeInteger that)
      Returns this large integer divided by the one specified (integer division). The remainder of this division is accessible using getRemainder().
      Parameters:
      that - the integer divisor.
      Returns:
      this / that and this % that (getRemainder())
      Throws:
      ArithmeticException - if that.equals(ZERO)

    • divide

      public LargeInteger divide(int divisor)
      Returns this large integer divided by the specified int divisor. The remainder of this division is accessible using getRemainder().
      Parameters:
      divisor - the int divisor.
      Returns:
      this / divisor and this % divisor (getRemainder())
      Throws:
      ArithmeticException - if divisor == 0

    • remainder

      public LargeInteger remainder(LargeInteger that)
      Returns the remainder of the division of this large integer with the one specified (convenience method equivalent to this.divide(that).getRemainder()).
      Parameters:
      that - the value by which this integer is to be divided, and the remainder returned.
      Returns:
      this % that
      Throws:
      ArithmeticException - if that.equals(ZERO)
      See Also:

    • inverseScaled

      public LargeInteger inverseScaled(int precision)
      Returns a scaled approximation of 1 / this.
      Parameters:
      precision - the requested precision (reciprocal error being ± 1).
      Returns:
      2(precision + this.bitLength()) / this
      Throws:
      ArithmeticException - if this.isZero()

    • sqrt

      public LargeInteger sqrt()
      Returns the integer square root of this integer.
      Returns:
      k such as k^2 <= this < (k + 1)^2
      Throws:
      ArithmeticException - if this integer is negative.

    • mod

      public LargeInteger mod(LargeInteger m)
      Returns this large integer modulo the specified large integer.

      Note: The result as the same sign as the divisor unlike the Java remainder (%) operator (which as the same sign as the dividend).

      Parameters:
      m - the modulus.
      Returns:
      this mod m
      See Also:

    • modInverse

      public LargeInteger modInverse(LargeInteger m)
      Returns the large integer whose value is (this-1 mod m) .
      Parameters:
      m - the modulus.
      Returns:
      this-1 mod m.
      Throws:
      ArithmeticException - m <= 0, or this integer has no multiplicative inverse mod m (that is, this integer is not relatively prime to m).

    • modPow

      public LargeInteger modPow(LargeInteger exp, LargeInteger m)
      Returns this large integer raised at the specified exponent modulo the specified modulus.
      Parameters:
      exp - the exponent.
      m - the modulus.
      Returns:
      thisexp mod m
      Throws:
      ArithmeticException - m <= 0
      See Also:

    • gcd

      public LargeInteger gcd(LargeInteger that)
      Returns the greatest common divisor of this large integer and the one specified.
      Parameters:
      that - the other number to compute the GCD with.
      Returns:
      a positive number or ZERO if (this.isZero() && that.isZero()).

    • shiftLeft

      public LargeInteger shiftLeft(int n)
      Returns the value of this large integer after performing a binary shift to left. The shift distance, n, may be negative, in which case this method performs a right shift.
      Parameters:
      n - the shift distance, in bits.
      Returns:
      this << n.
      See Also:

    • shiftRight

      public LargeInteger shiftRight(int n)
      Returns the value of this large integer after performing a binary shift to right with sign extension (-1 >> 1 == -1). The shift distance, n, may be negative, in which case this method performs a shiftLeft(int).
      Parameters:
      n - the shift distance, in bits.
      Returns:
      this >> n.

    • times2pow

      public LargeInteger times2pow(int n)
      Returns the value of this large integer after multiplication by a power of two. This method is equivalent to shiftLeft(int) for positive n; but is different from shiftRight(int) for negative n as no sign extension is performed (-1 >>> 1 == 0).
      Parameters:
      n - the power of 2 exponent.
      Returns:
      this · 2n.

    • times10pow

      public LargeInteger times10pow(int n)
      Returns the value of this large integer after multiplication by a power of ten. For example:[code] LargeInteger billion = LargeInteger.ONE.times10pow(9); // 1E9 LargeInteger million = billion.times10pow(-3);[/code]
      Parameters:
      n - the decimal exponent.
      Returns:
      this · 10n

    • equals

      public boolean equals(Object that)
      Compares this large integer against the specified object.
      Specified by:
      equals in class Number<LargeInteger>
      Parameters:
      that - the object to compare with.
      Returns:
      true if the objects are the same; false otherwise.

    • equals

      public boolean equals(long value)
      Compares this large integer against the specified long value.
      Parameters:
      value - long value to compare with.
      Returns:
      true if this large integer has the specified value; false otherwise.

    • hashCode

      public int hashCode()
      Returns the hash code for this large integer number.
      Specified by:
      hashCode in class Number<LargeInteger>
      Returns:
      the hash code value.

    • longValue

      public long longValue()
      Returns the low order bits of this large integer as a long.

      Note: This conversion can lose information about the overall magnitude of the integer value and may return a result with the opposite sign.

      Specified by:
      longValue in class Number<LargeInteger>
      Returns:
      the numeric value represented by this integer after conversion to type long.

    • doubleValue

      public double doubleValue()
      Returns the value of this large integer as a double.
      Specified by:
      doubleValue in class Number<LargeInteger>
      Returns:
      the numeric value represented by this integer after conversion to type double.

    • compareTo

      public int compareTo(LargeInteger that)
      Compares two large integers numerically.
      Specified by:
      compareTo in interface Comparable<LargeInteger>
      Specified by:
      compareTo in class Number<LargeInteger>
      Parameters:
      that - the integer to compare with.
      Returns:
      -1, 0 or 1 as this integer is numerically less than, equal to, or greater than that.
      Throws:
      ClassCastException - that is not a large integer.

    • compareTo

      public int compareTo(long value)
      Compares this large integer to the specified long value.
      Parameters:
      value - the long value to compare with.
      Returns:
      -1, 0 or 1 as this integer is numerically less than, equal to, or greater than the specified value.

    • copy

      public LargeInteger copy()
      Description copied from class: Number
      Returns a copy of this number allocated by the calling thread (possibly on the stack).
      Specified by:
      copy in interface javolution.lang.ValueType
      Specified by:
      copy in class Number<LargeInteger>
      Returns:
      an identical and independant copy of this number.

    • toText

      public javolution.text.Text toText()
      Returns the text representation of this number using the current format.
      Specified by:
      toText in interface javolution.lang.Realtime
      Specified by:
      toText in class Number<LargeInteger>
      Returns:
      TextFormat.getInstance(LargeInteger.class).format(this)

    • toText

      public javolution.text.Text toText(int radix)
      Returns the text representation of this number in the specified radix.
      Parameters:
      radix - the radix of the representation.
      Returns:
      the text representation of this number in the specified radix.

    • parse

      public static LargeInteger parse(CharSequence csq, int radix, javolution.text.TextFormat.Cursor cursor)
      Parses the specified character sequence from the specified position as a large integer in the specified radix.
      Parameters:
      csq - the character sequence to parse.
      radix - the radix to be used while parsing.
      cursor - the current cursor position (being maintained).
      Returns:
      the corresponding large integer.
      Throws:
      NumberFormatException - if error when parsing.

    • format

      public static Appendable format(LargeInteger li, int radix, Appendable out) throws IOException
      Formats the specified large integer in the specified radix and into the specified Appendable argument.
      Parameters:
      li - the large integer to format.
      radix - the radix.
      out - the Appendable to append.
      Returns:
      the specified Appendable object.
      Throws:
      IllegalArgumentException - if radix is not in [2 .. 36] range.
      IOException - if an I/O exception occurs.