Package java.math

Class BigInteger

java.lang.Object

java.lang.Number

java.math.BigInteger

All Implemented Interfaces:

Serializable, Comparable<BigInteger>

public class BigInteger
extends Number
implements Comparable<BigInteger>, Serializable

An immutable arbitrary-precision signed integer.

Fast Cryptography

This implementation is efficient for operations traditionally used in cryptography, such as the generation of large prime numbers and computation of the modular inverse.

Slow Two's Complement Bitwise Operations

This API includes operations for bitwise operations in two's complement representation. Two's complement is not the internal representation used by this implementation, so such methods may be inefficient. Use BitSet for high-performance bitwise operations on arbitrarily-large sequences of bits.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static BigInteger	ONE	The BigInteger constant 1.
static BigInteger	TEN	The BigInteger constant 10.
static BigInteger	ZERO	The BigInteger constant 0.

Constructor Summary

Constructors

Constructor	Description
BigInteger(byte[] value)	Constructs a new BigInteger from the given two's complement representation.
BigInteger(int signum, byte[] magnitude)	Constructs a new BigInteger instance with the given sign and magnitude.
BigInteger(int bitLength, int certainty, Random random)	Constructs a random BigInteger instance in the range [0, pow(2, bitLength)-1] which is probably prime.
BigInteger(int numBits, Random random)	Constructs a random non-negative BigInteger instance in the range [0, pow(2, numBits)-1].
BigInteger(String value)	Constructs a new BigInteger by parsing value.
BigInteger(String value, int radix)	Constructs a new BigInteger instance by parsing value.

Method Summary

Modifier and Type	Method	Description
BigInteger	abs()	Returns a BigInteger whose value is the absolute value of this.
BigInteger	add(BigInteger value)	Returns a BigInteger whose value is this + value.
BigInteger	and(BigInteger value)	Returns a BigInteger whose value is this & value.
BigInteger	andNot(BigInteger value)	Returns a BigInteger whose value is this & ~value.
int	bitCount()	Returns the number of bits in the two's complement representation of this which differ from the sign bit.
int	bitLength()	Returns the length of the value's two's complement representation without leading zeros for positive numbers / without leading ones for negative values.
BigInteger	clearBit(int n)	Returns a BigInteger which has the same binary representation as this but with the bit at position n cleared.
int	compareTo(BigInteger value)	Compares this BigInteger with value.
BigInteger	divide(BigInteger divisor)	Returns a BigInteger whose value is this / divisor.
BigInteger[]	divideAndRemainder(BigInteger divisor)	Returns a two element BigInteger array containing this / divisor at index 0 and this % divisor at index 1.
double	doubleValue()	Returns this BigInteger as a double.
boolean	equals(Object x)	Compares this instance with the specified object and indicates if they are equal.
BigInteger	flipBit(int n)	Returns a BigInteger which has the same binary representation as this but with the bit at position n flipped.
float	floatValue()	Returns this BigInteger as a float.
BigInteger	gcd(BigInteger value)	Returns a BigInteger whose value is greatest common divisor of this and value.
int	getLowestSetBit()	Returns the position of the lowest set bit in the two's complement representation of this BigInteger.
int	hashCode()	Returns an integer hash code for this object.
int	intValue()	Returns this BigInteger as an int value.
boolean	isProbablePrime(int certainty)	Tests whether this BigInteger is probably prime.
long	longValue()	Returns this BigInteger as a long value.
BigInteger	max(BigInteger value)	Returns the maximum of this BigInteger and value.
BigInteger	min(BigInteger value)	Returns the minimum of this BigInteger and value.
BigInteger	mod(BigInteger m)	Returns a BigInteger whose value is this mod m.
BigInteger	modInverse(BigInteger m)	Returns a BigInteger whose value is 1/this mod m.
BigInteger	modPow(BigInteger exponent, BigInteger modulus)	Returns a BigInteger whose value is pow(this, exponent) mod modulus.
BigInteger	multiply(BigInteger value)	Returns a BigInteger whose value is this * value.
BigInteger	negate()	Returns a BigInteger whose value is the -this.
BigInteger	nextProbablePrime()	Returns the smallest integer x > this which is probably prime as a BigInteger instance.
BigInteger	not()	Returns a BigInteger whose value is ~this.
BigInteger	or(BigInteger value)	Returns a BigInteger whose value is this | value.
BigInteger	pow(int exp)	Returns a BigInteger whose value is pow(this, exp).
static BigInteger	probablePrime(int bitLength, Random random)	Returns a random positive BigInteger instance in the range [0, pow(2, bitLength)-1] which is probably prime.
BigInteger	remainder(BigInteger divisor)	Returns a BigInteger whose value is this % divisor.
BigInteger	setBit(int n)	Returns a BigInteger which has the same binary representation as this but with the bit at position n set.
BigInteger	shiftLeft(int n)	Returns a BigInteger whose value is this << n.
BigInteger	shiftRight(int n)	Returns a BigInteger whose value is this >> n.
int	signum()	Returns the sign of this BigInteger.
BigInteger	subtract(BigInteger value)	Returns a BigInteger whose value is this - value.
boolean	testBit(int n)	Tests whether the bit at position n in this is set.
byte[]	toByteArray()	Returns the two's complement representation of this BigInteger in a byte array.
String	toString()	Returns a string representation of this BigInteger in decimal form.
String	toString(int radix)	Returns a string containing a string representation of this BigInteger with base radix.
static BigInteger	valueOf(long value)	Returns a BigInteger whose value is equal to value.
BigInteger	xor(BigInteger value)	Returns a BigInteger whose value is this ^ value.

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

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

