Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Class java.math.BigInteger

java.lang.Object
    |
    +----java.lang.Number
            |
            +----java.math.BigInteger

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

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

Single-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 number with a different sign from the 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.

See Also:
BigDecimal

Constructor Summary
 BigInteger(byte[] val)
Translates a byte array containing the two's-complement representation of a (signed) integer into a BigInteger.
 BigInteger(int signum, byte[] magnitude)
Translates the sign-magnitude representation of an integer into a BigInteger.
 BigInteger(String val, int radix)
Translates a string containing an optional minus sign followed by a sequence of one or more digits in the specified radix into a BigInteger.
 BigInteger(String val)
Translates a string containing an optional minus sign followed by a sequence of one or more decimal digits into a BigInteger.
 BigInteger(int numBits, Random rndSrc)
Returns a random number uniformly distributed on [0, 2**numBits - 1] (assuming a fair source of random bits is provided in rndSrc).
 BigInteger(int bitLength, int certainty, Random rnd)
Returns a randomly selected BigInteger with the specified bitLength that is probably prime.
 

Method Summary
BigInteger  abs()
Returns a BigInteger whose value is the absolute value of this number.
BigInteger  add(BigInteger val)
Returns a BigInteger whose value is (this + val).
BigInteger  and(BigInteger val)
Returns a BigInteger whose value is (this & val).
BigInteger  andNot(BigInteger val)
Returns a BigInteger whose value is (this & ~val).
int  bitCount()
Returns the number of bits in the two's complement representation of this number that differ from its sign bit.
int  bitLength()
Returns the number of bits in the minimal two's-complement representation of this number, *excluding* a sign bit, i.e., (ceil(log2(this < 0 ? -this : this + 1))).
BigInteger  clearBit(int n)
Returns a BigInteger whose value is equivalent to this number with the designated bit cleared.
int  compareTo(BigInteger val)
Returns -1, 0 or 1 as this number is less than, equal to, or greater than val.
int  compareTo(Object o)
Compares this BigInteger to another Object.
BigInteger  divide(BigInteger val)
Returns a BigInteger whose value is (this / val).
BigInteger[]  divideAndRemainder(BigInteger val)
Returns an array of two BigIntegers.
double  doubleValue()
Converts the number to a double.
boolean  equals(Object x)
Returns true iff x is a BigInteger whose value is equal to this number.
BigInteger  flipBit(int n)
Returns a BigInteger whose value is equivalent to this number with the designated bit flipped.
float  floatValue()
Converts this number to a float.
BigInteger  gcd(BigInteger val)
Returns a BigInteger whose value is the greatest common denominator of abs(this) and abs(val).
int  getLowestSetBit()
Returns the index of the rightmost (lowest-order) one bit in this number (i.e., the number of zero bits to the right of the rightmost one bit).
int  hashCode()
Computes a hash code for this object.
int  intValue()
Converts this number to an int.
boolean  isProbablePrime(int certainty)
Returns true if this BigInteger is probably prime, false if it's definitely composite.
long  longValue()
Converts this number to a long.
BigInteger  max(BigInteger val)
Returns the BigInteger whose value is the greater of this and val.
BigInteger  min(BigInteger val)
Returns the BigInteger whose value is the lesser of this and val.
BigInteger  mod(BigInteger m)
Returns a BigInteger whose value is this mod m.
BigInteger  modInverse(BigInteger m)
Returns modular multiplicative inverse of this, mod m.
BigInteger  modPow(BigInteger exponent, BigInteger m)
Returns a BigInteger whose value is (this ** exponent) mod m.
BigInteger  multiply(BigInteger val)
Returns a BigInteger whose value is (this * val).
BigInteger  negate()
Returns a BigInteger whose value is (-1 * this).
BigInteger  not()
Returns a BigInteger whose value is (~this).
BigInteger  or(BigInteger val)
Returns a BigInteger whose value is (this | val).
BigInteger  pow(int exponent)
Returns a BigInteger whose value is (this ** exponent).
BigInteger  remainder(BigInteger val)
Returns a BigInteger whose value is (this % val).
BigInteger  setBit(int n)
Returns a BigInteger whose value is equivalent to this number with the designated bit 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 signum function of this number (i.e., -1, 0 or 1 as the value of this number is negative, zero or positive).
BigInteger  subtract(BigInteger val)
Returns a BigInteger whose value is (this - val).
boolean  testBit(int n)
Returns true iff the designated bit is set.
byte[]  toByteArray()
Returns the two's-complement representation of this number.
String  toString(int radix)
Returns the string representation of this number in the given radix.
String  toString()
Returns the string representation of this number, radix 10.
static BigInteger  valueOf(long val)
Returns a BigInteger with the specified value.
BigInteger  xor(BigInteger val)
Returns a BigInteger whose value is (this ^ val).
 
