LargeInteger

java.lang.Object
- java.lang.Number
- - org.jscience.mathematics.number.Number<LargeInteger>
  - - org.jscience.mathematics.number.LargeInteger

All Implemented Interfaces:

java.io.Serializable, java.lang.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(n^Log3) instead of O(n²).
Note: This class uses ConcurrentContext to accelerate calculations on multi-cores systems.
Version:

3.3, January 14, 2007

Author:

Jean-Marie Dautelle

See Also:

Wikipedia: Arbitrary-precision Arithmetic, Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static LargeInteger`	`ONE` The large integer representing the multiplicative identity.
`static <any>`	`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 LargeInteger`	`ZERO` The large integer representing the additive identity.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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(LargeInteger that)` Compares two large integers numerically.
`int`	`compareTo(long value)` Compares this large integer to the specified `long` value.
`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(java.lang.Object that)` Compares this large integer against the specified object.
`static java.lang.Appendable`	`format(LargeInteger li, int radix, java.lang.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` (`ZERO`is 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(LargeInteger that)` Returns the difference between this large integer and the one specified.
`LargeInteger`	`minus(long value)` Returns the difference between this large integer and the specified value
`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(java.lang.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(LargeInteger that)` Returns the sum of this large integer with the one specified.
`LargeInteger`	`plus(long value)` Returns the sum of this large integer with the specified `long` integer (convenience method)
`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(LargeInteger that)` Returns the product of this large integer with the one specified.
`LargeInteger`	`times(long multiplier)` Returns the product of this large integer with the specified `long` multiplier.
`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(java.math.BigInteger bigInteger)` Returns the large integer corresponding to the specified `java.math.BigInteger` instance.
`static LargeInteger`	`valueOf(byte[] bytes, int offset, int length)` Returns the large integer of specified two's-complement binary representation.
`static LargeInteger`	`valueOf(java.lang.CharSequence csq)` Returns the large integer for the specified character sequence using the current `format`.
`static LargeInteger`	`valueOf(java.lang.CharSequence csq, int radix)` Returns the large integer for the specified character sequence in the specified radix.
`static LargeInteger`	`valueOf(long value)` Returns the large integer of specified `long` value.

Methods inherited from class org.jscience.mathematics.number.Number
byteValue, floatValue, intValue, isGreaterThan, isLessThan, pow, shortValue, toString

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - PRIME_CERTAINTY
```
public static final <any> 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:
    
    java.lang.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:
    
    java.lang.IndexOutOfBoundsException - if bytes.length < (bitLength() >> 3) + 1
    
    See Also:
    
    valueOf(byte[], int, int), bitLength()
  - valueOf
```
public static LargeInteger valueOf(java.lang.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:
    
    java.lang.NumberFormatException - if error when parsing.
  - valueOf
```
public static LargeInteger valueOf(java.lang.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:
    
    java.lang.NumberFormatException - if error when parsing.
  - valueOf
```
public static LargeInteger valueOf(java.math.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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 ± 1).
    
    Returns:
    
    2^{(precision + this.bitLength())} / this
    
    Throws:
    
    java.lang.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: java.lang.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: java.lang.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: this^exp mod m Throws: java.lang.ArithmeticException - m <= 0 See Also: modInverse(org.jscience.mathematics.number.LargeInteger) 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 · 2ⁿ. 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 · 10ⁿ equals public boolean equals(java.lang.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 java.lang.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: java.lang.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(java.lang.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: java.lang.NumberFormatException - if error when parsing. format public static java.lang.Appendable format(LargeInteger li, int radix, java.lang.Appendable out) throws java.io.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: java.lang.IllegalArgumentException - if radix is not in [2 .. 36] range. java.io.IOException - if an I/O exception occurs.

Class LargeInteger

Field Summary

Method Summary

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

Methods inherited from class java.lang.Object

Field Detail

PRIME_CERTAINTY

ZERO

ONE

Method Detail

valueOf

valueOf

toByteArray

valueOf

valueOf

valueOf

isPositive

isNegative

isZero

isEven

isOdd

isProbablyPrime

bitLength

digitLength

isPowerOfTwo

getLowestSetBit

getRemainder

isLargerThan

abs

opposite

plus

plus

minus

minus

times

times

divide

divide

remainder

inverseScaled

sqrt

mod

modInverse

modPow

gcd

shiftLeft

shiftRight

times2pow

times10pow

equals

equals

hashCode

longValue

doubleValue

compareTo

compareTo

copy

toText

toText

parse

format