org.metasyntactic.math
Class BigInteger

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

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Comparable, java.io.Serializable

public class BigInteger

extends java.lang.Number

implements java.lang.Comparable, java.lang.Cloneable, java.io.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 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 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.

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 (i + j) is shorthand for "a BigInteger whose value is that of the BigInteger i plus that of the BigInteger j. The pseudo-code expression (i == j) is shorthand for true if and only if the BigInteger i represents the same value as the the BigInteger j." Other pseudo-code expressions are interpreted similarly.

See Also:

Serialized Form

Field Summary

static BigInteger	ONE
static BigInteger	ZERO

Constructor Summary

BigInteger(boolean[] value)

BigInteger(boolean[] value, boolean isNegative)

BigInteger(boolean[] value, int start, int finish, boolean isNegative)

BigInteger(java.lang.String val)

BigInteger(java.lang.String val, int radix)

Method Summary

BigInteger	abs()
BigInteger	add(BigInteger bi) Returns a BigInteger shose values is (this + bi)
int	bitCount()
int	bitLength()
BigInteger	clearBit(int n)
java.lang.Object	clone()
int	compareTo(BigInteger bi)
int	compareTo(java.lang.Object o)
BigInteger	copy()
BigInteger	divide(BigInteger bi) Returns a new BigInteger whose value is equals to (this / bi)
BigInteger[]	divideAndRemainder(BigInteger bi)
double	doubleValue()
boolean	equals(BigInteger bi)
boolean	equals(java.lang.Object o)
BigInteger	flipBit(int n)
float	floatValue()
int	getLowestSetBit()
int	hashCode() Returns a hashcode whose value is equals to (this % 231)
int	intValue()
boolean	isZero()
long	longValue()
static void	main(java.lang.String[] args)
BigInteger	max(BigInteger val)
BigInteger	min(BigInteger val)
BigInteger	multiply(BigInteger bi) Returns a new BigInteger whose value is equal to (this * bi)
BigInteger	negate()
BigInteger	not()
BigInteger	pow(int exponent) Returns a new BigInteger whose value is equal to (thisexponent)
BigInteger	remainder(BigInteger bi) Returns a new BigInteger whose value is equal to (this % bi)
BigInteger	setBit(int n)
BigInteger	shiftLeft(int places) Returns a new BigInteger whose value is equal to (this << places) NOTE! This method breaks the semantics of java's right shift operator in that you can pass it a negative integer.
BigInteger	shiftRight(int places) Returns a new BigInteger whose value is equal to (this >> places) NOTE! This method breaks the semantics of java's right shift operator in that you can pass it a negative integer.
int	signum()
BigInteger	subtract(BigInteger bi) Returns a BigInteger whose value is (this - bi)
boolean	testBit(int n)
java.lang.String	toString() Returns the String version of this BigInteger in base 10 format
java.lang.String	toString(int radix) Returns the String version of this BigInteger in base radix format.

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ZERO

public static final BigInteger ZERO

ONE

public static final BigInteger ONE

Constructor Detail

BigInteger

public BigInteger(java.lang.String val)

BigInteger

public BigInteger(java.lang.String val,
                  int radix)

BigInteger

public BigInteger(boolean[] value)

BigInteger

public BigInteger(boolean[] value,
                  boolean isNegative)

BigInteger

public BigInteger(boolean[] value,
                  int start,
                  int finish,
                  boolean isNegative)

Method Detail

main

public static void main(java.lang.String[] args)

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object

copy

public BigInteger copy()

add

public BigInteger add(BigInteger bi)

Returns a BigInteger shose values is (this + bi)

Parameters:

bi - value to be added to this BigInteger

Returns:

this + bi

subtract

public BigInteger subtract(BigInteger bi)

Returns a BigInteger whose value is (this - bi)

Parameters:

bi - value to be subtracted from this BigInteger

Returns:

this - bi

multiply

public BigInteger multiply(BigInteger bi)

Returns a new BigInteger whose value is equal to (this * bi)

divide

public BigInteger divide(BigInteger bi)

Returns a new BigInteger whose value is equals to (this / bi)

Throws:

java.lang.ArithmeticException - when bi == ZERO

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

equals

public boolean equals(BigInteger bi)

compareTo

public int compareTo(java.lang.Object o)

Specified by:

compareTo in interface java.lang.Comparable

compareTo

public int compareTo(BigInteger bi)

hashCode

public int hashCode()

Returns a hashcode whose value is equals to (this % 231)

Overrides:

hashCode in class java.lang.Object

shiftRight

public BigInteger shiftRight(int places)

Returns a new BigInteger whose value is equal to (this >> places) NOTE! This method breaks the semantics of java's right shift operator in that you can pass it a negative integer. If you pass it a negative integer then this.shiftLeft(-places) will be called.

shiftLeft

public BigInteger shiftLeft(int places)

Returns a new BigInteger whose value is equal to (this << places) NOTE! This method breaks the semantics of java's right shift operator in that you can pass it a negative integer. If you pass it a negative integer then this.shiftRight(-places) will be called.

toString

public java.lang.String toString()

Returns the String version of this BigInteger in base 10 format

Overrides:

toString in class java.lang.Object

toString

public java.lang.String toString(int radix)

Returns the String version of this BigInteger in base radix format. NOTE! While toString() is a costly method, the result is cached so that subsequent calls to toString with the same radix will take almost no time

remainder

public BigInteger remainder(BigInteger bi)

Returns a new BigInteger whose value is equal to (this % bi)

divideAndRemainder

public BigInteger[] divideAndRemainder(BigInteger bi)

pow

public BigInteger pow(int exponent)

Returns a new BigInteger whose value is equal to (thisexponent)

abs

public BigInteger abs()

isZero

public boolean isZero()

negate

public BigInteger negate()

signum

public int signum()

not

public BigInteger not()

testBit

public boolean testBit(int n)

setBit

public BigInteger setBit(int n)

clearBit

public BigInteger clearBit(int n)

flipBit

public BigInteger flipBit(int n)

getLowestSetBit

public int getLowestSetBit()

bitLength

public int bitLength()

bitCount

public int bitCount()

min

public BigInteger min(BigInteger val)

max

public BigInteger max(BigInteger val)

intValue

public int intValue()

Specified by:

intValue in class java.lang.Number

longValue

public long longValue()

Specified by:

longValue in class java.lang.Number

doubleValue

public double doubleValue()

Specified by:

doubleValue in class java.lang.Number

floatValue

public float floatValue()

Specified by:

floatValue in class java.lang.Number