Field Details

ZERO

public static final BigInteger ZERO

The BigInteger constant 0.

ONE

public static final BigInteger ONE

The BigInteger constant 1.

TEN

public static final BigInteger TEN

The BigInteger constant 10.

Constructor Details

BigInteger

public BigInteger(int numBits,
Random random)

Constructs a random non-negative BigInteger instance in the range [0, pow(2, numBits)-1].

Parameters:

numBits - maximum length of the new BigInteger in bits.

random - is the random number generator to be used.

Throws:

IllegalArgumentException - if numBits < 0.

BigInteger

public BigInteger(int bitLength,
int certainty,
Random random)

Constructs a random BigInteger instance in the range [0, pow(2, bitLength)-1] which is probably prime. The probability that the returned BigInteger is prime is greater than 1 - 1/2<sup>certainty</sup>).

Note: the Random argument is ignored if bitLength >= 16, where this implementation will use OpenSSL's BN_generate_prime_ex as a source of cryptographically strong pseudo-random numbers.

Parameters:

bitLength - length of the new BigInteger in bits.

certainty - tolerated primality uncertainty.

Throws:

ArithmeticException - if bitLength < 2.

See Also:

Specification of random generator used from OpenSSL library

BigInteger

public BigInteger(String value)

Constructs a new BigInteger by parsing value. The string representation consists of an optional plus or minus sign followed by a non-empty sequence of decimal digits. Digits are interpreted as if by Character.digit(char,10).

Parameters:

value - string representation of the new BigInteger.

Throws:

NullPointerException - if value == null.

NumberFormatException - if value is not a valid representation of a BigInteger.

BigInteger

public BigInteger(String value,
int radix)

Constructs a new BigInteger instance by parsing value. The string representation consists of an optional plus or minus sign followed by a non-empty sequence of digits in the specified radix. Digits are interpreted as if by Character.digit(char, radix).

Parameters:

value - string representation of the new BigInteger.

radix - the base to be used for the conversion.

Throws:

NullPointerException - if value == null.

NumberFormatException - if value is not a valid representation of a BigInteger or if radix < Character.MIN_RADIX or radix > Character.MAX_RADIX.

BigInteger

public BigInteger(int signum,
byte[] magnitude)

Constructs a new BigInteger instance with the given sign and magnitude.

Parameters:

signum - sign of the new BigInteger (-1 for negative, 0 for zero, 1 for positive).

magnitude - magnitude of the new BigInteger with the most significant byte first.

Throws:

NullPointerException - if magnitude == null.

NumberFormatException - if the sign is not one of -1, 0, 1 or if the sign is zero and the magnitude contains non-zero entries.

BigInteger

public BigInteger(byte[] value)

