LargeInteger
org.jscience.mathematics.number

Class 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 LargeIntegerextends 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:
    Wikipedia: Arbitrary-precision Arithmetic, Serialized Form
    • Field Summary

      Fields 
      Modifier and TypeField and Description
      static LargeIntegerONE
      The large integer representing the multiplicative identity.
      static 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 LargeIntegerZERO
      The large integer representing the additive identity.
    • Method Summary

      Methods 
      Modifier and TypeMethod and Description
      LargeIntegerabs()
      Returns the absolute value of this large integer.
      intbitLength()
      Returns the minimal number of bits to represent this large integer in the minimal two\'s-complement (sign excluded).
      intcompareTo(LargeInteger that)
      Compares two large integers numerically.
      intcompareTo(long value)
      Compares this large integer to the specified long value.
      LargeIntegercopy()
      Returns a copy of this number allocated by the calling thread (possibly on the stack).
      intdigitLength()
      Returns the minimal number of decimal digits necessary to represent this large integer (sign excluded).
      LargeIntegerdivide(int divisor)
      Returns this large integer divided by the specified int divisor.
      LargeIntegerdivide(LargeInteger that)
      Returns this large integer divided by the one specified (integer division).
      doubledoubleValue()
      Returns the value of this large integer as a double.
      booleanequals(long value)
      Compares this large integer against the specified long value.
      booleanequals(Object that)
      Compares this large integer against the specified object.
      static Appendableformat(LargeInteger li, int radix, Appendable out)
      Formats the specified large integer in the specified radix and into the specified Appendable argument.
      LargeIntegergcd(LargeInteger that)
      Returns the greatest common divisor of this large integer and the one specified.
      intgetLowestSetBit()
      Returns the index of the lowest-order one bit in this large integer or -1 if this.equals(ZERO).
      LargeIntegergetRemainder()
      Returns the final undivided part after division that is less or of lower degree than the divisor.
      inthashCode()
      Returns the hash code for this large integer number.
      LargeIntegerinverseScaled(int precision)
      Returns a scaled approximation of 1 / this.
      booleanisEven()
      Indicates if this large integer is an even number.
      booleanisLargerThan(LargeInteger that)
      Indicates if this large integer is larger than the one specified in absolute value.
      booleanisNegative()
      Indicates if this large integer is less than ZERO.
      booleanisOdd()
      Indicates if this large integer is an odd number.
      booleanisPositive()
      Indicates if this large integer is greater than ZERO (ZEROis not included).
      booleanisPowerOfTwo()
      Indicates if this number is a power of two (equals to 2 (bitLength() - 1)).
      booleanisProbablyPrime()
      Indicates if this large integer is probably prime.
      booleanisZero()
      Indicates if this large integer is equal to ZERO.
      longlongValue()
      Returns the low order bits of this large integer as a long.
      LargeIntegerminus(LargeInteger that)
      Returns the difference between this large integer and the one specified.
      LargeIntegerminus(long value)
      Returns the difference between this large integer and the specified value
      LargeIntegermod(LargeInteger m)
      Returns this large integer modulo the specified large integer.
      LargeIntegermodInverse(LargeInteger m)
      Returns the large integer whose value is (this-1 mod m) .
      LargeIntegermodPow(LargeInteger exp, LargeInteger m)
      Returns this large integer raised at the specified exponent modulo the specified modulus.
      LargeIntegeropposite()
      Returns the opposite of this large integer.
      static LargeIntegerparse(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.
      LargeIntegerplus(LargeInteger that)
      Returns the sum of this large integer with the one specified.
      LargeIntegerplus(long value)
      Returns the sum of this large integer with the specified long integer (convenience method)
      LargeIntegerremainder(LargeInteger that)
      Returns the remainder of the division of this large integer with the one specified (convenience method equivalent to this.divide(that).getRemainder()).
      LargeIntegershiftLeft(int n)
      Returns the value of this large integer after performing a binary shift to left.
      LargeIntegershiftRight(int n)
      Returns the value of this large integer after performing a binary shift to right with sign extension (-1 >> 1 == -1).
      LargeIntegersqrt()
      Returns the integer square root of this integer.
      LargeIntegertimes(LargeInteger that)
      Returns the product of this large integer with the one specified.
      LargeIntegertimes(long multiplier)
      Returns the product of this large integer with the specified long multiplier.
      LargeIntegertimes10pow(int n)
      Returns the value of this large integer after multiplication by a power of ten.
      LargeIntegertimes2pow(int n)
      Returns the value of this large integer after multiplication by a power of two.
      inttoByteArray(byte[] bytes, int offset)
      Returns the two\'s-complement binary representation of this large integer.
      javolution.text.TexttoText()
      Returns the text representation of this number using the current format.
      javolution.text.TexttoText(int radix)
      Returns the text representation of this number in the specified radix.
      static LargeIntegervalueOf(BigInteger bigInteger)
      Returns the large integer corresponding to the specified java.math.BigInteger instance.
      static LargeIntegervalueOf(byte[] bytes, int offset, int length)
      Returns the large integer of specified two\'s-complement binary representation.
      static LargeIntegervalueOf(CharSequence csq)
      Returns the large integer for the specified character sequence using the current format.
      static LargeIntegervalueOf(CharSequence csq, int radix)
      Returns the large integer for the specified character sequence in the specified radix.
      static LargeIntegervalueOf(long value)
      Returns the large integer of specified long value.
    • Field Detail

      • 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 Detail

      • 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(byte[], int)
      • 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(byte[], int, int), bitLength()
      • 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 \xc2\xb7 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 \xc2\xb7 multiplier.
      • 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:
        divide(LargeInteger)
      • inverseScaled

        public LargeInteger inverseScaled(int precision)
        Returns a scaled approximation of 1 / this.
        Parameters:
        precision - the requested precision (reciprocal error being \xc2\xb1 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:
        getRemainder()
      • 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).
      • 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(int)
      • 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 \xc2\xb7 2n.
      • times10pow

        public LargeInteger times10pow(int n)
        Returns the value of this large integer after multiplication by a power of ten. For example:
             LargeInteger billion = LargeInteger.ONE.times10pow(9); // 1E9     LargeInteger million = billion.times10pow(-3);
        Parameters:
        n - the decimal exponent.
        Returns:
        this \xc2\xb7 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(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.

SCaVis 1.7 © jWork.org