java.math
Class BigInteger

java.lang.Object
  java.lang.Number
      java.math.BigInteger

All Implemented Interfaces:

Serializable, Comparable

public class BigInteger
extends Number
implements Comparable

BigInteger objects represent arbitrary precision decimal integers. They contain values that cannot be changed. Thus, most operations on the BigInteger objects yield new instances of BigInteger.

See Also:

Serialized Form

Field Summary

static BigInteger	ONE Constant: 1 as represented by a BigInteger.
static BigInteger	TEN Constant: 10 as represented by a BigInteger.
static BigInteger	ZERO Constant: 0 as represented by a BigInteger.

Constructor Summary

BigInteger(byte[] bytes)
Constructs a new instance of this class given an array containing bytes representing the bit pattern for the answer.

BigInteger(int sign, byte[] bytes)
Constructs a new instance of this class given an array containing bytes representing the bit pattern for the answer, and a sign flag.

BigInteger(int bitLength, int certainty, Random rnd)
Constructs a new instance of this class of the specified length, whose content is produced by aquiring random bits from the specified random number generator.

BigInteger(int bitLength, Random rnd)
Constructs a new instance of this class of the specified length, whose content is produced by aquiring random bits from the specified random number generator.

BigInteger(String val)
Constructs a new instance of this class given a string containing a representation of a decimal number.

BigInteger(String val, int radix)
Constructs a new instance of this class given a string containing digits in the specified radix.

Method Summary

BigInteger	abs() Answers the absolute value of the receiver
BigInteger	add(BigInteger val) Answers the sum of the receiver and a BigInteger
BigInteger	and(BigInteger val) Answers the bitwise AND of the receiver and the argument.
BigInteger	andNot(BigInteger val) Answers the bitwise NAND of the receiver and the argument.
int	bitCount() Answers the number of set bits in the receiver.
int	bitLength() Answers the length in bits of the receiver.
BigInteger	clearBit(int n) Unsets the specified bit in the receiver.
int	compareTo(BigInteger val) Answers an integer indicating the relative positions of the receiver and the argument in the natural order of elements of the receiver's class.
int	compareTo(Object o) Answers an integer indicating the relative positions of the receiver and the argument in the natural order of elements of the receiver's class.
BigInteger	divide(BigInteger val) Answers the quotient of the receiver and a BigInteger.
BigInteger[]	divideAndRemainder(BigInteger val) Answers the quotient and remainder of the receiver divided by a BigInteger.
double	doubleValue() Answers the double value which the receiver represents
boolean	equals(Object o) Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
BigInteger	flipBit(int n) Toggles the specified bit in the receiver.
float	floatValue() Answers the float value which the receiver represents
BigInteger	gcd(BigInteger val) Answers the greatest common divisor of abs(this) and abs(val), zero if this==val==0
int	getLowestSetBit() Answers the index of the lowest set bit in the receiver, or -1 if no bits are set.
int	hashCode() Answers an integer hash code for the receiver.
int	intValue() Answers the int value which the receiver represents
boolean	isProbablePrime(int certainty) Answers true if the receiver is probably prime to the given degree of certainty.
long	longValue() Answers the long value which the receiver represents
BigInteger	max(BigInteger val) Answers the most positive of either the receiver or the argument.
BigInteger	min(BigInteger val) Answers the most negative of either the receiver or the argument.
BigInteger	mod(BigInteger val) Answers the remainder of the receiver modulo a BigInteger (a positive value).
BigInteger	modInverse(BigInteger modulo) Answers the inverse of the receiver modulo a BigInteger, if it exists.
BigInteger	modPow(BigInteger exponent, BigInteger modulo) Answers the receiver to the power of exponent modulo a BigInteger
BigInteger	multiply(BigInteger val) Answers the product of the receiver and a BigInteger.
BigInteger	negate() Answers the negative of the receiver
BigInteger	not() Answers the bitwise negation of the receiver.
BigInteger	or(BigInteger val) Answers the bitwise OR of the receiver and the argument.
BigInteger	pow(int exponent) Answers the receiver to the power of exponent.
BigInteger	remainder(BigInteger val) Answers the remainder of the receiver divided by a BigInteger
BigInteger	setBit(int n) Sets the specified bit in the receiver.
BigInteger	shiftLeft(int shiftval) Answers a BigInteger with the value of the reciever multiplied by 2^shiftval.
BigInteger	shiftRight(int shiftval) Answers a BigInteger with the value of the reciever divided by 2^shiftval.
int	signum() Answers the sign of the receiver
BigInteger	subtract(BigInteger val) Answers the difference of the receiver and a BigInteger.
boolean	testBit(int n) Answers true if the specified bit is set in the receiver.
byte[]	toByteArray() Answers an array of bytes containing the value of the receiver in the same format used by the matching constructor.
String	toString() Answers a string containing a concise, human-readable description of the receiver.
String	toString(int radix) Answers a string containing a concise, human-readable description of the receiver as a sequence of digits in the specified radix.
static BigInteger	valueOf(long val) Answers a BigInteger with the same value as val
BigInteger	xor(BigInteger val) Answers the bitwise XOR of the receiver and the argument.

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

