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
From interface java.lang.Comparable

Constants

public static final BigInteger ONE

Since: API Level 1

The BigInteger constant 1.

public static final BigInteger TEN

Since: API Level 1

The BigInteger constant 10.

public static final BigInteger ZERO

Since: API Level 1

The BigInteger constant 0.

Public Constructors

public BigInteger (int numBits, Random rnd)

Since: API Level 1

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)

Since: API Level 1

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

public BigInteger (String val)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: 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 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 ()

Since: API Level 1

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

Returns
  • abs(this).

public BigInteger add (BigInteger val)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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 ()

Since: API Level 1

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 ()

Since: 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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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

public double doubleValue ()

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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 ()

Since: API Level 1

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)

Since: API Level 1

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 ()

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

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

public int hashCode ()

Since: API Level 1

Returns a hash code for this BigInteger.

Returns
  • hash code for this.

public int intValue ()

Since: API Level 1

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)

Since: API Level 1

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 ()

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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 ()

Since: API Level 1

Returns a new BigInteger whose value is the -this.

Returns
  • -this.

public BigInteger nextProbablePrime ()

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

Returns
  • smallest integer > this which is robably prime.
Throws
ArithmeticException if this < 0.

public BigInteger not ()

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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)

Since: API Level 1

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 ()

Since: 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 val)

Since: API Level 1

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)

Since: API Level 1

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 ()

Since: API Level 1

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

Returns
  • two's complement representation of this.

public String toString ()

Since: API Level 1

Returns a string representation of this BigInteger in decimal form.

Returns
  • a string representation of this in decimal form.

public String toString (int radix)

Since: 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.
Returns
  • a string representation of this with radix 10.

public static BigInteger valueOf (long val)

Since: API Level 1

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)

Since: API Level 1

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