Skip to content

Most visited

Recently visited

navigation
Added in API level 1

BigInteger

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

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


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.

Inherited methods

From class java.lang.Number
From class java.lang.Object
From interface java.lang.Comparable

Fields

ONE

Added in API level 1
BigInteger ONE

The BigInteger constant 1.

TEN

Added in API level 1
BigInteger TEN

The BigInteger constant 10.

ZERO

Added in API level 1
BigInteger ZERO

The BigInteger constant 0.

Public constructors

BigInteger

Added in API level 1
BigInteger (int numBits, 
                Random random)

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

Parameters
numBits int: maximum length of the new BigInteger in bits.
random Random: is the random number generator to be used.
Throws
IllegalArgumentException if numBits < 0.

BigInteger

Added in API level 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. The probability that the returned BigInteger is prime is greater than 1 - 1/2certainty).

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 int: length of the new BigInteger in bits.
certainty int: tolerated primality uncertainty.
random Random
Throws
ArithmeticException if bitLength < 2.

See also:

BigInteger

Added in API level 1
BigInteger (String value)

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

Parameters
value String: string representation of the new BigInteger.
Throws
NullPointerException if value == null.
NumberFormatException if value is not a valid representation of a BigInteger.

BigInteger

Added in API level 1
BigInteger (String value, 
                int radix)

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

Parameters
value String: string representation of the new BigInteger.
radix int: the base to be used for the conversion.
Throws
NullPointerException if value == null.
NumberFormatException if value is not a valid representation of a BigInteger or if radix < Character.MIN_RADIX or radix > Character.MAX_RADIX.

BigInteger

Added in API level 1
BigInteger (int signum, 
                byte[] magnitude)

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

Parameters
signum int: sign of the new BigInteger (-1 for negative, 0 for zero, 1 for positive).
magnitude byte: magnitude of the new BigInteger with the most significant byte first.
Throws
NullPointerException if magnitude == null.
NumberFormatException if the sign is not one of -1, 0, 1 or if the sign is zero and the magnitude contains non-zero entries.

BigInteger

Added in API level 1
BigInteger (byte[] value)

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

Parameters
value byte: two's complement representation of the new BigInteger.
Throws
NullPointerException if value == null.
NumberFormatException if the length of value is zero.

Public methods

abs

Added in API level 1
BigInteger abs ()

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

Returns
BigInteger

add

Added in API level 1
BigInteger add (BigInteger value)

Returns a BigInteger whose value is this + value.

Parameters
value BigInteger
Returns
BigInteger

and

Added in API level 1
BigInteger and (BigInteger value)

Returns a BigInteger whose value is this & value.

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

Parameters
value BigInteger: value to be and'ed with this.
Returns
BigInteger
Throws
NullPointerException if value == null.

andNot

Added in API level 1
BigInteger andNot (BigInteger value)

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

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

Parameters
value BigInteger: value to be not'ed and then and'ed with this.
Returns
BigInteger
Throws
NullPointerException if value == null.

bitCount

Added in API level 1
int bitCount ()

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

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

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

Returns
int

bitLength

Added in API level 1
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
int the length of the minimal two's complement representation for this without the sign bit.

clearBit

Added in API level 1
BigInteger clearBit (int n)

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

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

Parameters
n int: position where the bit in this has to be cleared.
Returns
BigInteger
Throws
ArithmeticException if n < 0.

compareTo

Added in API level 1
int compareTo (BigInteger value)

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

Parameters
value BigInteger: value to be compared with this.
Returns
int
Throws
NullPointerException if value == null.

divide

Added in API level 1
BigInteger divide (BigInteger divisor)

Returns a BigInteger whose value is this / divisor.

Parameters
divisor BigInteger: value by which this is divided.
Returns
BigInteger this / divisor.
Throws
NullPointerException if divisor == null.
ArithmeticException if divisor == 0.

divideAndRemainder

Added in API level 1
BigInteger[] divideAndRemainder (BigInteger divisor)

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

Parameters
divisor BigInteger: value by which this is divided.
Returns
BigInteger[]
Throws
NullPointerException if divisor == null.
ArithmeticException if divisor == 0.

See also:

doubleValue

Added in API level 1
double doubleValue ()

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

Returns
double the primitive double value of this object.

equals

Added in API level 1
boolean equals (Object x)

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 Object: the object to compare this instance with.
Returns
boolean true if the specified object is equal to this Object; false otherwise.

flipBit

Added in API level 1
BigInteger flipBit (int n)

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

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

Parameters
n int: position where the bit in this has to be flipped.
Returns
BigInteger
Throws
ArithmeticException if n < 0.

floatValue

Added in API level 1
float floatValue ()

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

Returns
float the primitive float value of this object.

gcd

Added in API level 1
BigInteger gcd (BigInteger value)

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

Parameters
value BigInteger: value with which the greatest common divisor is computed.
Returns
BigInteger
Throws
NullPointerException if value == null.

getLowestSetBit

Added in API level 1
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
int

hashCode

