Summary: Constants | 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

This class represents immutable integer numbers of arbitrary length. Large numbers are typically used in security applications and therefore BigIntegers offer dedicated functionality like the generation of large prime numbers or the computation of modular inverse.

Since the class was modeled to offer all the functionality as the Integer class does, it provides even methods that operate bitwise on a two's complement representation of large integers. Note however that the implementations favors an internal representation where magnitude and sign are treated separately. Hence such operations are inefficient and should be discouraged. In simple words: Do NOT implement any bit fields based on BigInteger.

Implementation Note:
The native OpenSSL library with its BIGNUM operations covers all the meaningful functionality (everything but bit level operations).

Summary

Constants
BigInteger	ONE	The `BigInteger` constant 1.
BigInteger	TEN	The `BigInteger` constant 10.
BigInteger	ZERO	The `BigInteger` constant 0.

Public Constructors
	BigInteger(int numBits, Random rnd) Constructs a random non-negative `BigInteger` instance in the range [0, 2^(numBits)-1].
	BigInteger(int bitLength, int certainty, Random rnd) Constructs a random `BigInteger` instance in the range [0, 2^(bitLength)-1] which is probably prime.
	BigInteger(String val) Constructs a new `BigInteger` instance from the string representation.
	BigInteger(String val, int radix) Constructs a new `BigInteger` instance from the string representation.
	BigInteger(int signum, byte[] magnitude) Constructs a new `BigInteger` instance with the given sign and the given magnitude.
	BigInteger(byte[] val) Constructs a new `BigInteger` from the given two's complement representation.

