All Packages Class Hierarchy This Package Previous Next Index
Class java.math.BigInteger
java.lang.Object

+java.lang.Number

+java.math.BigInteger
 public class BigInteger
 extends Number
Immutable arbitraryprecision integers. All operations behave as if
BigIntegers were represented in two'scomplement 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,
singlebit 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 rightshift with a negative
shift distance results in a left shift, and viceversa. 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 nonnegative result, between 0 and (modulus  1), inclusive.
Singlebit operations operate on a single bit of the two'scomplement
representation of their operand. If necessary, the operand is sign
extended so that it contains the designated bit. None of the singlebit
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

BigInteger(byte[])
 Translates a byte array containing the two'scomplement representation
of a (signed) integer into a BigInteger.

BigInteger(int, byte[])
 Translates the signmagnitude representation of an integer into a
BigInteger.

BigInteger(int, int, Random)
 Returns a randomly selected BigInteger with the specified bitLength
that is probably prime.

BigInteger(int, Random)
 Returns a random number uniformly distributed on [0, 2**numBits  1]
(assuming a fair source of random bits is provided in rndSrc).

BigInteger(String)
 Translates a string containing an optional minus sign followed by a
sequence of one or more decimal digits into a BigInteger.

BigInteger(String, int)
 Translates a string containing an optional minus sign followed by a
sequence of one or more digits in the specified radix into a BigInteger.

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

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

and(BigInteger)
 Returns a BigInteger whose value is (this & val).

andNot(BigInteger)
 Returns a BigInteger whose value is (this & ~val).

bitCount()
 Returns the number of bits in the two's complement representation
of this number that differ from its sign bit.

bitLength()
 Returns the number of bits in the minimal two'scomplement
representation of this number, *excluding* a sign bit, i.e.,
(ceil(log2(this < 0 ? this : this + 1))).

clearBit(int)
 Returns a BigInteger whose value is equivalent to this number
with the designated bit cleared.

compareTo(BigInteger)
 Returns 1, 0 or 1 as this number is less than, equal to, or
greater than val.

divide(BigInteger)
 Returns a BigInteger whose value is (this / val).

divideAndRemainder(BigInteger)
 Returns an array of two BigIntegers.

doubleValue()
 Converts the number to a double.

equals(Object)
 Returns true iff x is a BigInteger whose value is equal to this number.

flipBit(int)
 Returns a BigInteger whose value is equivalent to this number
with the designated bit flipped.

floatValue()
 Converts this number to a float.

gcd(BigInteger)
 Returns a BigInteger whose value is the greatest common denominator
of abs(this) and abs(val).

getLowestSetBit()
 Returns the index of the rightmost (lowestorder) one bit in this
number (i.e., the number of zero bits to the right of the rightmost
one bit).

hashCode()
 Computes a hash code for this object.

intValue()
 Converts this number to an int.

isProbablePrime(int)
 Returns true if this BigInteger is probably prime, false if it's
definitely composite.

longValue()
 Converts this number to a long.

max(BigInteger)
 Returns the BigInteger whose value is the greater of this and val.

min(BigInteger)
 Returns the BigInteger whose value is the lesser of this and val.

mod(BigInteger)
 Returns a BigInteger whose value is this mod m.

modInverse(BigInteger)
 Returns modular multiplicative inverse of this, mod m.

modPow(BigInteger, BigInteger)
 Returns a BigInteger whose value is (this ** exponent) mod m.

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

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

not()
 Returns a BigInteger whose value is (~this).

or(BigInteger)
 Returns a BigInteger whose value is (this  val).

pow(int)
 Returns a BigInteger whose value is (this ** exponent).

remainder(BigInteger)
 Returns a BigInteger whose value is (this % val).

setBit(int)
 Returns a BigInteger whose value is equivalent to this number
with the designated bit set.

shiftLeft(int)
 Returns a BigInteger whose value is (this << n).

shiftRight(int)
 Returns a BigInteger whose value is (this >> n).

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

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

testBit(int)
 Returns true iff the designated bit is set.

toByteArray()
 Returns the two'scomplement representation of this number.

toString()
 Returns the string representation of this number, radix 10.

toString(int)
 Returns the string representation of this number in the given radix.

valueOf(long)
 Returns a BigInteger with the specified value.

xor(BigInteger)
 Returns a BigInteger whose value is (this ^ val).
BigInteger
public BigInteger(byte val[]) throws NumberFormatException
 Translates a byte array containing the two'scomplement representation
of a (signed) integer into a BigInteger. The input array is assumed to
be bigendian (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 signmagnitude 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 bigendian 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 charactertodigit 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
charactertodigit 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 nonnegative 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.
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 noninteger 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 nonnegative.)
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<
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<
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<
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<
getLowestSetBit
public int getLowestSetBit()
 Returns the index of the rightmost (lowestorder) 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'scomplement
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 bitvector 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) 0), where is one of the
six comparison operators.
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 digittocharacter 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
digittocharacter 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'scomplement representation of this number. The array
is bigendian (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 doubletofloat
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 doubletofloat
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
All Packages Class Hierarchy This Package Previous Next Index
Submit a bug or feature  Version 1.1.8 of Java Platform API Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 19951999 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.