JScience v4.3

org.jscience.mathematics.number
Class LargeInteger

java.lang.Object
  extended by java.lang.Number
      extended by org.jscience.mathematics.number.Number<LargeInteger>
          extended by 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:

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
static LargeInteger ONE
          The large integer representing the multiplicative identity.
static javolution.lang.Configurable<java.lang.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 LargeInteger ZERO
          The large integer representing the additive identity.
 
Method Summary
 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 (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(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
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

PRIME_CERTAINTY

public static final javolution.lang.Configurable<java.lang.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:
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:
thisexp 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 · 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 · 10n

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.

JScience v4.3

Copyright © 2006 JScience.