public class

BigInteger

extends Number
implements Serializable Comparable<T>
java.lang.Object
   ↳ java.lang.Number
     ↳ java.math.BigInteger

Class Overview

An immutable signed integer of arbitrary magnitude.

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

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 random)
Constructs a random non-negative BigInteger instance in the range [0, pow(2, numBits)-1].
BigInteger(int bitLength, int certainty, Random unused)
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 m)
Returns a BigInteger whose value is pow(this, exponent) mod m.
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 unused)
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
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 random)

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

Since: 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 beyond 1 - 1/pow(2, certainty).

Implementation Note: the Random argument is ignored. This implementation uses OpenSSL's bn_rand 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

public BigInteger (String value)

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

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

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

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

Since: API Level 1

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

public BigInteger add (BigInteger value)

Since: API Level 1

Returns a BigInteger whose value is this + value.

public BigInteger and (BigInteger value)

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

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

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

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

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

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

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

public double doubleValue ()

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

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

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

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

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

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.

public int hashCode ()

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

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

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

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

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

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

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

Since: API Level 1

Returns a BigInteger whose value is pow(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 pow(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.
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 value)

Since: API Level 1

Returns a BigInteger whose value is this * value.

Throws
NullPointerException if value == null.

public BigInteger negate ()

Since: API Level 1

Returns a BigInteger whose value is the -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/pow(2, 80).

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

public BigInteger not ()

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

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

Since: API Level 1

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

Throws
ArithmeticException if exp < 0.

public static BigInteger probablePrime (int bitLength, Random unused)

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

Implementation Note: Currently random is ignored.

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)

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

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

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

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

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

Since: API Level 1

Returns a BigInteger whose value is this - value.

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

Since: API Level 1

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

public String toString ()

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

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.

public static BigInteger valueOf (long value)

Since: API Level 1

Returns a BigInteger whose value is equal to value.

public BigInteger xor (BigInteger value)

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