Save This Page
Home » openjdk-7 » java » math » [javadoc | source]
java.math
public class: BigInteger [javadoc | source]
java.lang.Object
   java.lang.Number
      java.math.BigInteger

All Implemented Interfaces:
    Comparable, Serializable

Immutable arbitrary-precision integers. All operations behave as if BigIntegers were represented in two's-complement notation (like Java's primitive integer types). BigInteger provides analogues to all of Java's primitive integer operators, and all relevant methods from java.lang.Math. Additionally, BigInteger provides operations for modular arithmetic, GCD calculation, primality testing, prime generation, bit manipulation, and a few other miscellaneous operations.

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 {@code ArithmeticException}, and division of a negative by a positive yields a negative (or zero) remainder. All of the details in the Spec concerning overflow are ignored, as BigIntegers are made as large as necessary to accommodate the results of an operation.

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 ({@code >>>}) is omitted, as this operation makes little sense in combination with the "infinite word size" abstraction provided by this class.

Semantics of bitwise logical operations exactly mimic those of Java's bitwise integer operators. The binary operators ({@code and}, {@code or}, {@code 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 {@code 0} and {@code (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 "infinite word size" abstraction provided by this class ensures that 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 {@code (i + j)} is shorthand for "a BigInteger whose value is that of the BigInteger {@code i} plus that of the BigInteger {@code j}." The pseudo-code expression {@code (i == j)} is shorthand for "{@code true} if and only if the BigInteger {@code i} represents the same value as the BigInteger {@code j}." Other pseudo-code expressions are interpreted similarly.

All methods and constructors in this class throw {@code NullPointerException} when passed a null object reference for any input parameter.

Field Summary
final  int signum    The signum of this BigInteger: -1 for negative, 0 for zero, or 1 for positive. Note that the BigInteger zero must have a signum of 0. This is necessary to ensures that there is exactly one representation for each BigInteger value.
    serial:
 
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. The magnitude must be "minimal" in that the most-significant int ({@code mag[0]}) must be non-zero. This is necessary to ensure that there is exactly one representation for each BigInteger value. Note that this implies that the BigInteger zero has a zero-length mag array. 
static final  long LONG_MASK    This mask is used to obtain the value of an int as if it were unsigned. 
public static final  BigInteger ZERO    The BigInteger constant zero.
    since: 1.2 -
 
public static final  BigInteger ONE    The BigInteger constant one.
    since: 1.2 -
 
public static final  BigInteger TEN    The BigInteger constant ten.
    since: 1.5 -
 
static  int[] bnExpModThreshTable     
Constructor:
 public BigInteger(byte[] val) 
 BigInteger(char[] val) 
 public BigInteger(String val) 
    Translates the decimal String representation of a BigInteger into a BigInteger. The String representation consists of an optional minus sign followed by a sequence of one or more decimal digits. The character-to-digit mapping is provided by {@code Character.digit}. The String may not contain any extraneous characters (whitespace, for example).
    Parameters:
    val - decimal String representation of BigInteger.
    Throws:
    NumberFormatException - {@code val} is not a valid representation of a BigInteger.
    Also see:
    Character#digit
 public BigInteger(int signum,
    byte[] magnitude) 
 public BigInteger(String val,
    int radix) 
    Translates the String representation of a BigInteger in the specified radix into a BigInteger. The String representation consists of an optional minus or plus sign followed by a sequence of one or more digits in the specified radix. The character-to-digit mapping is provided by {@code Character.digit}. The String may not contain any extraneous characters (whitespace, for example).
    Parameters:
    val - String representation of BigInteger.
    radix - radix to be used in interpreting {@code val}.
    Throws:
    NumberFormatException - {@code val} is not a valid representation of a BigInteger in the specified radix, or {@code radix} is outside the range from Character#MIN_RADIX to Character#MAX_RADIX , inclusive.
    Also see:
    Character#digit
 public BigInteger(int numBits,
    Random rnd) 
    Constructs a randomly generated BigInteger, uniformly distributed over the range 0 to (2{@code numBits} - 1), inclusive. The uniformity of the distribution assumes that a fair source of random bits is provided in {@code rnd}. Note that this constructor always constructs a non-negative BigInteger.
    Parameters:
    numBits - maximum bitLength of the new BigInteger.
    rnd - source of randomness to be used in computing the new BigInteger.
    Throws:
    IllegalArgumentException - {@code numBits} is negative.
    Also see:
    bitLength()
 BigInteger(int[] magnitude,
    int signum) 
 public BigInteger(int bitLength,
    int certainty,
    Random rnd) 
    Constructs a randomly generated positive BigInteger that is probably prime, with the specified bitLength.

    It is recommended that the probablePrime method be used in preference to this constructor unless there is a compelling need to specify a certainty.

    Parameters:
    bitLength - bitLength of the returned BigInteger.
    certainty - 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{@code certainty}). The execution time of this constructor is proportional to the value of this parameter.
    rnd - source of random bits used to select candidates to be tested for primality.
    Throws:
    ArithmeticException - {@code bitLength < 2}.
    Also see:
    bitLength()
