java.math
Class BigInteger

java.lang.Object
  extended by java.lang.Number
      extended by java.math.BigInteger
All Implemented Interfaces:
Serializable, Comparable<BigInteger>

public class BigInteger
extends Number
implements Comparable<BigInteger>

Written using on-line Java Platform 1.2 API Specification, as well as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998) and "Applied Cryptography, Second Edition" by Bruce Schneier (Wiley, 1996). Based primarily on IntNum.java BitOps.java by Per Bothner (per@bothner.com) (found in Kawa 1.6.62).

See Also:
Serialized Form

Field Summary
static BigInteger ONE
          The constant one as a BigInteger.
static BigInteger TEN
          The constant ten as a BigInteger.
static BigInteger ZERO
          The constant zero as a BigInteger.
 
Constructor Summary
BigInteger(byte[] val)
           
BigInteger(int signum, byte[] magnitude)
           
BigInteger(int bitLength, int certainty, Random rnd)
           
BigInteger(int numBits, Random rnd)
           
BigInteger(String val)
           
BigInteger(String s, int radix)
           
 
Method Summary
 BigInteger abs()
           
 BigInteger add(BigInteger val)
           
 BigInteger and(BigInteger y)
          Return the logical (bit-wise) "and" of two BigIntegers.
 BigInteger andNot(BigInteger val)
           
 int bitCount()
          Count one bits in a BigInteger.
 int bitLength()
          Calculates ceiling(log2(this < 0 ?
 BigInteger clearBit(int n)
           
 int compareTo(BigInteger val)
          Compares this object with another, and returns a numerical result based on the comparison.
 BigInteger divide(BigInteger val)
           
 BigInteger[] divideAndRemainder(BigInteger val)
           
 double doubleValue()
          Return the value of this Number as a float.
 boolean equals(Object obj)
          Determine whether this Object is semantically equal to another Object.
 BigInteger flipBit(int n)
           
 float floatValue()
          Return the value of this Number as a float.
 BigInteger gcd(BigInteger y)
           
 int getLowestSetBit()
           
 int hashCode()
          Get a value that represents this Object, as uniquely as possible within the confines of an int.
 int intValue()
          Return the value of this Number as an int.
 boolean isProbablePrime(int certainty)
          Returns true if this BigInteger is probably prime, false if it's definitely composite.
 long longValue()
          Return the value of this Number as a long.
 BigInteger max(BigInteger val)
           
 BigInteger min(BigInteger val)
           
 BigInteger mod(BigInteger m)
           
 BigInteger modInverse(BigInteger y)
           
 BigInteger modPow(BigInteger exponent, BigInteger m)
           
 BigInteger multiply(BigInteger y)
           
 BigInteger negate()
           
 BigInteger not()
          Return the logical (bit-wise) negation of a BigInteger.
 BigInteger or(BigInteger y)
          Return the logical (bit-wise) "(inclusive) or" of two BigIntegers.
 BigInteger pow(int exponent)
          Calculate the integral power of a BigInteger.
static BigInteger probablePrime(int bitLength, Random rnd)
          Return a BigInteger that is bitLength bits long with a probability < 2^-100 of being composite.
 BigInteger remainder(BigInteger val)
           
 BigInteger setBit(int n)
           
 BigInteger shiftLeft(int n)
           
 BigInteger shiftRight(int n)
           
 int signum()
           
 BigInteger subtract(BigInteger val)
           
 boolean testBit(int n)
           
 byte[] toByteArray()
           
 String toString()
          Convert this Object to a human-readable String.
 String toString(int radix)
           
static BigInteger valueOf(long val)
          Return a (possibly-shared) BigInteger with a given long value.
 BigInteger xor(BigInteger y)
          Return the logical (bit-wise) "exclusive or" of two BigIntegers.
 
Methods inherited from class java.lang.Number
byteValue, shortValue
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ZERO

public static final BigInteger ZERO
The constant zero as a BigInteger.

Since:
1.2

ONE

public static final BigInteger ONE
The constant one as a BigInteger.

Since:
1.2

TEN

public static final BigInteger TEN
The constant ten as a BigInteger.

Since:
1.5
Constructor Detail

BigInteger

public BigInteger(String s,
                  int radix)

BigInteger

public BigInteger(String val)

BigInteger

public BigInteger(byte[] val)

BigInteger

public BigInteger(int signum,
                  byte[] magnitude)

BigInteger

public BigInteger(int numBits,
                  Random rnd)

BigInteger

public BigInteger(int bitLength,
                  int certainty,
                  Random rnd)
Method Detail

probablePrime

public static BigInteger probablePrime(int bitLength,
                                       Random rnd)
Return a BigInteger that is bitLength bits long with a probability < 2^-100 of being composite.

Parameters:
bitLength - length in bits of resulting number
rnd - random number generator to use
Throws:
ArithmeticException - if bitLength < 2
Since:
1.4

valueOf

public static BigInteger valueOf(long val)
Return a (possibly-shared) BigInteger with a given long value.


signum

public int signum()

compareTo

public int compareTo(BigInteger val)
Description copied from interface: Comparable
Compares this object with another, and returns a numerical result based on the comparison. If the result is negative, this object sorts less than the other; if 0, the two are equal, and if positive, this object sorts greater than the other. To translate this into boolean, simply perform o1.compareTo(o2) <op> 0, where op is one of <, <=, =, !=, >, or >=.

You must make sure that the comparison is mutual, ie. sgn(x.compareTo(y)) == -sgn(y.compareTo(x)) (where sgn() is defined as -1, 0, or 1 based on the sign). This includes throwing an exception in either direction if the two are not comparable; hence, compareTo(null) should always throw an Exception.

You should also ensure transitivity, in two forms: x.compareTo(y) > 0 && y.compareTo(z) > 0 implies x.compareTo(z) > 0; and x.compareTo(y) == 0 implies x.compareTo(z) == y.compareTo(z).

Specified by:
compareTo in interface Comparable<BigInteger>
Parameters:
val - the object to be compared
Returns:
an integer describing the comparison
Since:
1.2

min

public BigInteger min(BigInteger val)

max

public BigInteger max(BigInteger val)

add

public BigInteger add(BigInteger val)

subtract

public BigInteger subtract(BigInteger val)

multiply

public BigInteger multiply(BigInteger y)

divide

public BigInteger divide(BigInteger val)

remainder

public BigInteger remainder(BigInteger val)

divideAndRemainder

public BigInteger[] divideAndRemainder(BigInteger val)

mod

public BigInteger mod(BigInteger m)

pow

public BigInteger pow(int exponent)
Calculate the integral power of a BigInteger.

Parameters:
exponent - the exponent (must be non-negative)

modInverse

public BigInteger modInverse(BigInteger y)

modPow

public BigInteger modPow(BigInteger exponent,
                         BigInteger m)

gcd

public BigInteger gcd(BigInteger y)

isProbablePrime

public boolean isProbablePrime(int certainty)

Returns true if this BigInteger is probably prime, false if it's definitely composite. If certainty is <= 0, true is returned.

Parameters:
certainty - a measure of the uncertainty that the caller is willing to tolerate: if the call returns 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:
true if this BigInteger is probably prime, false if it's definitely composite.

shiftLeft

public BigInteger shiftLeft(int n)

shiftRight

public BigInteger shiftRight(int n)

toString

public String toString()
Description copied from class: Object
Convert this Object to a human-readable String. There are no limits placed on how long this String should be or what it should contain. We suggest you make it as intuitive as possible to be able to place it into System.out.println() and such.

It is typical, but not required, to ensure that this method never completes abruptly with a RuntimeException.

This method will be called when performing string concatenation with this object. If the result is null, string concatenation will instead use "null".

The default implementation returns getClass().getName() + "@" + Integer.toHexString(hashCode()).

Overrides:
toString in class Object
Returns:
the String representing this Object, which may be null
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

toString

public String toString(int radix)

intValue

public int intValue()
Description copied from class: Number
Return the value of this Number as an int.

Specified by:
intValue in class Number
Returns:
the int value

longValue

public long longValue()
Description copied from class: Number
Return the value of this Number as a long.

Specified by:
longValue in class Number
Returns:
the long value

hashCode

public int hashCode()
Description copied from class: Object
Get a value that represents this Object, as uniquely as possible within the confines of an int.

There are some requirements on this method which subclasses must follow:

Notice that since hashCode is used in Hashtable and other hashing classes, a poor implementation will degrade the performance of hashing (so don't blindly implement it as returning a constant!). Also, if calculating the hash is time-consuming, a class may consider caching the results.

The default implementation returns System.identityHashCode(this)

Overrides:
hashCode in class Object
Returns:
the hash code for this Object
See Also:
Object.equals(Object), System.identityHashCode(Object)

equals

public boolean equals(Object obj)
Description copied from class: Object
Determine whether this Object is semantically equal to another Object.

There are some fairly strict requirements on this method which subclasses must follow:

This is typically overridden to throw a ClassCastException if the argument is not comparable to the class performing the comparison, but that is not a requirement. It is legal for a.equals(b) to be true even though a.getClass() != b.getClass(). Also, it is typical to never cause a NullPointerException.

In general, the Collections API (java.util) use the equals method rather than the == operator to compare objects. However, IdentityHashMap is an exception to this rule, for its own good reasons.

The default implementation returns this == o.

Overrides:
equals in class Object
Parameters:
obj - the Object to compare to
Returns:
whether this Object is semantically equal to another
See Also:
Object.hashCode()

doubleValue

public double doubleValue()
Description copied from class: Number
Return the value of this Number as a float.

Specified by:
doubleValue in class Number
Returns:
the double value

floatValue

public float floatValue()
Description copied from class: Number
Return the value of this Number as a float.

Specified by:
floatValue in class Number
Returns:
the float value

abs

public BigInteger abs()

negate

public BigInteger negate()

bitLength

public int bitLength()
Calculates ceiling(log2(this < 0 ? -this : this+1)) See Common Lisp: the Language, 2nd ed, p. 361.


toByteArray

public byte[] toByteArray()

and

public BigInteger and(BigInteger y)
Return the logical (bit-wise) "and" of two BigIntegers.


or

public BigInteger or(BigInteger y)
Return the logical (bit-wise) "(inclusive) or" of two BigIntegers.


xor

public BigInteger xor(BigInteger y)
Return the logical (bit-wise) "exclusive or" of two BigIntegers.


not

public BigInteger not()
Return the logical (bit-wise) negation of a BigInteger.


andNot

public BigInteger andNot(BigInteger val)

clearBit

public BigInteger clearBit(int n)

setBit

public BigInteger setBit(int n)

testBit

public boolean testBit(int n)

flipBit

public BigInteger flipBit(int n)

getLowestSetBit

public int getLowestSetBit()

bitCount

public int bitCount()
Count one bits in a BigInteger. If argument is negative, count zero bits instead.