Semantics of arithmetic operations exactly mimic those of Java's integer
arithmetic operators, as defined in The Java Language Specification.
For example, division by zero throws an ArithmeticException, and
division of a negative by a positive yields a negative (or zero) remainder.
Semantics of shift operations extend those of Java's shift operators
to allow for negative shift distances. A right-shift with a negative
shift distance results in a left shift, and vice-versa. The unsigned
right shift operator (>>>) is omitted since this operation
only makes sense for a fixed sized word and not for a
representation conceptually having an infinite number of leading
virtual sign bits.
Semantics of bitwise logical operations exactly mimic those of Java's
bitwise integer operators. The binary operators (and,
or, xor) implicitly perform sign extension on the shorter
of the two operands prior to performing the operation.
Comparison operations perform signed integer comparisons, analogous to those performed by Java's relational and equality operators.
Modular arithmetic operations are provided to compute residues, perform
exponentiation, and compute multiplicative inverses. These methods always
return a non-negative result, between 0 and (modulus - 1),
inclusive.
Bit operations operate on a single bit of the two's-complement representation of their operand. If necessary, the operand is sign-extended so that it contains the designated bit. None of the single-bit operations can produce a BigInteger with a different sign from the BigInteger being operated on, as they affect only a single bit, and the arbitrarily large abstraction provided by this class ensures that conceptually there are infinitely many "virtual sign bits" preceding each BigInteger.
For the sake of brevity and clarity, pseudo-code is used throughout the
descriptions of BigInteger methods. The pseudo-code expression
(i + j) is shorthand for "a BigInteger whose value is
that of the BigInteger i plus that of the BigInteger j."
The pseudo-code expression (i == j) is shorthand for
"true if and only if the BigInteger i represents the same
value as the BigInteger j." Other pseudo-code expressions are
interpreted similarly.
All methods and constructors in this class throw
NullPointerException when passed
a null object reference for any input parameter.
BigInteger must support values in the range
-2Integer.MAX_VALUE (exclusive) to
+2Integer.MAX_VALUE (exclusive)
and may support values outside of that range.
An ArithmeticException is thrown when a BigInteger
constructor or method would generate a value outside of the
supported range.
The range of probable prime values is limited and may be less than
the full supported positive range of BigInteger.
The range must be at least 1 to 2500000000.
API Note
As BigInteger values are
arbitrary precision integers, the algorithmic complexity of the
methods of this class varies and may be superlinear in the size of
the input. For example, a method like intValue() would be
expected to run in O(1), that is constant time, since with
the current internal representation only a fixed-size component of
the BigInteger needs to be accessed to perform the
conversion to int. In contrast, a method like not()
would be expected to run in O(n) time where n
is the size of the BigInteger in bits, that is, to run in
time proportional to the size of the input. For multiplying two
BigInteger values of size n, a naive multiplication
algorithm would run in time O(n2) and
theoretical results indicate a multiplication algorithm for numbers
using this category of representation must run in at least
O(n log n). Common multiplication
algorithms between the bounds of the naive and theoretical cases
include the Karatsuba multiplication
(O(n1.585)) and 3-way Toom-Cook
multiplication (O(n1.465)).
A particular implementation of multiply is free to switch between different algorithms for
different inputs, such as to improve actual running time to produce
the product by using simpler algorithms for smaller inputs even if
the simpler algorithm has a larger asymptotic complexity.
Operations may also allocate and compute on intermediate results, potentially those allocations may be as large as in proportion to the running time of the algorithm.
Users of BigInteger concerned with bounding the running
time or space of operations can screen out BigInteger
values above a chosen magnitude.
Implementation Note
In the reference implementation, BigInteger constructors and
operations throw ArithmeticException when the result is out
of the supported range of
-2Integer.MAX_VALUE (exclusive) to
+2Integer.MAX_VALUE (exclusive).
BigDecimal
| Modifier and Type | Class and Description |
|---|---|
| private abstract static class | |
| private static class |
| Modifier and Type | Field and Description |
|---|---|
| private int | bitCountPlusOne
One plus the bitCount of this BigInteger. |
| private static long[] | |
| pack-priv static int[] | |
| pack-priv static final int | BURNIKEL_ZIEGLER_OFFSET
The offset value for using Burnikel-Ziegler division. |
| pack-priv static final int | BURNIKEL_ZIEGLER_THRESHOLD
The threshold value for using Burnikel-Ziegler division. |
| private static final int | |
| private static int[] | |
| private static int[] | |
| private static int[] | |
| private static final int | KARATSUBA_SQUARE_THRESHOLD
The threshold value for using Karatsuba squaring. |
| private static final int | KARATSUBA_THRESHOLD
The threshold value for using Karatsuba multiplication. |
| private static final double | LOG_TWO
The natural log of 2. |
| private static final double[] | logCache
The cache of logarithms of radices for base conversion. |
| pack-priv static final long | LONG_MASK
This mask is used to obtain the value of an int as if it were unsigned. |
| private static BigInteger[] | |
| private int | lowestSetBitPlusTwo
Two plus the lowest set bit of this BigInteger. |
| pack-priv final int[] | mag
The magnitude of this BigInteger, in big-endian order: the zeroth element of this array is the most-significant int of the magnitude. |
| private int | magBitLengthPlusOne
One plus the bitLength of the magnitude of this BigInteger. |
| private static final int | MAX_CONSTANT
Initialize static constant array when class is loaded. |
| private static final int | MAX_MAG_LENGTH
This constant limits |
| private static final int | MONTGOMERY_INTRINSIC_THRESHOLD
The threshold for using an intrinsic version of implMontgomeryXXX to perform Montgomery multiplication. |
| private static final int | MULTIPLY_SQUARE_THRESHOLD
The threshold value for using squaring code to perform multiplication
of a |
| private static final BigInteger | NEGATIVE_ONE
The BigInteger constant -1. |
| private static final BigInteger[] | |
| private static int | |
| private int | numberOfTrailingZeroIntsPlusTwo
Two plus the index of the lowest-order int in the magnitude of this BigInteger that contains a nonzero int. |
| public static final BigInteger | ONE
The BigInteger constant one. |
| private static final BigInteger[] | |
| private static volatile BigInteger[][] | powerCache
The cache of powers of each radix. |
| private static final int | PRIME_SEARCH_BIT_LENGTH_LIMIT
Bit lengths larger than this constant can cause overflow in searchLen calculation and in BitSieve.singleSearch method. |
| private static final int | SCHOENHAGE_BASE_CONVERSION_THRESHOLD
The threshold value for using Schoenhage recursive base conversion. |
| private static final ObjectStreamField[] | serialPersistentFields
Serializable fields for BigInteger. |
| private static final long | serialVersionUID
use serialVersionUID from JDK 1.1.
|
| pack-priv final int | signum
The signum of this BigInteger: -1 for negative, 0 for zero, or 1 for positive. |
| private static final BigInteger | |
| private static final int | |
| public static final BigInteger | TEN
The BigInteger constant ten. |
| private static final int | TOOM_COOK_SQUARE_THRESHOLD
The threshold value for using Toom-Cook squaring. |
| private static final int | TOOM_COOK_THRESHOLD
The threshold value for using 3-way Toom-Cook multiplication. |
| public static final BigInteger | TWO
The BigInteger constant two. |
| public static final BigInteger | ZERO
The BigInteger constant zero. |
| private static final String |
| Access | Constructor and Description |
|---|---|
| public | BigInteger(byte[]
byte array containing a sub-array which is the big-endian
two's-complement binary representation of a BigInteger. val, int the start offset of the binary representation. off, int the number of bytes to use. len)Translates a byte sub-array containing the two's-complement binary representation of a BigInteger into a BigInteger. |
| public | BigInteger(byte[]
big-endian two's-complement binary representation of a
BigInteger. val)Translates a byte array containing the two's-complement binary representation of a BigInteger into a BigInteger. |
| private | BigInteger(int[] val)
This private constructor translates an int array containing the two's-complement binary representation of a BigInteger into a BigInteger. |
| public | BigInteger(int
signum of the number (-1 for negative, 0 for zero, 1
for positive). signum, byte[] big-endian binary representation of the magnitude of
the number. magnitude, int the start offset of the binary representation. off, int the number of bytes to use. len)Translates the sign-magnitude representation of a BigInteger into a BigInteger. |
| public | BigInteger(int
signum of the number (-1 for negative, 0 for zero, 1
for positive). signum, byte[] big-endian binary representation of the magnitude of
the number. magnitude)Translates the sign-magnitude representation of a BigInteger into a BigInteger. |
| private | BigInteger(int signum, int[] magnitude)
A constructor for internal use that translates the sign-magnitude representation of a BigInteger into a BigInteger. |
| public | BigInteger(String
String representation of BigInteger. val, int radix to be used in interpreting radix)val.Translates the String representation of a BigInteger in the specified radix into a BigInteger. |
| pack-priv | |
| public | BigInteger(String
decimal String representation of BigInteger. val)Translates the decimal String representation of a BigInteger into a BigInteger. |
| public | BigInteger(int
maximum bitLength of the new BigInteger. numBits, Random source of randomness to be used in computing the new
BigInteger. rnd)Constructs a randomly generated BigInteger, uniformly distributed over
the range 0 to (2 |
| public | BigInteger(int
bitLength of the returned BigInteger. bitLength, int a measure of the uncertainty that the caller is
willing to tolerate. The probability that the new BigInteger
represents a prime number will exceed
(1 - 1/2 certainty, Random certainty). The execution time of
this constructor is proportional to the value of this parameter.source of random bits used to select candidates to be
tested for primality. rnd)Constructs a randomly generated positive BigInteger that is probably prime, with the specified bitLength. |
| pack-priv | BigInteger(int[] magnitude, int signum)
This internal constructor differs from its public cousin with the arguments reversed in two ways: it assumes that its arguments are correct, and it doesn't copy the magnitude array. |
| private | BigInteger(byte[] magnitude, int signum)
This private constructor is for internal use and assumes that its arguments are correct. |
| private | BigInteger(long mag, int signum)
Constructs a BigInteger with magnitude specified by the long, which may not be zero, and the signum specified by the int. |
| private |
| Modifier and Type | Method and Description |
|---|---|
| public BigInteger | |
| public BigInteger | Returns: this + valvalue to be added to this BigInteger. val)Returns a BigInteger whose value is |
| pack-priv BigInteger | |
| private static int[] | |
| private static int[] | |
| pack-priv static int | |
| public BigInteger | Returns: this & valvalue to be AND'ed with this BigInteger. val)Returns a BigInteger whose value is |
| public BigInteger | Returns: this & ~valvalue to be complemented and AND'ed with this BigInteger. val)Returns a BigInteger whose value is |
| public int | Returns: number of bits in the two's complement representation of this BigInteger that differ from its sign bit.Returns the number of bits in the two's complement representation of this BigInteger that differ from its sign bit. |
| public int | Returns: number of bits in the minimal two's-complement representation of this BigInteger, excluding a sign bit.Returns the number of bits in the minimal two's-complement representation of this BigInteger, excluding a sign bit. |
| pack-priv static int | |
| pack-priv static int | |
| public byte | Returns: thisBigInteger converted to a byte.Converts this |
| private void | |
| private void | |
| public BigInteger | Returns: this & ~(1<<n)index of bit to clear. n)Returns a BigInteger whose value is equivalent to this BigInteger with the designated bit cleared. |
| pack-priv final int | Returns: -1, 0 or 1 as this magnitude array is less than, equal to or greater than the magnitude array for the specified BigInteger's.BigInteger whose magnitude array to be compared. val)Compares the magnitude array of this BigInteger with the specified BigInteger's. |
| pack-priv final int | |
| public int | Returns: -1, 0 or 1 as this BigInteger is numerically less than, equal to, or greater thanval.BigInteger to which this BigInteger is to be compared. val)Implements java. Compares this BigInteger with the specified BigInteger. |
| private static void | |
| public BigInteger | Returns: this / valvalue by which this BigInteger is to be divided. val)Returns a BigInteger whose value is |
| public BigInteger[] | Returns: an array of two BigIntegers: the quotient(this / val)
is the initial element, and the remainder (this % val)
is the final element.value by which this BigInteger is to be divided, and the
remainder computed. val)Returns an array of two BigIntegers containing |
| private BigInteger[] | Returns: an array containing the quotient and remainderthe divisor val)Computes |
| private BigInteger[] | |
| private BigInteger | Returns: this / valthe divisor val)Calculates |
| private BigInteger | Returns: this / valvalue by which this BigInteger is to be divided. val)Returns a BigInteger whose value is |
| public double | Returns: this BigInteger converted to adouble.Implements abstract java. Converts this BigInteger to a |
| public boolean | Returns: true if and only if the specified Object is a
BigInteger whose value is numerically equal to this BigInteger.Object to which this BigInteger is to be compared. x)Overrides java. Compares this BigInteger with the specified Object for equality. |
| private BigInteger | exactDivideBy3()
Does an exact division (that is, the remainder is known to be zero) of the specified number by 3. |
| private boolean | |
| public BigInteger | Returns: this ^ (1<<n)index of bit to flip. n)Returns a BigInteger whose value is equivalent to this BigInteger with the designated bit flipped. |
| public float | Returns: this BigInteger converted to afloat.Implements abstract java. Converts this BigInteger to a |
| public BigInteger | Returns: GCD(abs(this), abs(val))value with which the GCD is to be computed. val)Returns a BigInteger whose value is the greatest common divisor of
|
| private int | getInt(int n)
Returns the specified int of the little-endian two's complement representation (int 0 is the least significant). |
| private BigInteger | |
| public int | Returns: index of the rightmost one bit in this BigInteger.Returns the index of the rightmost (lowest-order) one bit in this BigInteger (the number of zero bits to the right of the rightmost one bit). |
| private static int | |
| private static BigInteger | getRadixConversionCache(int radix, int exponent)
Returns the value radix^(2^exponent) from the cache. |
| private BigInteger | getToomSlice(int
The size of the lower-order bit slices. lowerSize, int The size of the higher-order bit slices. upperSize, int The index of which slice is requested, which must be a
number from 0 to size-1. Slice 0 is the highest-order bits, and slice
size-1 are the lowest-order bits. Slice 0 may be of different size than
the other slices. slice, int The size of the larger integer array, used to align
slices to the appropriate position when multiplying different-sized
numbers. fullsize)Returns a slice of a BigInteger for use in Toom-Cook multiplication. |
| private BigInteger | |
| public int | Returns: the hash code for this BigIntegerOverrides java. Returns the hash code for this BigInteger. |
| private static int[] | |
| private static void | |
| private static int[] | |
| private static int | implMulAdd(int[] out, int[] in, int offset, int len, int k)
Java Runtime may use intrinsic for this method. |
| private static void | |
| private static int[] | |
| private static final int[] | |
| private static void | |
| private static int | |
| private int | intLength()
Returns the length of the two's complement representation in ints, including space for at least one sign bit. |
| public int | Returns: this BigInteger converted to anint.Implements abstract java. Converts this BigInteger to an |
| public int | Returns: thisBigInteger converted to an int.Converts this |
| public boolean | Returns: true if this BigInteger is probably prime,
false if it's definitely composite.a measure of the uncertainty that the caller is
willing to tolerate: if the call returns certainty)true
the probability that this BigInteger is prime exceeds
(1 - 1/2certainty). The execution time of
this method is proportional to the value of this parameter.Returns |
| private static int | |
| pack-priv static int[] | |
| private static BigInteger | largePrime(int bitLength, int certainty, Random rnd)
Find a random number of the specified bitLength that is probably prime. |
| private static int[] | |
| public long | Returns: this BigInteger converted to along.Implements abstract java. Converts this BigInteger to a |
| public long | Returns: thisBigInteger converted to a long.Converts this |
| private static BigInteger | |
| private int | |
| private byte[] | |
| private static int[] | |
| private static int[] | makePositive(int[] a)
Takes an array a representing a negative 2's-complement number and returns the minimal (no leading zero ints) unsigned whose value is -a. |
| private static int[] | |
| public BigInteger | Returns: the BigInteger whose value is the greater of this andval. If they are equal, either may be returned.value with which the maximum is to be computed. val)Returns the maximum of this BigInteger and |
| public BigInteger | Returns: the BigInteger whose value is the lesser of this BigInteger andval. If they are equal, either may be returned.value with which the minimum is to be computed. val)Returns the minimum of this BigInteger and |
| public BigInteger | |
| private BigInteger | |
| public BigInteger | Returns: this-1 mod m.the modulus. m)Returns a BigInteger whose value is |
| public BigInteger | Returns: thisexponent mod mthe exponent. exponent, BigInteger the modulus. m)Returns a BigInteger whose value is
|
| private BigInteger | modPow2(BigInteger exponent, int p)
Returns a BigInteger whose value is (this ** exponent) mod (2**p) |
| private static int[] | |
| private static int[] | |
| private static int[] | |
| pack-priv static int | mulAdd(int[] out, int[] in, int offset, int len, int k)
Multiply an array by one word k and add to result, return the carry |
| public BigInteger | Returns: this * valvalue to be multiplied by this BigInteger. val)Returns a BigInteger whose value is |
| private BigInteger | Returns: this * valvalue to be multiplied by this BigInteger. val, boolean whether this is a recursive invocation isRecursion, boolean whether the multiply should be done in parallel parallel, int depth)Returns a BigInteger whose value is |
| pack-priv BigInteger | multiply(long v)
Package private methods used by BigDecimal code to multiply a BigInteger with a long. |
| private static BigInteger | |
| private static BigInteger | multiplyKaratsuba(BigInteger x, BigInteger y)
Multiplies two BigIntegers using the Karatsuba multiplication algorithm. |
| private static int[] | multiplyToLen(int[] x, int xlen, int[] y, int ylen, int[] z)
Multiplies int arrays x and y to the specified lengths and places the result into z. |
| private static void | |
| private static BigInteger | multiplyToomCook3(BigInteger a, BigInteger b, boolean parallel, int depth)
Multiplies two BigIntegers using a 3-way Toom-Cook multiplication algorithm. |
| public BigInteger | |
| public BigInteger | Returns: the first integer greater than thisBigInteger that
is probably prime.Returns the first integer greater than this |
| public BigInteger | |
| private int | numberOfTrailingZeroInts()
Returns the index of the int that contains the first nonzero int in the little-endian binary representation of the magnitude (int 0 is the least significant). |
| private BigInteger | |
| public BigInteger | Returns: this | valvalue to be OR'ed with this BigInteger. val)Returns a BigInteger whose value is |
| private static void | padWithZeros(StringBuilder
The StringBuilder that will be appended to. buf, int The number of zeros to append. numZeros)If |
| public BigInteger | Returns: this * valvalue to be multiplied by this BigInteger. val)Returns a BigInteger whose value is |
| private int | |
| private boolean | |
| private boolean | passesMillerRabin(int iterations, Random rnd)
Returns true iff this BigInteger passes the specified number of Miller-Rabin tests. |
| public BigInteger | Returns: thisexponentexponent to which this BigInteger is to be raised. exponent)Returns a BigInteger whose value is |
| pack-priv boolean | Returns: true if this BigInteger is probably prime,
false if it's definitely composite.a measure of the uncertainty that the caller is
willing to tolerate: if the call returns certainty, Random random)true
the probability that this BigInteger is prime exceeds
(1 - 1/2certainty). The execution time of
this method is proportional to the value of this parameter.Returns |
| pack-priv static void | |
| pack-priv static void | |
| public static BigInteger | Returns: a BigInteger ofbitLength bits that is probably primebitLength of the returned BigInteger. bitLength, Random source of random bits used to select candidates to be
tested for primality. rnd)Returns a positive BigInteger that is probably prime, with the specified bitLength. |
| private static byte[] | |
| private void | readObject(ObjectInputStream
the stream being read. s)Reconstitute the |
| private void | |
| public BigInteger | Returns: this % valvalue by which this BigInteger is to be divided, and the
remainder computed. val)Returns a BigInteger whose value is |
| private BigInteger | Returns: this % valthe divisor val)Calculates |
| private BigInteger | |
| private static void | |
| public BigInteger | Returns: the integernth root of thisthe root degree n)Returns the integer |
| public BigInteger[] | Returns: an array of two BigIntegers with the integernth root at
offset 0 and the remainder at offset 1the root degree n)Returns an array of two BigIntegers containing the integer |
| public BigInteger | Returns: this | (1<<n)index of bit to set. n)Returns a BigInteger whose value is equivalent to this BigInteger with the designated bit set. |
| public BigInteger | Returns: this << nshift distance, in bits. n)Returns a BigInteger whose value is |
| private static int[] | Returns: mag << nmagnitude, the most-significant int ( mag, int mag[0]) must be non-zero.unsigned shift distance, in bits. n)Returns a magnitude array whose value is |
| private static void | |
| public BigInteger | Returns: this >> nshift distance, in bits. n)Returns a BigInteger whose value is |
| private BigInteger | Returns: this >> nunsigned shift distance, in bits. n)Returns a BigInteger whose value is |
| private static void | |
| public short | Returns: thisBigInteger converted to a short.Converts this |
| private int | |
| private int | |
| public int | Returns: -1, 0 or 1 as the value of this BigInteger is negative, zero or positive.Returns the signum function of this BigInteger. |
| private static BigInteger | smallPrime(int bitLength, int certainty, Random rnd)
Find a random number of the specified bitLength that is probably prime. |
| private void | smallToString(int
The base to convert to. radix, StringBuilder The StringBuilder that will be appended to in place. buf, int The minimum number of digits to pad to. digits)This method is used to perform toString when arguments are small. |
| public BigInteger | |
| public BigInteger[] | Returns: an array of two BigIntegers with the integer square root at offset 0 and the remainder at offset 1Returns an array of two BigIntegers containing the integer square root
|
| private BigInteger | |
| private BigInteger | Returns: this2whether this is a recursive invocation isRecursion, boolean parallel, int depth)Returns a BigInteger whose value is |
| private BigInteger | |
| private static final int[] | |
| private BigInteger | squareToomCook3(boolean parallel, int depth)
Squares a BigInteger using the 3-way Toom-Cook squaring algorithm. |
| private static int[] | |
| private static int[] | |
| private static int[] | stripLeadingZeroInts(int[] val, boolean trusted)
Returns the input array stripped of any leading zero ints. |
| private static int | |
| private static int[] | |
| private static int[] | subtract(int[] big, long val)
Subtracts the contents of the second argument (val) from the first (big). |
| public BigInteger | Returns: this - valvalue to be subtracted from this BigInteger. val)Returns a BigInteger whose value is |
| private static int[] | subtract(int[] big, int[] little)
Subtracts the contents of the second int arrays (little) from the first (big). |
| public boolean | Returns: true if and only if the designated bit is set.index of bit to test. n)Returns |
| public byte[] | Returns: a byte array containing the two's-complement representation of this BigInteger.Returns a byte array containing the two's-complement representation of this BigInteger. |
| private static int[] | |
| public String | Returns: String representation of this BigInteger in the given radix.radix of the String representation. radix)Returns the String representation of this BigInteger in the given radix. |
| private static void | toString(BigInteger
The number to convert to a string. u, StringBuilder The StringBuilder that will be appended to in place. sb, int The base to convert to. radix, int The minimum number of digits to pad to. digits)Converts the specified BigInteger to a string and appends to
|
| public String | Returns: decimal String representation of this BigInteger.Overrides java. Returns the decimal String representation of this BigInteger. |
| private static int[] | |
| pack-priv static long | |
| public static BigInteger | Returns: a BigInteger with the specified value.value of the BigInteger to return. val)Returns a BigInteger whose value is equal to that of the
specified |
| private static BigInteger | |
| private void | writeObject(ObjectOutputStream
the stream to serialize to. s)Save the |
| public BigInteger | Returns: this ^ valvalue to be XOR'ed with this BigInteger. val)Returns a BigInteger whose value is |