Summary: Fields | Ctors | Methods | Inherited Methods | [Expand All]

public class

BigInteger

extends Number
implements Serializable Comparable <T>

java.lang.Object
↳	java.lang.Number
	↳	java.math.BigInteger

Class Overview

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.

Summary

Fields
public static final BigInteger	ONE	The `BigInteger` constant 1.
public static final BigInteger	TEN	The `BigInteger` constant 10.
public static final BigInteger	ZERO	The `BigInteger` constant 0.

Public Constructors
	BigInteger (int numBits, Random random) Constructs a random non-negative `BigInteger` instance in the range `[0, pow(2, numBits)-1]` .
	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 ( String value) Constructs a new `BigInteger` by parsing `value` .
	BigInteger ( String value, int radix) Constructs a new `BigInteger` instance by parsing `value` .
	BigInteger (int signum, byte[] magnitude) Constructs a new `BigInteger` instance with the given sign and magnitude.
	BigInteger (byte[] value) Constructs a new `BigInteger` from the given two's complement representation.

Public Methods
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` .

[Expand]

Inherited Methods

From class java.lang.Number

byte	byteValue () Returns this object's value as a byte.
abstract double	doubleValue () Returns this object's value as a double.
abstract float	floatValue () Returns this object's value as a float.
abstract int	intValue () Returns this object's value as an int.
abstract long	longValue () Returns this object's value as a long.
short	shortValue () Returns this object's value as a short.

From class java.lang.Object

Object	clone () Creates and returns a copy of this `Object` .
boolean	equals ( Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize () Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class <?>	getClass () Returns the unique instance of `Class` that represents this object's class.
int	hashCode () Returns an integer hash code for this object.
final void	notify () Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll () Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString () Returns a string containing a concise, human-readable description of this object.
final void	wait () Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait (long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait (long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

From interface java.lang.Comparable

Fields

public static final BigInteger ONE

Added in API level 1

The BigInteger constant 1.

public static final BigInteger TEN

Added in API level 1

The BigInteger constant 10.

public static final BigInteger ZERO

Added in API level 1

The BigInteger constant 0.

Public Constructors

public BigInteger (int numBits, Random random)

Added in API level 1

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.

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

Added in API level 1

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 ^certainty ) .

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` .

public BigInteger ( String value)

Added in API level 1

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` .

public BigInteger ( String value, int radix)

Added in API level 1

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` .

public BigInteger (int signum, byte[] magnitude)

Added in API level 1

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.

public BigInteger (byte[] value)

Added in API level 1

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.

Public Methods

public BigInteger abs ()

Added in API level 1

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

public BigInteger add ( BigInteger value)

Added in API level 1

Returns a BigInteger whose value is this + value .

public BigInteger and ( BigInteger value)

Added in API level 1

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` .

public BigInteger andNot ( BigInteger value)

Added in API level 1

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` .

public int bitCount ()

Added in API level 1

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.

public int bitLength ()

Added in API level 1

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.

public BigInteger clearBit (int n)

Added in API level 1

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` .

public int compareTo ( BigInteger value)

Added in API level 1

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

Parameters

value	value to be compared with `this` .

Throws

NullPointerException	if `value == null` .

public BigInteger divide ( BigInteger divisor)

Added in API level 1

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` .

public BigInteger[] divideAndRemainder ( BigInteger divisor)

Added in API level 1

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` .

public double doubleValue ()

Added in API level 1

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.

Returns

the primitive double value of this object.

public boolean equals ( Object x)

Added in API level 1

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 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.

Parameters

x	the object to compare this instance with.

Returns

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

public BigInteger flipBit (int n)

Added in API level 1

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` .

public float floatValue ()

Added in API level 1

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.

Returns

the primitive float value of this object.

public BigInteger gcd ( BigInteger value)

Added in API level 1

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` .

public int getLowestSetBit ()

Added in API level 1

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.

public int hashCode ()

Added in API level 1

Returns an integer hash code for this object. By contract, any two objects for which equals(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.

Returns

this object's hash code.

public int intValue ()

Added in API level 1

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

Returns

the primitive int value of this object.

public boolean isProbablePrime (int certainty)

Added in API level 1

Tests whether this BigInteger is probably prime. If true is returned, then this is prime with a probability greater than 1 - 1/2 ^certainty ) . 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.

public long longValue ()

Added in API level 1

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.

Returns

the primitive long value of this object.

public BigInteger max ( BigInteger value)

Added in API level 1

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`