Constructs a new BigInteger from the given two's complement representation. The most significant byte is the entry at index 0. The most significant bit of this entry determines the sign of the new BigInteger instance. The array must be nonempty.

Parameters:

value - two's complement representation of the new BigInteger.

Throws:

NullPointerException - if value == null.

NumberFormatException - if the length of value is zero.

Method Details

valueOf

public static BigInteger valueOf(long value)

Returns a BigInteger whose value is equal to value.

toByteArray

public byte[] toByteArray()

Returns the two's complement representation of this BigInteger in a byte array.

abs

public BigInteger abs()

Returns a BigInteger whose value is the absolute value of this.

negate

public BigInteger negate()

Returns a BigInteger whose value is the -this.

add

public BigInteger add(BigInteger value)

Returns a BigInteger whose value is this + value.

subtract

public BigInteger subtract(BigInteger value)

Returns a BigInteger whose value is this - value.

signum

public int signum()

Returns the sign of this BigInteger.

Returns:

-1 if this < 0, 0 if this == 0, 1 if this > 0.

shiftRight

public BigInteger shiftRight(int n)

Returns a BigInteger whose value is this >> n. For negative arguments, the result is also negative. The shift distance may be negative which means that this is shifted left.

Implementation Note: Usage of this method on negative values is not recommended as the current implementation is not efficient.

Parameters:

n - shift distance

Returns:

this >> n if n >= 0; this << (-n) otherwise

shiftLeft

public BigInteger shiftLeft(int n)

Returns a BigInteger whose value is this << n. The result is equivalent to this * pow(2, n) if n >= 0. The shift distance may be negative which means that this is shifted right. The result then corresponds to floor(this / pow(2, -n)).

Implementation Note: Usage of this method on negative values is not recommended as the current implementation is not efficient.

Parameters:

n - shift distance.

Returns:

this << n if n >= 0; this >> (-n). otherwise

bitLength

public int bitLength()

Returns the length of the value's two's complement representation without leading zeros for positive numbers / without leading ones for negative values.

The two's complement representation of this will be at least bitLength() + 1 bits long.

The value will fit into an int if bitLength() < 32 or into a long if bitLength() < 64.

Returns:

the length of the minimal two's complement representation for this without the sign bit.

testBit

public boolean testBit(int n)

Tests whether the bit at position n in this is set. The result is equivalent to this & pow(2, n) != 0.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters:

n - position where the bit in this has to be inspected.

Throws:

ArithmeticException - if n < 0.

setBit

public BigInteger setBit(int n)

Returns a BigInteger which has the same binary representation as this but with the bit at position n set. The result is equivalent to this | pow(2, n).

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters:

n - position where the bit in this has to be set.

Throws:

ArithmeticException - if n < 0.

clearBit

public BigInteger clearBit(int n)

Returns a BigInteger which has the same binary representation as this but with the bit at position n cleared. The result is equivalent to this & ~pow(2, n).

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters:

n - position where the bit in this has to be cleared.

Throws:

ArithmeticException - if n < 0.

flipBit

public BigInteger flipBit(int n)

Returns a BigInteger which has the same binary representation as this but with the bit at position n flipped. The result is equivalent to this ^ pow(2, n).

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters:

n - position where the bit in this has to be flipped.

Throws:

ArithmeticException - if n < 0.

getLowestSetBit

public int getLowestSetBit()

Returns the position of the lowest set bit in the two's complement representation of this BigInteger. If all bits are zero (this==0) then -1 is returned as result.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

bitCount

public int bitCount()

Returns the number of bits in the two's complement representation of this which differ from the sign bit. If this is negative, the result is equivalent to the number of bits set in the two's complement representation of -this - 1.

Use bitLength(0) to find the length of the binary value in bits.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

not

public BigInteger not()

Returns a BigInteger whose value is ~this. The result of this operation is -this-1.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

and

public BigInteger and(BigInteger value)

Returns a BigInteger whose value is this & value.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters:

value - value to be and'ed with this.

Throws:

NullPointerException - if value == null.

or

public BigInteger or(BigInteger value)

Returns a BigInteger whose value is this | value.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters:

value - value to be or'ed with this.