Added in API level 1
int hashCode ()

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
int this object's hash code.

intValue

Added in API level 1
int intValue ()

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

Returns
int the primitive int value of this object.

isProbablePrime

Added in API level 1
boolean isProbablePrime (int certainty)

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

Parameters
certainty int: tolerated primality uncertainty.
Returns
boolean true, if this is probably prime, false otherwise.

longValue

Added in API level 1
long longValue ()

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

Returns
long the primitive long value of this object.

max

Added in API level 1
BigInteger max (BigInteger value)

Returns the maximum of this BigInteger and value.

Parameters
value BigInteger: value to be used to compute the maximum with this
Returns
BigInteger
Throws
NullPointerException if value == null

min

Added in API level 1
BigInteger min (BigInteger value)

Returns the minimum of this BigInteger and value.

Parameters
value BigInteger: value to be used to compute the minimum with this.
Returns
BigInteger
Throws
NullPointerException if value == null.

mod

Added in API level 1
BigInteger mod (BigInteger m)

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

Parameters
m BigInteger: the modulus.
Returns
BigInteger this mod m.
Throws
NullPointerException if m == null.
ArithmeticException if m < 0.

modInverse

Added in API level 1
BigInteger modInverse (BigInteger m)

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

Parameters
m BigInteger: the modulus.
Returns
BigInteger
Throws
NullPointerException if m == null
ArithmeticException if m < 0 or if this is not relatively prime to m

modPow

Added in API level 1
BigInteger modPow (BigInteger exponent, 
                BigInteger modulus)

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

Parameters
exponent BigInteger
modulus BigInteger
Returns
BigInteger
Throws
NullPointerException if modulus == null or exponent == null.
ArithmeticException if modulus < 0 or if exponent < 0 and not relatively prime to modulus.

multiply

Added in API level 1
BigInteger multiply (BigInteger value)

Returns a BigInteger whose value is this * value.

Parameters
value BigInteger
Returns
BigInteger
Throws
NullPointerException if value == null.

negate

Added in API level 1
BigInteger negate ()

Returns a BigInteger whose value is the -this.

Returns
BigInteger

nextProbablePrime

Added in API level 1
BigInteger nextProbablePrime ()

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

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

not

Added in API level 1
BigInteger not ()

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

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

Returns
BigInteger

or

Added in API level 1
BigInteger or (BigInteger value)

Returns a BigInteger whose value is this | value.

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

Parameters
value BigInteger: value to be or'ed with this.
Returns
BigInteger
Throws
NullPointerException if value == null.

pow

Added in API level 1
BigInteger pow (int exp)

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

Parameters
exp int
Returns
BigInteger
Throws
ArithmeticException if exp < 0.

probablePrime

Added in API level 1
BigInteger probablePrime (int bitLength, 
                Random random)

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

Parameters
bitLength int: length of the new BigInteger in bits.
random Random
Returns
BigInteger probably prime random BigInteger instance.
Throws
IllegalArgumentException if bitLength < 2.

remainder

Added in API level 1
BigInteger remainder (BigInteger divisor)

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

Parameters
divisor BigInteger: value by which this is divided.
Returns
BigInteger
Throws
NullPointerException if divisor == null.
ArithmeticException if divisor == 0.

setBit

Added in API level 1
BigInteger setBit (int n)

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

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

Parameters
n int: position where the bit in this has to be set.
Returns
BigInteger
Throws
ArithmeticException if n < 0.

shiftLeft

Added in API level 1
BigInteger shiftLeft (int n)

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

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

Parameters
n int: shift distance.
Returns
BigInteger this << n if n >= 0; this >> (-n). otherwise

shiftRight

Added in API level 1
BigInteger shiftRight (int n)

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

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

Parameters
n int: shift distance
Returns
BigInteger this >> n if n >= 0; this << (-n) otherwise

signum

Added in API level 1
int signum ()

Returns the sign of this BigInteger.

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

subtract

Added in API level 1
BigInteger subtract (BigInteger value)

Returns a BigInteger whose value is this - value.

Parameters
value BigInteger
Returns
BigInteger

testBit

Added in API level 1
boolean testBit (int n)

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

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

Parameters
n int: position where the bit in this has to be inspected.
Returns
boolean
Throws
ArithmeticException if n < 0.

toByteArray

Added in API level 1
byte[] toByteArray ()

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

Returns
byte[]

toString

Added in API level 1
String toString ()

Returns a string representation of this BigInteger in decimal form.

Returns
String a printable representation of this object.

toString

Added in API level 1
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 int: base to be used for the string representation.
Returns
String

valueOf

Added in API level 1
BigInteger valueOf (long value)

Returns a BigInteger whose value is equal to value.

Parameters
value long
Returns
BigInteger

xor

Added in API level 1
BigInteger xor (BigInteger value)

Returns a BigInteger whose value is this ^ value.

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

Parameters
value BigInteger: value to be xor'ed with this
Returns
BigInteger
Throws
NullPointerException if value == null
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.