Methods inherited from class java.lang.Number
 byteValue, doubleValue, floatValue, intValue, longValue, shortValue
 
Methods inherited from class java.lang.Object
 clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BigInteger

public BigInteger(byte[] val) throws NumberFormatException
Translates a byte array containing the two's-complement representation of a (signed) integer into a BigInteger. The input array is assumed to be big-endian (i.e., the most significant byte is in the [0] position). (The most significant bit of the most significant byte is the sign bit.) The array must contain at least one byte or a NumberFormatException will be thrown.

BigInteger

public BigInteger(int signum,
                  byte[] magnitude) throws NumberFormatException
Translates the sign-magnitude representation of an integer into a BigInteger. The sign is represented as an integer signum value (-1 for negative, 0 for zero, 1 for positive). The magnitude is represented as a big-endian byte array (i.e., the most significant byte is in the [0] position). An invalid signum value or a 0 signum value coupled with a nonzero magnitude will result in a NumberFormatException. A zero length magnitude array is permissible, and will result in in a value of 0 (irrespective of the given signum value).

BigInteger

public BigInteger(String val,
                  int radix) throws NumberFormatException
Translates a string containing an optional minus sign followed by a sequence of one or more digits in the specified radix into a BigInteger. The character-to-digit mapping is provided by Character.digit. Any extraneous characters (including whitespace), or a radix outside the range from Character.MIN_RADIX(2) to Character.MAX_RADIX(36), inclusive, will result in a NumberFormatException.

BigInteger

public BigInteger(String val) throws NumberFormatException
Translates a string containing an optional minus sign followed by a sequence of one or more decimal digits into a BigInteger. The character-to-digit mapping is provided by Character.digit. Any extraneous characters (including whitespace) will result in a NumberFormatException.

BigInteger

public BigInteger(int numBits,
                  Random rndSrc) throws IllegalArgumentException
Returns a random number uniformly distributed on [0, 2**numBits - 1] (assuming a fair source of random bits is provided in rndSrc). Note that this constructor always returns a non-negative BigInteger. Throws an IllegalArgumentException if numBits < 0.

BigInteger

public BigInteger(int bitLength,
                  int certainty,
                  Random rnd)
Returns a randomly selected BigInteger with the specified bitLength that is probably prime. The certainty parameter is a measure of the uncertainty that the caller is willing to tolerate: the probability that the number is prime will exceed 1 - 1/2**certainty. The execution time is proportional to the value of the certainty parameter. The given random number generator is used to select candidates to be tested for primality. Throws an ArithmeticException if bitLength < 2.
Method Detail

valueOf

public static BigInteger valueOf(long val)
Returns a BigInteger with the specified value. This factory is provided in preference to a (long) constructor because it allows for reuse of frequently used BigIntegers (like 0 and 1), obviating the need for exported constants.

add

public BigInteger add(BigInteger val) throws ArithmeticException
Returns a BigInteger whose value is (this + val).

subtract

public BigInteger subtract(BigInteger val)
Returns a BigInteger whose value is (this - val).

multiply

public BigInteger multiply(BigInteger val)
Returns a BigInteger whose value is (this * val).

divide

public BigInteger divide(BigInteger val) throws ArithmeticException
Returns a BigInteger whose value is (this / val). Throws an ArithmeticException if val == 0.

remainder

public BigInteger remainder(BigInteger val) throws ArithmeticException
Returns a BigInteger whose value is (this % val). Throws an ArithmeticException if val == 0.

