# Print output for @column tags ?> BigInteger - Android SDK | Android Developers

Most visited

Recently visited

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)

Indicates whether some other object is "equal to" this one.

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 a hash code value for the 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

Fields

ONE

public static final BigInteger ONE

The BigInteger constant 1.

TEN

public static final BigInteger TEN

The BigInteger constant 10.

ZERO

public static final BigInteger ZERO

The BigInteger constant 0.

Public constructors

BigInteger

public 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

public 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/2<sup>certainty</sup>).

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

public 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

public 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

public 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

public 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

public BigInteger abs ()

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

Returns
BigInteger

add

public BigInteger add (BigInteger value)

Returns a BigInteger whose value is this + value.

Parameters
value BigInteger

Returns
BigInteger

and

public 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

public 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

public 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

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

clearBit

public 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

public 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

public 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

public 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

public 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 numeric value represented by this object after conversion to type double.

equals

public boolean equals (Object x)

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Parameters
x Object: the reference object with which to compare.

Returns
boolean true if this object is the same as the obj argument; false otherwise.

flipBit

public 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

public 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 numeric value represented by this object after conversion to type float.

gcd

public 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

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
int

hashCode

public int hashCode ()

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java™ programming language.)

Returns
int a hash code value for this object.

intValue

public 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 numeric value represented by this object after conversion to type int.

isProbablePrime

public 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/2<sup>certainty</sup>). 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

public 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 numeric value represented by this object after conversion to type long.

max

public 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

public 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

public 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

public 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

public 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

public BigInteger multiply (BigInteger value)

Returns a BigInteger whose value is this * value.

Parameters
value BigInteger

Returns
BigInteger

Throws
NullPointerException if value == null.

negate

public BigInteger negate ()

Returns a BigInteger whose value is the -this.

Returns
BigInteger

nextProbablePrime

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 greater than 1 - 1/2<sup>100</sup>.

Returns
BigInteger smallest integer > this which is probably prime.

Throws
ArithmeticException if this < 0.

not

public 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

public 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

public BigInteger pow (int exp)

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

Parameters
exp int

Returns
BigInteger

Throws
ArithmeticException if exp < 0.

probablePrime

public 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. The probability that the returned BigInteger is prime is greater than 1 - 1/2<sup>100</sup>).

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

public 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

public 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

public 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

public 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

public int signum ()

Returns the sign of this BigInteger.

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

subtract

public BigInteger subtract (BigInteger value)

Returns a BigInteger whose value is this - value.

Parameters
value BigInteger

Returns
BigInteger

testBit

public 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

public byte[] toByteArray ()

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

Returns
byte[]

toString

public String toString ()

Returns a string representation of this BigInteger in decimal form.

Returns
String a string representation of the object.

toString

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 int: base to be used for the string representation.

Returns
String

valueOf

public static BigInteger valueOf (long value)

Returns a BigInteger whose value is equal to value.

Parameters
value long

Returns
BigInteger

xor

public 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