Constant: 0 as represented by a BigInteger.

ONE

public static final BigInteger ONE

Constant: 1 as represented by a BigInteger.

TEN

public static final BigInteger TEN

Constant: 10 as represented by a BigInteger.

Constructor Detail

BigInteger

public BigInteger(int bitLength,
                  Random rnd)

Constructs a new instance of this class of the specified length, whose content is produced by aquiring random bits from the specified random number generator.

Parameters:

bitLength - int the number of bits to have in the result.

rnd - Random the generator to produce the bits.

BigInteger

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

Constructs a new instance of this class of the specified length, whose content is produced by aquiring random bits from the specified random number generator. The result is guaranteed to be prime up to the given degree of certainty.

Parameters:

bitLength - int the number of bits to have in the result.

certainty - int the degree of certainty required that the result is prime.

rnd - Random the generator to produce the bits.

BigInteger

public BigInteger(byte[] bytes)

Constructs a new instance of this class given an array containing bytes representing the bit pattern for the answer.

Parameters:

bytes - byte[] the bits of the value of the new instance.

BigInteger

public BigInteger(int sign,
                  byte[] bytes)

Constructs a new instance of this class given an array containing bytes representing the bit pattern for the answer, and a sign flag.

Parameters:

sign - int the sign of the result.

bytes - byte[] the bits of the value of the new instance.

BigInteger

public BigInteger(String val)

Constructs a new instance of this class given a string containing a representation of a decimal number.

Parameters:

val - String the decimal digits of the answer.

BigInteger

public BigInteger(String val,
                  int radix)

Constructs a new instance of this class given a string containing digits in the specified radix.

Parameters:

val - String the digits of the answer.

radix - int the radix to use for conversion.

Method Detail

toByteArray

public byte[] toByteArray()

Answers an array of bytes containing the value of the receiver in the same format used by the matching constructor.

Returns:

byte[] the bits of the value of the receiver.

isProbablePrime

public boolean isProbablePrime(int certainty)

Answers true if the receiver is probably prime to the given degree of certainty.

Parameters:

certainty - int the degree of certainty required.

Returns:

boolean true if the receiver is prime and false otherwise.

equals

public boolean equals(Object o)

Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison. In this case the argument must also be a BigInteger which represents the same number

Overrides:

equals in class Object

Parameters:

o - Object the object to compare with this object.

Returns:

boolean true if the object is the same as this object false if it is different from this object.

See Also:

hashCode()

compareTo

public int compareTo(BigInteger val)

Answers an integer indicating the relative positions of the receiver and the argument in the natural order of elements of the receiver's class.

Parameters:

val - BigInteger an object to compare the receiver to

Returns:

int which should be <0 if the receiver should sort before the argument, 0 if the receiver should sort in the same position as the argument, and >0 if the receiver should sort after the argument.

Throws:

