XBigInteger is an object wrapper for the
arbitrary precision BigInteger class that
also provides Stringable
capabilities. Hence, unlike BigInteger,
objects of this class are mutable.

The default wrapped value for this class is
the BigInteger representation of zero,
BigInteger.ZERO.

This class provides the operations of the class
BigInteger in two forms. Member methods
will mutate the object that is operated on but leave all
parameters unchanged and will return void.
Static methods will create new objects and change no
parameters. In all cases, if an argument to an operation
is null, it is treated as zero.

In addition to the usual string representation of a
big integer as a signed decimal, this class supports a
string bit representation that shows the bits in a
two's complement form that makes it easier to see what
is happening with the bit operations. See the method
toBits for more details.

XBigInteger

Constructs an XBigInteger using the information
contained in the given string data. Will parse and evaluate
simple big integer arithmetic expressions in decimal format and
will also read data in the special bit format output by the
method toBits.

Makes use of the parsing capabilities of the method
fromStringData(String).

fromStringData

Sets the state of this XBigInteger using the
information contained in the given string data. Will parse
and evaluate simple big integer arithmetic expressions in
decimal format and will also read data in the format output
by the method toBits.

setValue

Sets the state of this XBigInteger using the
information contained in the given string data. Will parse
and evaluate simple big integer arithmetic expressions in
decimal format and will also read data in the format output
by the method toBits.

Makes use of the parsing capabilities of the method
fromStringData(String).

flipBit

Returns a new XBigInteger whose value
is equivalent to x with the
n-th bit flipped.

In other words, returns
(x^(1<<n)).

Throws ArithmeticException if n is negative.

Parameters:

x - the initial value

n - the bit to modify

getLowestSetBit

public final int getLowestSetBit()

Returns the index of the rightmost (lowest-order) one bit in this
XBigInteger, that is, the number of zero bits to the
right of the rightmost one bit.

Returns -1 if this XBigInteger contains no one bits.

Computes ((this == 0) ? -1 : log2(this & -this)).

bitLength

public final int bitLength()

Returns the number of bits in the minimal two's-complement
representation of this XBigInteger, excluding a sign bit.
For positive XBigInteger's, this is equivalent to the
number of bits in the ordinary binary representation.

Computes (ceil(log2(this < 0 ? -this : (this+1)))).

bitCount

public final int bitCount()

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

isProbablePrime

public final boolean isProbablePrime(int certainty)

Returns true if this XBigInteger is probably prime,
false if it's definitely composite.

If certainty <= 0, true is returned.

If the call returns true, the probability that this
XBigInteger is prime exceeds (1 - 1/n) where n equals
2 raised to the power certainty. The execution time of this method
is proportional to the value of this parameter.

Parameters:

certainty - a measure of the uncertainty that the caller is
willing to tolerate

compareTo

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.

Throws NullPointerException if the given object
y is null. Since this method is not specified in
the interface Comparable, we throw the natural
exception rather than ClassCastException which
is required in the more generic compareTo(Object)
method.