divideAndRemainder

public BigInteger[] divideAndRemainder(BigInteger val) throws ArithmeticException
Returns an array of two BigIntegers. The first ([0]) element of the return value is the quotient (this / val), and the second ([1]) element is the remainder (this % val). Throws an ArithmeticException if val == 0.

pow

public BigInteger pow(int exponent) throws ArithmeticException
Returns a BigInteger whose value is (this ** exponent). Throws an ArithmeticException if exponent < 0 (as the operation would yield a non-integer value). Note that exponent is an integer rather than a BigInteger.

gcd

public BigInteger gcd(BigInteger val)
Returns a BigInteger whose value is the greatest common denominator of abs(this) and abs(val). Returns 0 if this == 0 && val == 0.

abs

public BigInteger abs()
Returns a BigInteger whose value is the absolute value of this number.

negate

public BigInteger negate()
Returns a BigInteger whose value is (-1 * this).

signum

public int signum()
Returns the signum function of this number (i.e., -1, 0 or 1 as the value of this number is negative, zero or positive).

mod

public BigInteger mod(BigInteger m)
Returns a BigInteger whose value is this mod m. Throws an ArithmeticException if m <= 0.

modPow

public BigInteger modPow(BigInteger exponent,
                         BigInteger m)
Returns a BigInteger whose value is (this ** exponent) mod m. (If exponent == 1, the returned value is (this mod m). If exponent < 0, the returned value is the modular multiplicative inverse of (this ** -exponent).) Throws an ArithmeticException if m <= 0.

modInverse

public BigInteger modInverse(BigInteger m) throws ArithmeticException
Returns modular multiplicative inverse of this, mod m. Throws an ArithmeticException if m <= 0 or this has no multiplicative inverse mod m (i.e., gcd(this, m) != 1).

shiftLeft

public BigInteger shiftLeft(int n)
Returns a BigInteger whose value is (this << n). (Computes floor(this * 2**n).)

shiftRight

public BigInteger shiftRight(int n)
Returns a BigInteger whose value is (this >> n). Sign extension is performed. (Computes floor(this / 2**n).)

and

public BigInteger and(BigInteger val)
Returns a BigInteger whose value is (this & val). (This method returns a negative number iff this and val are both negative.)

or

public BigInteger or(BigInteger val)
Returns a BigInteger whose value is (this | val). (This method returns a negative number iff either this or val is negative.)

xor

public BigInteger xor(BigInteger val)
Returns a BigInteger whose value is (this ^ val). (This method returns a negative number iff exactly one of this and val are negative.)

not

public BigInteger not()
Returns a BigInteger whose value is (~this). (This method returns a negative value iff this number is non-negative.)

andNot

public BigInteger andNot(BigInteger val)
Returns a BigInteger whose value is (this & ~val). This method, which is equivalent to and(val.not()), is provided as a convenience for masking operations. (This method returns a negative number iff this is negative and val is positive.)

testBit

public boolean testBit(int n) throws ArithmeticException
Returns true iff the designated bit is set. (Computes ((this & (1<<n)) != 0).) Throws an ArithmeticException if n < 0.

setBit

public BigInteger setBit(int n) throws ArithmeticException
Returns a BigInteger whose value is equivalent to this number with the designated bit set. (Computes (this | (1<<n)).) Throws an ArithmeticException if n < 0.

clearBit

public BigInteger clearBit(int n) throws ArithmeticException
Returns a BigInteger whose value is equivalent to this number with the designated bit cleared. (Computes (this & ~(1<<n)).) Throws an ArithmeticException if n < 0.

flipBit

public BigInteger flipBit(int n) throws ArithmeticException
Returns a BigInteger whose value is equivalent to this number with the designated bit flipped. (Computes (this ^ (1<<n)).) Throws an ArithmeticException if n < 0.

getLowestSetBit

public int getLowestSetBit()
Returns the index of the rightmost (lowest-order) one bit in this number (i.e., the number of zero bits to the right of the rightmost one bit). Returns -1 if this number contains no one bits. (Computes (this==0? -1 : log2(this & -this)).)