ClassCastException - if the argument can not be converted into something comparable with the receiver.

compareTo

public int compareTo(Object o)

Answers an integer indicating the relative positions of the receiver and the argument in the natural order of elements of the receiver's class.

Specified by:

compareTo in interface Comparable

Parameters:

o - Object an object to compare the receiver to

Returns:

int which should be <0 if the receiver should sort before the argument, 0 if the receiver should sort in the same position as the argument, and >0 if the receiver should sort after the argument.

Throws:

ClassCastException - if the argument can not be converted into something comparable with the receiver.

intValue

public int intValue()

Answers the int value which the receiver represents

Specified by:

intValue in class Number

Returns:

int the value of the receiver.

longValue

public long longValue()

Answers the long value which the receiver represents

Specified by:

longValue in class Number

Returns:

long the value of the receiver.

valueOf

public static BigInteger valueOf(long val)

Answers a BigInteger with the same value as val

Parameters:

val - the long value to convert to a BigInteger

Returns:

the BigInteger equivalent of the long value

add

public BigInteger add(BigInteger val)

Answers the sum of the receiver and a BigInteger

Parameters:

val - a BigInteger to add

Returns:

BigInteger this + val

negate

public BigInteger negate()

Answers the negative of the receiver

Returns:

BigInteger (-1) * this

signum

public int signum()

Answers the sign of the receiver

Returns:

BigInteger -1, 0, or 1 if the receiver is negative, zero, or positive

abs

public BigInteger abs()

Answers the absolute value of the receiver

Returns:

BigInteger absolute value of the receiver

pow

public BigInteger pow(int exponent)

Answers the receiver to the power of exponent.

Parameters:

exponent - the exponent

Returns:

BigInteger this ^ exponent

Throws:

ArithmeticException - if the exponent is negative.

modPow

public BigInteger modPow(BigInteger exponent,
                         BigInteger modulo)

Answers the receiver to the power of exponent modulo a BigInteger

Parameters:

exponent - the exponent

modulo - the modulo

Returns:

BigInteger this ^ exponent (mod modulo)

Throws:

ArithmeticException - modulo is <= 0

gcd

public BigInteger gcd(BigInteger val)

Answers the greatest common divisor of abs(this) and abs(val), zero if this==val==0

Parameters:

val - the value with which to compute the GCD

Returns:

BigInteger gcd(abs(this), abs(val))

modInverse

public BigInteger modInverse(BigInteger modulo)

Answers the inverse of the receiver modulo a BigInteger, if it exists.

Parameters:

modulo - BigInteger a BigInteger to divide

Returns:

BigInteger this^(-1) (mod modulo)

Throws:

ArithmeticException - if modulo is <= 0, or gcd(this,modulo) != 1

getLowestSetBit

public int getLowestSetBit()

Answers the index of the lowest set bit in the receiver, or -1 if no bits are set.

Returns:

BigInteger the bit index of the least significant set bit in the receiver.

shiftRight

public BigInteger shiftRight(int shiftval)

Answers a BigInteger with the value of the reciever divided by 2^shiftval.

Parameters:

shiftval - int the amount to shift the receiver.

Returns:

BigInteger this >> val

shiftLeft

public BigInteger shiftLeft(int shiftval)

Answers a BigInteger with the value of the reciever multiplied by 2^shiftval.

Parameters:

shiftval - int the amount to shift the receiver.

Returns:

BigInteger this << val

subtract

public BigInteger subtract(BigInteger val)

Answers the difference of the receiver and a BigInteger.

Parameters:

val - BigInteger the value to subtract

Returns:

BigInteger this - val

multiply

public BigInteger multiply(BigInteger val)

Answers the product of the receiver and a BigInteger.

Parameters:

val - BigInteger the value to multiply

Returns:

BigInteger this * val

divide

public BigInteger divide(BigInteger val)

Answers the quotient of the receiver and a BigInteger.

Parameters:

val - BigInteger the value to divide

Returns:

BigInteger this / val

Throws:

ArithmeticException - if val is zero.

remainder

public BigInteger remainder(BigInteger val)

Answers the remainder of the receiver divided by a BigInteger

Parameters:

val - a BigInteger to divide

Returns:

BigInteger this % val

Throws:

ArithmeticException - if val is zero

mod

public BigInteger mod(BigInteger val)

Answers the remainder of the receiver modulo a BigInteger (a positive value).

Parameters:

val - the value to divide

Returns:

BigInteger this (mod val)

Throws:

ArithmeticException - if val is zero

divideAndRemainder

public BigInteger[] divideAndRemainder(BigInteger val)

Answers the quotient and remainder of the receiver divided by a BigInteger.

Parameters:

val - BigInteger the value to divide.

Returns:

BigInteger[2] {this / val, this % val )}

Throws:

ArithmeticException - if val is zero.

toString

public String toString()

Answers a string containing a concise, human-readable description of the receiver. In this case, a string of decimal digits.

Overrides:

toString in class Object

Returns:

String a printable representation for the receiver.

toString

public String toString(int radix)

Answers a string containing a concise, human-readable description of the receiver as a sequence of digits in the specified radix.

Parameters:

radix - the radix

Returns:

String a printable representation for the receiver.

max

public BigInteger max(BigInteger val)

Answers the most positive of either the receiver or the argument.

Parameters:

val - BigInteger the value to compare.

Returns:

BigInteger the larger value.

min

public BigInteger min(BigInteger val)

Answers the most negative of either the receiver or the argument.

Parameters:

val - BigInteger the value to compare.

Returns:

BigInteger the smaller value.

hashCode

public int hashCode()

Answers an integer hash code for the receiver. Any two objects which answer true when passed to .equals must answer the same value for this method.

Overrides:

hashCode in class Object

Returns:

int the receiver's hash.

See Also:

equals(java.lang.Object)

testBit

public boolean testBit(int n)

Answers true if the specified bit is set in the receiver.

Parameters:

n - int the bit to check.

Returns:

boolean if the specified bit is set.

setBit

public BigInteger setBit(int n)

Sets the specified bit in the receiver.

Parameters:

n - int the bit to set.

Returns:

a new BitInteger with the specified bit set

clearBit

public BigInteger clearBit(int n)

Unsets the specified bit in the receiver.

Parameters:

n - int the bit to clear.

Returns:

a new BigInteger with the specified bit cleared

flipBit

public BigInteger flipBit(int n)

Toggles the specified bit in the receiver.

Parameters:

n - int the bit to flip.

Returns:

a new BigInteger with the specified bit flipped

and

public BigInteger and(BigInteger val)

Answers the bitwise AND of the receiver and the argument.

Parameters:

val - BigInteger the value to AND.

Returns:

BigInteger this & val

or

public BigInteger or(BigInteger val)

Answers the bitwise OR of the receiver and the argument.

Parameters:

val - BigInteger the value to OR.

Returns:

BigInteger this | val

xor

public BigInteger xor(BigInteger val)

Answers the bitwise XOR of the receiver and the argument.

Parameters:

val - BigInteger the value to XOR.

Returns:

BigInteger this XOR val

not

public BigInteger not()

Answers the bitwise negation of the receiver.

Returns:

BigInteger NOT(this)

andNot

public BigInteger andNot(BigInteger val)

Answers the bitwise NAND of the receiver and the argument.

Parameters:

val - BigInteger the value to NAND.

Returns:

BigInteger this & NOT(val)

bitLength

public int bitLength()

Answers the length in bits of the receiver.

Returns:

int the receiver's bit length.

bitCount

public int bitCount()

Answers the number of set bits in the receiver.

Returns:

int the receiver's bit count.

doubleValue

public double doubleValue()

Answers the double value which the receiver represents

Specified by:

doubleValue in class Number

Returns:

double the value of the receiver.

floatValue

public float floatValue()

Answers the float value which the receiver represents

Specified by:

floatValue in class Number

Returns:

float the value of the receiver.