Throws:

NullPointerException - if value == null.

xor

public BigInteger xor(BigInteger value)

Returns a BigInteger whose value is this ^ value.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters:

value - value to be xor'ed with this

Throws:

NullPointerException - if value == null

andNot

public BigInteger andNot(BigInteger value)

Returns a BigInteger whose value is this & ~value. Evaluating x.andNot(value) returns the same result as x.and(value.not()).

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters:

value - value to be not'ed and then and'ed with this.

Throws:

NullPointerException - if value == null.

intValue

public int intValue()

Returns this BigInteger as an int value. If this is too big to be represented as an int, then this % (1 << 32) is returned.

Specified by:

intValue in class Number

Returns:

the primitive int value of this object.

longValue

public long longValue()

Returns this BigInteger as a long value. If this is too big to be represented as a long, then this % pow(2, 64) is returned.

Specified by:

longValue in class Number

Returns:

the primitive long value of this object.

floatValue

public float floatValue()

Returns this BigInteger as a float. If this is too big to be represented as a float, then Float.POSITIVE_INFINITY or Float.NEGATIVE_INFINITY is returned. Note that not all integers in the range [-Float.MAX_VALUE, Float.MAX_VALUE] can be exactly represented as a float.

Specified by:

floatValue in class Number

Returns:

the primitive float value of this object.

doubleValue

public double doubleValue()

Returns this BigInteger as a double. If this is too big to be represented as a double, then Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY is returned. Note that not all integers in the range [-Double.MAX_VALUE, Double.MAX_VALUE] can be exactly represented as a double.

Specified by:

doubleValue in class Number

Returns:

the primitive double value of this object.

compareTo

public int compareTo(BigInteger value)

Compares this BigInteger with value. Returns -1 if this < value, 0 if this == value and 1 if this > value, .

Specified by:

compareTo in interface Comparable<BigInteger>

Parameters:

value - value to be compared with this.

Returns:

a negative integer if this instance is less than another; a positive integer if this instance is greater than another; 0 if this instance has the same order as another.

Throws:

NullPointerException - if value == null.

min

public BigInteger min(BigInteger value)

Returns the minimum of this BigInteger and value.

Parameters:

value - value to be used to compute the minimum with this.

Throws:

NullPointerException - if value == null.

max

public BigInteger max(BigInteger value)

Returns the maximum of this BigInteger and value.

Parameters:

value - value to be used to compute the maximum with this

Throws:

NullPointerException - if value == null

hashCode

public int hashCode()

Description copied from class: Object