public BigInteger min ( BigInteger value)

Added in API level 1

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` .

public BigInteger mod ( BigInteger m)

Added in API level 1

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` .

public BigInteger modInverse ( BigInteger m)

Added in API level 1

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`

public BigInteger modPow ( BigInteger exponent, BigInteger modulus)

Added in API level 1

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` .

public BigInteger multiply ( BigInteger value)

Added in API level 1

Returns a BigInteger whose value is this * value .

Throws

NullPointerException	if `value == null` .

public BigInteger negate ()

Added in API level 1

Returns a BigInteger whose value is the -this .

public BigInteger nextProbablePrime ()

Added in API level 1

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 ¹⁰⁰ .

Returns

smallest integer > this which is probably prime.

Throws

ArithmeticException	if `this < 0` .

public BigInteger not ()

Added in API level 1

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.

public BigInteger or ( BigInteger value)

Added in API level 1

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` .

public BigInteger pow (int exp)

Added in API level 1

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

Throws

ArithmeticException	if `exp < 0` .

public static BigInteger probablePrime (int bitLength, Random random)

Added in API level 1

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 ¹⁰⁰ ) .

Parameters

bitLength	length of the new `BigInteger` in bits.

Returns

probably prime random BigInteger instance.

Throws

IllegalArgumentException	if `bitLength < 2` .

public BigInteger remainder ( BigInteger divisor)

Added in API level 1

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` .

public BigInteger setBit (int n)

Added in API level 1

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` .

public BigInteger shiftLeft (int n)

Added in API level 1

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

public BigInteger shiftRight (int n)

Added in API level 1

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

public int signum ()

Added in API level 1

Returns the sign of this BigInteger .

Returns

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

public BigInteger subtract ( BigInteger value)

Added in API level 1

Returns a BigInteger whose value is this - value .

public boolean testBit (int n)

Added in API level 1

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` .

public byte[] toByteArray ()

Added in API level 1

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

public String toString ()

Added in API level 1

Returns a string representation of this BigInteger in decimal form.

Returns

a printable representation of this object.

public String toString (int radix)

Added in API level 1

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.

public static BigInteger valueOf (long value)

Added in API level 1

Returns a BigInteger whose value is equal to value .

public BigInteger xor ( BigInteger value)

Added in API level 1

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`

Results

Classes

Enums

BigInteger

Class Overview

Fast Cryptography

Slow Two's Complement Bitwise Operations

Summary

Fields

public static final BigInteger ONE

public static final BigInteger TEN

public static final BigInteger ZERO

Public Constructors

public BigInteger (int numBits, Random random)

Parameters

Throws

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

Parameters

Throws

See Also

public BigInteger ( String value)

Parameters

Throws

public BigInteger ( String value, int radix)

Parameters

Throws

public BigInteger (int signum, byte[] magnitude)

Parameters

Throws

public BigInteger (byte[] value)

Parameters

Throws

Public Methods

public BigInteger abs ()

public BigInteger add ( BigInteger value)

public BigInteger and ( BigInteger value)

Parameters

Throws

public BigInteger andNot ( BigInteger value)

Parameters

Throws

public int bitCount ()

public int bitLength ()

Returns

public BigInteger clearBit (int n)

Parameters

Throws

public int compareTo ( BigInteger value)

Parameters

Throws

public BigInteger divide ( BigInteger divisor)

Parameters

Returns

Throws

public BigInteger[] divideAndRemainder ( BigInteger divisor)

Parameters

Throws

See Also

public double doubleValue ()

Returns

public boolean equals ( Object x)

Parameters

Returns

public BigInteger flipBit (int n)

Parameters

Throws

public float floatValue ()

Returns

public BigInteger gcd ( BigInteger value)

Parameters

Throws

public int getLowestSetBit ()

public int hashCode ()

Returns

public int intValue ()

Returns

public boolean isProbablePrime (int certainty)

Parameters

Returns

public long longValue ()