Method from java.math.BigInteger Summary:
abs,   add,   addOne,   and,   andNot,   bitCount,   bitLength,   bitLengthForInt,   clearBit,   compareMagnitude,   compareTo,   divide,   divideAndRemainder,   doubleValue,   equals,   flipBit,   floatValue,   gcd,   getLowestSetBit,   hashCode,   intValue,   isProbablePrime,   javaIncrement,   longValue,   max,   min,   mod,   modInverse,   modPow,   mulAdd,   multiply,   multiply,   negate,   nextProbablePrime,   not,   or,   pow,   primeToCertainty,   primitiveLeftShift,   primitiveRightShift,   probablePrime,   remainder,   setBit,   shiftLeft,   shiftRight,   signum,   subtract,   testBit,   toByteArray,   toString,   toString,   valueOf,   xor
Methods from java.lang.Number:
byteValue,   doubleValue,   floatValue,   intValue,   longValue,   shortValue
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from java.math.BigInteger Detail:
 public BigInteger abs() 
    Returns a BigInteger whose value is the absolute value of this BigInteger.
 public BigInteger add(BigInteger val) 
    Returns a BigInteger whose value is {@code (this + val)}.
 static int addOne(int[] a,
    int offset,
    int mlen,
    int carry) 
    Add one word to the number a mlen words into a. Return the resulting carry.
 public BigInteger and(BigInteger val) 
    Returns a BigInteger whose value is {@code (this & val)}. (This method returns a negative BigInteger if and only if this and val are both negative.)
 public BigInteger andNot(BigInteger val) 
    Returns a BigInteger whose value is {@code (this & ~val)}. This method, which is equivalent to {@code and(val.not())}, is provided as a convenience for masking operations. (This method returns a negative BigInteger if and only if {@code this} is negative and {@code val} is positive.)
 public int bitCount() 
    Returns the number of bits in the two's complement representation of this BigInteger that differ from its sign bit. This method is useful when implementing bit-vector style sets atop BigIntegers.
 public int bitLength() 
    Returns the number of bits in the minimal two's-complement representation of this BigInteger, excluding a sign bit. For positive BigIntegers, this is equivalent to the number of bits in the ordinary binary representation. (Computes {@code (ceil(log2(this < 0 ? -this : this+1)))}.)
 static int bitLengthForInt(int n) 
    Package private method to return bit length for an integer.
 public BigInteger clearBit(int n) 
    Returns a BigInteger whose value is equivalent to this BigInteger with the designated bit cleared. (Computes {@code (this & ~(1<
 final int compareMagnitude(BigInteger val) 
    Compares the magnitude array of this BigInteger with the specified BigInteger's. This is the version of compareTo ignoring sign.
 public int compareTo(BigInteger val) 
    Compares this BigInteger with the specified BigInteger. This method is provided in preference to individual methods for each of the six boolean comparison operators ({@literal <}, ==, {@literal >}, {@literal >=}, !=, {@literal <=}). The suggested idiom for performing these comparisons is: {@code (x.compareTo(y)} <op> {@code 0)}, where <op> is one of the six comparison operators.
 public BigInteger divide(BigInteger val) 
    Returns a BigInteger whose value is {@code (this / val)}.
 public BigInteger[] divideAndRemainder(BigInteger val) 
    Returns an array of two BigIntegers containing {@code (this / val)} followed by {@code (this % val)}.
 public double doubleValue() 
    Converts this BigInteger to a {@code double}. This conversion is similar to the narrowing primitive conversion from {@code double} to {@code float} as defined in section 5.1.3 of The Java™ Language Specification: if this BigInteger has too great a magnitude to represent as a {@code double}, it will be converted to Double#NEGATIVE_INFINITY or Double#POSITIVE_INFINITY as appropriate. Note that even when the return value is finite, this conversion can lose information about the precision of the BigInteger value.
 public boolean equals(Object x) 
    Compares this BigInteger with the specified Object for equality.
 public BigInteger flipBit(int n) 
    Returns a BigInteger whose value is equivalent to this BigInteger with the designated bit flipped. (Computes {@code (this ^ (1<
 public float floatValue() 
    Converts this BigInteger to a {@code float}. This conversion is similar to the narrowing primitive conversion from {@code double} to {@code float} as defined in section 5.1.3 of The Java™ Language Specification: if this BigInteger has too great a magnitude to represent as a {@code float}, it will be converted to Float#NEGATIVE_INFINITY or Float#POSITIVE_INFINITY as appropriate. Note that even when the return value is finite, this conversion can lose information about the precision of the BigInteger value.
 public BigInteger gcd(BigInteger val) 
    Returns a BigInteger whose value is the greatest common divisor of {@code abs(this)} and {@code abs(val)}. Returns 0 if {@code this==0 && val==0}.
 public int getLowestSetBit() 
    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). Returns -1 if this BigInteger contains no one bits. (Computes {@code (this==0? -1 : log2(this & -this))}.)
 public int hashCode() 
    Returns the hash code for this BigInteger.
 public int intValue() 
    Converts this BigInteger to an {@code int}. This conversion is analogous to a narrowing primitive conversion from {@code long} to {@code int} as defined in section 5.1.3 of The Java™ Language Specification: if this BigInteger is too big to fit in an {@code int}, only the low-order 32 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigInteger value as well as return a result with the opposite sign.
 public boolean isProbablePrime(int certainty) 
    Returns {@code true} if this BigInteger is probably prime, {@code false} if it's definitely composite. If {@code certainty} is ≤ 0, {@code true} is returned.
 int[] javaIncrement(int[] val) 
 public long longValue() 
    Converts this BigInteger to a {@code long}. This conversion is analogous to a narrowing primitive conversion from {@code long} to {@code int} as defined in section 5.1.3 of The Java™ Language Specification: if this BigInteger is too big to fit in a {@code long}, only the low-order 64 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigInteger value as well as return a result with the opposite sign.
 public BigInteger max(BigInteger val) 
    Returns the maximum of this BigInteger and {@code val}.
 public BigInteger min(BigInteger val) 
    Returns the minimum of this BigInteger and {@code val}.
 public BigInteger mod(BigInteger m) 
    Returns a BigInteger whose value is {@code (this mod m}). This method differs from {@code remainder} in that it always returns a non-negative BigInteger.
 public BigInteger modInverse(BigInteger m) 
    Returns a BigInteger whose value is {@code (this}-1 {@code mod m)}.
 public BigInteger modPow(BigInteger exponent,
    BigInteger m) 
    Returns a BigInteger whose value is (thisexponent mod m). (Unlike {@code pow}, this method permits negative exponents.)
 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 multiply(BigInteger val) 
    Returns a BigInteger whose value is {@code (this * val)}.
 BigInteger multiply(long v) 
    Package private methods used by BigDecimal code to multiply a BigInteger with a long. Assumes v is not equal to INFLATED.
 public BigInteger negate() 
    Returns a BigInteger whose value is {@code (-this)}.
 public BigInteger nextProbablePrime() 
    Returns the first integer greater than this {@code BigInteger} that is probably prime. The probability that the number returned by this method is composite does not exceed 2-100. This method will never skip over a prime when searching: if it returns {@code p}, there is no prime {@code q} such that {@code this < q < p}.
 public BigInteger not() 
    Returns a BigInteger whose value is {@code (~this)}. (This method returns a negative value if and only if this BigInteger is non-negative.)
 public BigInteger or(BigInteger val) 
    Returns a BigInteger whose value is {@code (this | val)}. (This method returns a negative BigInteger if and only if either this or val is negative.)
 public BigInteger pow(int exponent) 
    Returns a BigInteger whose value is (thisexponent). Note that {@code exponent} is an integer rather than a BigInteger.
 boolean primeToCertainty(int certainty,
    Random random) 
    Returns {@code true} if this BigInteger is probably prime, {@code false} if it's definitely composite. This method assumes bitLength > 2.
 static  void primitiveLeftShift(int[] a,
    int len,
    int n) 
 static  void primitiveRightShift(int[] a,
    int len,
    int n) 
 public static BigInteger probablePrime(int bitLength,
    Random rnd) 
    Returns a positive BigInteger that is probably prime, with the specified bitLength. The probability that a BigInteger returned by this method is composite does not exceed 2-100.
 public BigInteger remainder(BigInteger val) 
    Returns a BigInteger whose value is {@code (this % val)}.
 public BigInteger setBit(int n) 
    Returns a BigInteger whose value is equivalent to this BigInteger with the designated bit set. (Computes {@code (this | (1<
 public BigInteger shiftLeft(int n) 
    Returns a BigInteger whose value is {@code (this << n)}. The shift distance, {@code n}, may be negative, in which case this method performs a right shift. (Computes floor(this * 2n).)
 public BigInteger shiftRight(int n) 
    Returns a BigInteger whose value is {@code (this >> n)}. Sign extension is performed. The shift distance, {@code n}, may be negative, in which case this method performs a left shift. (Computes floor(this / 2n).)
 public int signum() 
    Returns the signum function of this BigInteger.
 public BigInteger subtract(BigInteger val) 
    Returns a BigInteger whose value is {@code (this - val)}.
 public boolean testBit(int n) 
    Returns {@code true} if and only if the designated bit is set. (Computes {@code ((this & (1<
 public byte[] toByteArray() 
    Returns a byte array containing the two's-complement representation of this BigInteger. The byte array will be in big-endian byte-order: the most significant byte is in the zeroth element. The array will contain the minimum number of bytes required to represent this BigInteger, including at least one sign bit, which is {@code (ceil((this.bitLength() + 1)/8))}. (This representation is compatible with the (byte[]) constructor.)
 public String toString() 
    Returns the decimal String representation of this BigInteger. The digit-to-character mapping provided by {@code Character.forDigit} is used, and a minus sign is prepended if appropriate. (This representation is compatible with the (String) constructor, and allows for String concatenation with Java's + operator.)
 public String toString(int radix) 
    Returns the String representation of this BigInteger in the given radix. If the radix is outside the range from Character#MIN_RADIX to Character#MAX_RADIX inclusive, it will default to 10 (as is the case for {@code Integer.toString}). The digit-to-character mapping provided by {@code Character.forDigit} is used, and a minus sign is prepended if appropriate. (This representation is compatible with the int) (String, int) constructor.)
 public static BigInteger valueOf(long val) 
    Returns a BigInteger whose value is equal to that of the specified {@code long}. This "static factory method" is provided in preference to a ({@code long}) constructor because it allows for reuse of frequently used BigIntegers.
 public BigInteger xor(BigInteger val) 
    Returns a BigInteger whose value is {@code (this ^ val)}. (This method returns a negative BigInteger if and only if exactly one of this and val are negative.)