Returns an integer hash code for this object. By contract, any two objects for which Object.equals(java.lang.Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Note that hash values must not change over time unless information used in equals comparisons also changes.

See Writing a correct hashCode method if you intend implementing your own hashCode method.

Overrides:

hashCode in class Object

Returns:

this object's hash code.

See Also:

Object.equals(java.lang.Object)

equals

public boolean equals(Object x)

Description copied from class: Object

Compares this instance with the specified object and indicates if they are equal. In order to be equal, o must represent the same object as this instance using a class-specific comparison. The general contract is that this comparison should be reflexive, symmetric, and transitive. Also, no object reference other than null is equal to null.

The default implementation returns true only if this == o. See Writing a correct equals method if you intend implementing your own equals method.

The general contract for the equals and Object.hashCode() methods is that if equals returns true for any two objects, then hashCode() must return the same value for these objects. This means that subclasses of Object usually override either both methods or neither of them.

Overrides:

equals in class Object

Parameters:

x - the object to compare this instance with.

Returns:

true if the specified object is equal to this Object; false otherwise.

See Also:

Object.hashCode()

toString

public String toString()

Returns a string representation of this BigInteger in decimal form.

Overrides:

toString in class Object

Returns:

a printable representation of this object.

toString

public String toString(int radix)

Returns a string containing a string representation of this BigInteger with base radix. If radix < Character.MIN_RADIX or radix > Character.MAX_RADIX then a decimal representation is returned. The characters of the string representation are generated with method Character.forDigit.

Parameters:

radix - base to be used for the string representation.

gcd

public BigInteger gcd(BigInteger value)

Returns a BigInteger whose value is greatest common divisor of this and value. If this == 0 and value == 0 then zero is returned, otherwise the result is positive.

Parameters:

value - value with which the greatest common divisor is computed.

Throws:

NullPointerException - if value == null.

multiply

public BigInteger multiply(BigInteger value)

Returns a BigInteger whose value is this * value.

Throws:

NullPointerException - if value == null.

pow

public BigInteger pow(int exp)

Returns a BigInteger whose value is pow(this, exp).

Throws:

ArithmeticException - if exp < 0.

divideAndRemainder

public BigInteger[] divideAndRemainder(BigInteger divisor)

Returns a two element BigInteger array containing this / divisor at index 0 and this % divisor at index 1.

Parameters:

divisor - value by which this is divided.

Throws:

NullPointerException - if divisor == null.

ArithmeticException - if divisor == 0.

See Also:

divide(java.math.BigInteger), remainder(java.math.BigInteger)

divide

public BigInteger divide(BigInteger divisor)

Returns a BigInteger whose value is this / divisor.

Parameters:

divisor - value by which this is divided.

Returns:

this / divisor.

Throws:

NullPointerException - if divisor == null.

ArithmeticException - if divisor == 0.

remainder

public BigInteger remainder(BigInteger divisor)

Returns a BigInteger whose value is this % divisor. Regarding signs this methods has the same behavior as the % operator on ints: the sign of the remainder is the same as the sign of this.

Parameters:

divisor - value by which this is divided.

Throws:

NullPointerException - if divisor == null.

ArithmeticException - if divisor == 0.

modInverse

public BigInteger modInverse(BigInteger m)

Returns a BigInteger whose value is 1/this mod m. The modulus m must be positive. The result is guaranteed to be in the interval [0, m) (0 inclusive, m exclusive). If this is not relatively prime to m, then an exception is thrown.

Parameters:

m - the modulus.

Throws:

NullPointerException - if m == null

ArithmeticException - if m < 0 or if this is not relatively prime to m

modPow

public BigInteger modPow(BigInteger exponent,
BigInteger modulus)

Returns a BigInteger whose value is pow(this, exponent) mod modulus. The modulus must be positive. The result is guaranteed to be in the interval [0, modulus). If the exponent is negative, then pow(this.modInverse(modulus), -exponent) mod modulus is computed. The inverse of this only exists if this is relatively prime to the modulus, otherwise an exception is thrown.

Throws:

NullPointerException - if modulus == null or exponent == null.

ArithmeticException - if modulus < 0 or if exponent < 0 and not relatively prime to modulus.

mod

public BigInteger mod(BigInteger m)

Returns a BigInteger whose value is this mod m. The modulus m must be positive. The result is guaranteed to be in the interval [0, m) (0 inclusive, m exclusive). The behavior of this function is not equivalent to the behavior of the % operator defined for the built-in int's.

Parameters:

m - the modulus.

Returns:

this mod m.

Throws:

NullPointerException - if m == null.

ArithmeticException - if m < 0.

isProbablePrime

public boolean isProbablePrime(int certainty)

Tests whether this BigInteger is probably prime. If true is returned, then this is prime with a probability greater than 1 - 1/2<sup>certainty</sup>). If false is returned, then this is definitely composite. If the argument certainty <= 0, then this method returns true.

Parameters:

certainty - tolerated primality uncertainty.

Returns:

true, if this is probably prime, false otherwise.

nextProbablePrime

public BigInteger nextProbablePrime()

Returns the smallest integer x > this which is probably prime as a BigInteger instance. The probability that the returned BigInteger is prime is greater than 1 - 1/2<sup>100</sup>.

Returns:

smallest integer > this which is probably prime.

Throws:

ArithmeticException - if this < 0.

probablePrime

public static BigInteger probablePrime(int bitLength,
Random random)

Returns a random positive BigInteger instance in the range [0, pow(2, bitLength)-1] which is probably prime. The probability that the returned BigInteger is prime is greater than 1 - 1/2<sup>100</sup>).

Parameters:

bitLength - length of the new BigInteger in bits.

Returns:

probably prime random BigInteger instance.

Throws:

IllegalArgumentException - if bitLength < 2.