bitLength

public int bitLength()
Returns the number of bits in the minimal two's-complement representation of this number, *excluding* a sign bit, i.e., (ceil(log2(this < 0 ? -this : this + 1))). (For positive numbers, this is equivalent to the number of bits in the ordinary binary representation.)

bitCount

public int bitCount()
Returns the number of bits in the two's complement representation of this number that differ from its sign bit. This method is useful when implementing bit-vector style sets atop BigIntegers.

isProbablePrime

public boolean isProbablePrime(int certainty)
Returns true if this BigInteger is probably prime, false if it's definitely composite. The certainty parameter is a measure of the uncertainty that the caller is willing to tolerate: the method returns true if the probability that this number is is prime exceeds 1 - 1/2**certainty. The execution time is proportional to the value of the certainty parameter.

compareTo

public int compareTo(BigInteger val)
Returns -1, 0 or 1 as this number is less than, equal to, or greater than val. This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=). The suggested idiom for performing these comparisons is: (x.compareTo(y) <op> 0), where <op> is one of the six comparison operators.
Implements:
compareTo in interface Comparable

compareTo

public int compareTo(Object o)
Compares this BigInteger to another Object. If the Object is a BigInteger, this function behaves like compareTo(BigInteger). Otherwise, it throws a ClassCastException (as BigIntegers are comparable only to other BigIntegers).
Implements:
compareTo in interface Comparable
Parameters:
o - the Object to be compared.
Returns:
the value 0 if the argument is a BigInteger numerically equal to this BigInteger; a value less than 0 if the argument is a BigInteger numerically greater than this BigInteger; and a value greater than 0 if the argument is a BigInteger numerically less than this BigInteger.
Throws:
ClassCastException - if the argument is not a BigInteger.
See Also:
Comparable

equals

public boolean equals(Object x)
Returns true iff x is a BigInteger whose value is equal to this number. This method is provided so that BigIntegers can be used as hash keys.
Overrides:
equals in class Object

min

public BigInteger min(BigInteger val)
Returns the BigInteger whose value is the lesser of this and val. If the values are equal, either may be returned.

max

public BigInteger max(BigInteger val)
Returns the BigInteger whose value is the greater of this and val. If the values are equal, either may be returned.

hashCode

public int hashCode()
Computes a hash code for this object.
Overrides:
hashCode in class Object

toString

public String toString(int radix)
Returns the string representation of this number in the given radix. If the radix is outside the range from Character.MIN_RADIX(2) to Character.MAX_RADIX(36) inclusive, it will default to 10 (as is the case for Integer.toString). The digit-to-character mapping provided by Character.forDigit is used, and a minus sign is prepended if appropriate. (This representation is compatible with the (String, int) constructor.)

toString

public String toString()
Returns the string representation of this number, radix 10. The digit-to-character mapping provided by 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.)
Overrides:
toString in class Object

toByteArray

public byte[] toByteArray()
Returns the two's-complement representation of this number. The array is big-endian (i.e., the most significant byte is in the [0] position). The array contains the minimum number of bytes required to represent the number (ceil((this.bitLength() + 1)/8)). (This representation is compatible with the (byte[]) constructor.)

intValue

public int intValue()
Converts this number to an int. Standard narrowing primitive conversion as per The Java Language Specification.
Overrides:
intValue in class Number

longValue

public long longValue()
Converts this number to a long. Standard narrowing primitive conversion as per The Java Language Specification.
Overrides:
longValue in class Number

floatValue

public float floatValue()
Converts this number to a float. Similar to the double-to-float narrowing primitive conversion defined in The Java Language Specification: if the number has too great a magnitude to represent as a float, it will be converted to infinity or negative infinity, as appropriate.
Overrides:
floatValue in class Number

doubleValue

public double doubleValue()
Converts the number to a double. Similar to the double-to-float narrowing primitive conversion defined in The Java Language Specification: if the number has too great a magnitude to represent as a double, it will be converted to infinity or negative infinity, as appropriate.
Overrides:
doubleValue in class Number

Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Submit a bug or feature
Submit comments/suggestions about new javadoc look.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.