Public Methods
BigInteger	abs() Returns a (new) `BigInteger` whose value is the absolute value of `this`.
BigInteger	add(BigInteger val) Returns a new `BigInteger` whose value is `this + val`.
BigInteger	and(BigInteger val) Returns a new `BigInteger` whose value is `this & val`.
BigInteger	andNot(BigInteger val) Returns a new `BigInteger` whose value is `this & ~val`.
int	bitCount() Use `bitLength(0)` if you want to know the length of the binary value in bits.
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 new `BigInteger` which has the same binary representation as `this` but with the bit at position n cleared.
int	compareTo(BigInteger val) Compares this `BigInteger` with `val`.
BigInteger	divide(BigInteger divisor) Returns a new `BigInteger` whose value is `this / divisor`.
BigInteger[]	divideAndRemainder(BigInteger divisor) Returns a `BigInteger` array which contains `this / divisor` at index 0 and `this % divisor` at index 1.
double	doubleValue() Returns this `BigInteger` as an double value.
boolean	equals(Object x) Returns `true` if `x` is a BigInteger instance and if this instance is equal to this `BigInteger`.
BigInteger	flipBit(int n) Returns a new `BigInteger` which has the same binary representation as `this` but with the bit at position n flipped.
float	floatValue() Returns this `BigInteger` as an float value.
BigInteger	gcd(BigInteger val) Returns a new `BigInteger` whose value is greatest common divisor of `this` and `val`.
int	getLowestSetBit() Returns the position of the lowest set bit in the two's complement representation of this `BigInteger`.
int	hashCode() Returns a hash code for this `BigInteger`.
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 an long value.
BigInteger	max(BigInteger val) Returns the maximum of this `BigInteger` and `val`.
BigInteger	min(BigInteger val) Returns the minimum of this `BigInteger` and `val`.
BigInteger	mod(BigInteger m) Returns a new `BigInteger` whose value is `this mod m`.
BigInteger	modInverse(BigInteger m) Returns a new `BigInteger` whose value is `1/this mod m`.
BigInteger	modPow(BigInteger exponent, BigInteger m) Returns a new `BigInteger` whose value is `this^exponent mod m`.
BigInteger	multiply(BigInteger val) Returns a new `BigInteger` whose value is `this * val`.
BigInteger	negate() Returns a new `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 new `BigInteger` whose value is `~this`.
BigInteger	or(BigInteger val) Returns a new `BigInteger` whose value is `this \| val`.
BigInteger	pow(int exp) Returns a new `BigInteger` whose value is `this ^ exp`.
static BigInteger	probablePrime(int bitLength, Random rnd) Returns a random positive `BigInteger` instance in the range [0, 2^(bitLength)-1] which is probably prime.
BigInteger	remainder(BigInteger divisor) Returns a new `BigInteger` whose value is `this % divisor`.
BigInteger	setBit(int n) Returns a new `BigInteger` which has the same binary representation as `this` but with the bit at position n set.
BigInteger	shiftLeft(int n) Returns a new `BigInteger` whose value is `this << n`.
BigInteger	shiftRight(int n) Returns a new `BigInteger` whose value is `this >> n`.
int	signum() Returns the sign of this `BigInteger`.
BigInteger	subtract(BigInteger val) Returns a new `BigInteger` whose value is `this - val`.
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 val) Creates a new `BigInteger` whose value is equal to the specified `long` argument.
BigInteger	xor(BigInteger val) Returns a new `BigInteger` whose value is `this ^ val`.

[Expand]

Inherited Methods

From class java.lang.Number

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() Is called before the object's memory is being reclaimed by the VM.
final Class<? extends Object>	getClass() Returns the unique instance of Class which 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(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.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.

From interface java.lang.Comparable

Constants

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

public BigInteger (int numBits, Random rnd)

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

Parameters

numBits	maximum length of the new `BigInteger` in bits.
rnd	is an optional random generator to be used.

Throws

IllegalArgumentException	if `numBits` < 0.

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

Constructs a random BigInteger instance in the range [0, 2^(bitLength)-1] which is probably prime. The probability that the returned BigInteger is prime is beyond (1-1/2^certainty).

Implementation Note: Currently rnd is ignored. The implementation always uses method bn_rand from the OpenSSL library. bn_rand generates cryptographically strong pseudo-random numbers.

Parameters

bitLength	length of the new `BigInteger` in bits.
certainty	tolerated primality uncertainty.
rnd	is an optional random generator to be used.

Throws

ArithmeticException	if `bitLength` < 2.

public BigInteger (String val)

Constructs a new BigInteger instance from the string representation. The string representation consists of an optional minus sign followed by a non-empty sequence of decimal digits.

Parameters

val	string representation of the new `BigInteger`.

Throws

NullPointerException	if `val == null`.
NumberFormatException	if `val` is not a valid representation of a `BigInteger`.

public BigInteger (String val, int radix)

Constructs a new BigInteger instance from the string representation. The string representation consists of an optional minus sign followed by a non-empty sequence of digits in the specified radix. For the conversion the method Character.digit(char, radix) is used.

Parameters

val	string representation of the new `BigInteger`.
radix	the base to be used for the conversion.

Throws

NullPointerException	if `val == null`.
NumberFormatException	if `val` 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)

Constructs a new BigInteger instance with the given sign and the given magnitude. The sign is given as an integer (-1 for negative, 0 for zero, 1 for positive). The magnitude is specified as a byte array. The most significant byte is the entry at index 0.

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[] val)

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 given array must not be empty.

Parameters

val	two's complement representation of the new `BigInteger`.

Throws

NullPointerException	if `val == null`.
NumberFormatException	if the length of `val` is zero.

Public Methods

public BigInteger abs ()

Returns a (new) BigInteger whose value is the absolute value of this.

Returns

abs(this).

public BigInteger add (BigInteger val)

Returns a new BigInteger whose value is this + val.

Parameters

val	value to be added to `this`.

Returns

this + val.

Throws

NullPointerException	if `val == null`.

public BigInteger and (BigInteger val)

Returns a new BigInteger whose value is this & val.

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

Parameters

val	value to be and'ed with `this`.

Returns

this & val.

Throws

NullPointerException	if `val == null`.

public BigInteger andNot (BigInteger val)

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

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

Parameters

val	value to be not'ed and then and'ed with `this`.

Returns

this & ~val.

Throws

NullPointerException	if `val == null`.

public int bitCount ()

Use bitLength(0) if you want to know the length of the binary value in bits.

Returns the number of bits in the binary representation of this which differ from the sign bit. If this is positive the result is equivalent to the number of bits set in the binary representation of this. If this is negative the result is equivalent to the number of bits set in the binary representation of -this-1.

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

Returns

number of bits in the binary representation of this which differ from the sign bit

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.

public BigInteger clearBit (int n)

Returns a new BigInteger which has the same binary representation as this but with the bit at position n cleared. The result is equivalent to this & ~(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.

Returns

this & ~(2^n).

Throws

ArithmeticException	if `n < 0`.

public int compareTo (BigInteger val)

Compares this BigInteger with val. Returns one of the three values 1, 0, or -1.

Parameters

val	value to be compared with `this`.

Returns

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

Throws

NullPointerException	if `val == null`.

public BigInteger divide (BigInteger divisor)

Returns a new 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)

Returns a BigInteger array which contains this / divisor at index 0 and this % divisor at index 1.

Parameters

divisor	value by which `this` is divided.

Returns

[this / divisor, this % divisor].

Throws

NullPointerException	if `divisor == null`.
ArithmeticException	if `divisor == 0`.

public double doubleValue ()

Returns this BigInteger as an double value. If this is too big to be represented as an double, then Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY is returned. Note, that not all integers x in the range [-Double.MAX_VALUE, Double.MAX_VALUE] can be represented as a double. The double representation has a mantissa of length 53. For example, 2^53+1 = 9007199254740993 is returned as double 9007199254740992.0.

Returns

this BigInteger as a double value

public boolean equals (Object x)

Returns true if x is a BigInteger instance and if this instance is equal to this BigInteger.

Parameters

x	object to be compared with `this`.

Returns

true if x is a BigInteger and this == x, false otherwise.

public BigInteger flipBit (int n)

Returns a new BigInteger which has the same binary representation as this but with the bit at position n flipped. The result is equivalent to this ^ 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.

Returns

this ^ 2^n.

Throws

ArithmeticException	if `n < 0`.

public float floatValue ()

Returns this BigInteger as an float value. If this is too big to be represented as an float, then Float.POSITIVE_INFINITY or Float.NEGATIVE_INFINITY is returned. Note, that not all integers x in the range [-Float.MAX_VALUE, Float.MAX_VALUE] can be represented as a float. The float representation has a mantissa of length 24. For example, 2^24+1 = 16777217 is returned as float 16777216.0.

Returns

this BigInteger as a float value.

public BigInteger gcd (BigInteger val)

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

Parameters

val	value with which the greatest common divisor is computed.

Returns

gcd(this, val).

Throws

NullPointerException	if `val == null`.

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.

Returns

position of lowest bit if this != 0, -1 otherwise

public int hashCode ()

Returns a hash code for this BigInteger.

Returns

hash code for this.

public int intValue ()

Returns this BigInteger as an int value. If this is too big to be represented as an int, then this % 2^32 is returned.

Returns

this BigInteger as an int value.

public boolean isProbablePrime (int certainty)

Tests whether this BigInteger is probably prime. If true is returned, then this is prime with a probability beyond (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 ()

Returns this BigInteger as an long value. If this is too big to be represented as an long, then this % 2^64 is returned.

Returns

this BigInteger as a long value.

public BigInteger max (BigInteger val)

Returns the maximum of this BigInteger and val.

Parameters

val	value to be used to compute the maximum with `this`

Returns

max(this, val)

Throws

NullPointerException	if `val == null`

public BigInteger min (BigInteger val)

Returns the minimum of this BigInteger and val.

Parameters

val	value to be used to compute the minimum with `this`.

Returns

min(this, val).

Throws

NullPointerException	if `val == null`.

public BigInteger mod (BigInteger m)

Returns a new 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)

Returns a new 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.

Returns

1/this mod m.

Throws

NullPointerException	if `m == null`
ArithmeticException	if `m < 0 or` if `this` is not relatively prime to `m`

public BigInteger modPow (BigInteger exponent, BigInteger m)

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

Parameters

exponent	the exponent.
m	the modulus.

Returns

this^exponent mod val.

Throws

NullPointerException	if `m == null` or `exponent == null`.
ArithmeticException	if `m < 0` or if `exponent<0` and this is not relatively prime to `m`.

public BigInteger multiply (BigInteger val)

Returns a new BigInteger whose value is this * val.

Parameters

val	value to be multiplied with `this`.

Returns

this * val.

Throws

NullPointerException	if `val == null`.

public BigInteger negate ()

Returns a new BigInteger whose value is the -this.

Returns

-this.

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 beyond (1-1/2^80).

Returns

smallest integer > this which is robably prime.

Throws

ArithmeticException	if `this < 0`.

public BigInteger not ()

Returns a new 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.

Returns

~this.

public BigInteger or (BigInteger val)

Returns a new BigInteger whose value is this | val.

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

Parameters

val	value to be or'ed with `this`.

Returns

this | val.

Throws

NullPointerException	if `val == null`.

public BigInteger pow (int exp)

Returns a new BigInteger whose value is this ^ exp.

Parameters

exp	exponent to which `this` is raised.

Returns

this ^ exp.

Throws

ArithmeticException	if `exp < 0`.

public static BigInteger probablePrime (int bitLength, Random rnd)

Returns a random positive BigInteger instance in the range [0, 2^(bitLength)-1] which is probably prime. The probability that the returned BigInteger is prime is beyond (1-1/2^80).

Implementation Note: Currently rnd is ignored.

Parameters

bitLength	length of the new `BigInteger` in bits.
rnd	random generator used to generate the new `BigInteger`.

Returns

probably prime random BigInteger instance.

Throws

IllegalArgumentException	if `bitLength < 2`.

public BigInteger remainder (BigInteger divisor)

Returns a new BigInteger whose value is this % divisor. Regarding signs this methods has the same behavior as the % operator on int's, i.e. the sign of the remainder is the same as the sign of this.

Parameters

divisor	value by which `this` is divided.

Returns

this % divisor.

Throws

NullPointerException	if `divisor == null`.
ArithmeticException	if `divisor == 0`.

public BigInteger setBit (int n)

Returns a new BigInteger which has the same binary representation as this but with the bit at position n set. The result is equivalent to this | 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.

Returns

this | 2^n.

Throws

ArithmeticException	if `n < 0`.

public BigInteger shiftLeft (int n)

Returns a new BigInteger whose value is this << n. The result is equivalent to this * 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 / 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)

Returns a new 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 ()

Returns the sign of this BigInteger.

Returns

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

public BigInteger subtract (BigInteger val)

Returns a new BigInteger whose value is this - val.

Parameters

val	value to be subtracted from `this`.

Returns

this - val.

Throws

NullPointerException	if `val == null`.

public boolean testBit (int n)

Tests whether the bit at position n in this is set. The result is equivalent to this & (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.

Returns

this & (2^n) != 0.

Throws

ArithmeticException	if `n < 0`.

public byte[] toByteArray ()

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

Returns

two's complement representation of this.

public String toString ()

Returns a string representation of this BigInteger in decimal form.

Returns

a string representation of this in decimal form.

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.

Returns

a string representation of this with radix 10.

public static BigInteger valueOf (long val)

Creates a new BigInteger whose value is equal to the specified long argument.

Parameters

val	the value of the new `BigInteger`.

Returns

BigInteger instance with the value val.

public BigInteger xor (BigInteger val)

Returns a new BigInteger whose value is this ^ val.

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

Parameters

val	value to be xor'ed with `this`

Returns

this ^ val

Throws

NullPointerException	if `val == null`

Classes

Enums

BigInteger

Class Overview

Summary

Constants

public static final BigInteger ONE

public static final BigInteger TEN

public static final BigInteger ZERO

Public Constructors

public BigInteger (int numBits, Random rnd)

Parameters

Throws

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

Parameters

Throws

See Also

public BigInteger (String val)

Parameters

Throws

public BigInteger (String val, int radix)

Parameters

Throws

public BigInteger (int signum, byte[] magnitude)

Parameters

Throws

public BigInteger (byte[] val)

Parameters

Throws

Public Methods

public BigInteger abs ()

Returns

public BigInteger add (BigInteger val)

Parameters

Returns

Throws

public BigInteger and (BigInteger val)

Parameters

Returns

Throws

public BigInteger andNot (BigInteger val)

Parameters

Returns

Throws

public int bitCount ()

Returns

public int bitLength ()

Returns

public BigInteger clearBit (int n)

Parameters

Returns

Throws

public int compareTo (BigInteger val)

Parameters

Returns

Throws

public BigInteger divide (BigInteger divisor)

Parameters

Returns

Throws

public BigInteger[] divideAndRemainder (BigInteger divisor)

Parameters

Returns

Throws

See Also

public double doubleValue ()

Returns

public boolean equals (Object x)

Parameters

Returns

public BigInteger flipBit (int n)

Parameters

Returns

Throws

public float floatValue ()

Returns

public BigInteger gcd (BigInteger val)

Parameters

Returns

Throws