edu.neu.ccs
Class XBigInteger

java.lang.Object
  extended byedu.neu.ccs.XObject
      extended byedu.neu.ccs.XNumber
          extended byedu.neu.ccs.XBigInteger
All Implemented Interfaces:
Cloneable, Comparable, Serializable, Stringable

public class XBigInteger
extends XNumber
implements Comparable

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.

Since:
1.0
Version:
2.4.0
See Also:
Serialized Form

Field Summary
private static BigInteger MINUSONE
          The minus-one BigInteger.
private static String negative
          The introductory string for the bit represention of negative numbers.
private static char one
          The one character for bit parsing.
private static char period
          The period character for bit parsing.
private static String positive
          The introductory string for the bit represention of positive numbers.
static String standardMessage
          The standard error message for fromStringData.
private  BigInteger value
          The wrapped value of this object.
private static char zero
          The zero character for bit parsing.
private static BigInteger ZERO
          The zero BigInteger.
 
Fields inherited from class edu.neu.ccs.XObject
changeAdapter, VALUE
 
Constructor Summary
XBigInteger()
          Constructs a wrapper for the default BigInteger value of BigInteger.ZERO.
XBigInteger(BigInteger b)
          Constructs a wrapper for the given BigInteger value.
XBigInteger(byte[] val)
          Translates a byte array containing the two's-complement binary representation of a BigInteger into a BigInteger that is stored internally.
XBigInteger(long n)
          Constructs a wrapper for the BigInteger value corresponding to the given long data.
XBigInteger(String s)
          Constructs an XBigInteger using the information contained in the given string data.
XBigInteger(String s, int radix)
          Constructs an XBigInteger using the information contained in the given string of digit data in the given radix with a possible minus sign in front.
XBigInteger(XBigInteger b)
          Constructs an XBigInteger by copying the internal value of the given XBigInteger.
 
Method Summary
 void abs()
          Sets this to abs(this).
static XBigInteger abs(XBigInteger y)
          Returns a new XBigInteger whose value is the absolute value of the given y.
 void add(XBigInteger y)
          Sets this to (this + y).
static XBigInteger add(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is x + y.
 void and(XBigInteger y)
          Sets this to (this & y).
static XBigInteger and(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is x & y.
 void andNot(XBigInteger y)
          Sets this to (this & ~y).
static XBigInteger andNot(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is x & ~y.
static XBigInteger binomial(int n, int k)
          Returns the binomial coefficient for n, k.
 int bitCount()
          Returns the number of bits in the two's complement representation of this XBigInteger that differ from its sign bit.
 int bitLength()
          Returns the number of bits in the minimal two's-complement representation of this XBigInteger, excluding a sign bit.
 byte byteValue()
          Returns the value of this number as a byte value.
 void clearBit(int n)
          Sets this to the equivalent value with the n-th bit cleared.
static XBigInteger clearBit(XBigInteger x, int n)
          Returns a new XBigInteger whose value is equivalent to x with the n-th bit cleared.
 int compareTo(Object o)
          Compares this XBigInteger with the specified Object o.
 int compareTo(XBigInteger y)
          Compares this XBigInteger with the specified XBigInteger y.
 int digits()
          Returns the number of digits in toString() excluding the sign if any.
 int digits(int radix)
          Returns the number of digits in toString(radix) excluding the sign if any.
 void divide(XBigInteger y)
          Sets this to (this / y).
static XBigInteger divide(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is x / y.
static XBigInteger[] divideAndRemainder(XBigInteger x, XBigInteger y)
          Returns an array {quotient, remainder} after division of x by y.
 double doubleValue()
          Returns the value of this number as a double value.
 boolean equals(Object other)
          Returns true if the given object is of type XBigInteger and its BigInteger value is equal to the BigInteger value of this XBigInteger; returns false otherwise.
static XBigInteger factorial(int n)
          Returns factorial(n), that is, the product of the numbers from 1 to n.
 void flipBit(int n)
          Sets this to the equivalent value with the n-th bit flipped.
static XBigInteger flipBit(XBigInteger x, int n)
          Returns a new XBigInteger whose value is equivalent to x with the n-th bit flipped.
 float floatValue()
          Returns the value of this number as a float value.
private  void fromBits(String bits)
          Sets the state of this XBigInteger by reading data in the format output by the method toBits.
 void fromStringData(String data)
          Sets the state of this XBigInteger using the information contained in the given string data.
 void gcd(XBigInteger y)
          Sets this to gcd(this, y) where "gcd" stands for "greatest common divisor".
static XBigInteger gcd(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is gcd(x, y) where "gcd" stands for "greatest common divisor".
 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.
 BigInteger getValue()
          Returns the BigInteger value wrapped by this object.
 int hashCode()
          Returns the int hash code of the wrapped BigInteger value.
 int intValue()
          Returns the value of this number as a int value.
 boolean isProbablePrime(int certainty)
          Returns true if this XBigInteger is probably prime, false if it's definitely composite.
 void lcm(XBigInteger y)
          Sets this to lcm(this, y) where "lcm" stands for "least common multiple".
static XBigInteger lcm(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is lcm(x, y) where "lcm" stands for "least common multiple".
 long longValue()
          Returns the value of this number as a long value.
 void max(XBigInteger y)
          Sets this to max(this, y).
static XBigInteger max(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is the maximum of the given x and y values.
 void min(XBigInteger y)
          Sets this to min(this, y).
static XBigInteger min(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is the minimum of the given x and y values.
 void mod(XBigInteger y)
          Sets this to (this mod y).
static XBigInteger mod(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is x mod y.
 void modInverse(XBigInteger y)
          Sets this to the inverse modulo y of this.
static XBigInteger modInverse(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is the inverse of x modulo y.
 void modPow(XBigInteger e, XBigInteger y)
          Sets this to the value of this raised to the given exponent e modulo the given modulus y.
static XBigInteger modPow(XBigInteger x, XBigInteger e, XBigInteger y)
          Returns a new XBigInteger whose value is the given base x raised to the given exponent e modulo the given modulus y.
 void multiply(XBigInteger y)
          Sets this to (this * y).
static XBigInteger multiply(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is x * y.
 void negate()
          Sets this to (-this).
static XBigInteger negate(XBigInteger y)
          Returns a new XBigInteger whose value is the negation of the given y.
 void not()
          Sets this to (~this), which is the bitwise-not of the current value.
static XBigInteger not(XBigInteger y)
          Returns a new XBigInteger whose value is the bitwise not of the given y.
 void or(XBigInteger y)
          Sets this to (this | y).
static XBigInteger or(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is x | y.
 void pow(int e)
          Sets this to the value of this raised to the given integer exponent e which must be a non-negative integer.
static XBigInteger pow(XBigInteger x, int e)
          Returns a new XBigInteger whose value is the given base x raised to the given exponent e which must be a non-negative integer.
 void remainder(XBigInteger y)
          Sets this to (this % y).
static XBigInteger remainder(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is x % y.
 void setBit(int n)
          Sets this to the equivalent value with the n-th bit set.
static XBigInteger setBit(XBigInteger x, int n)
          Returns a new XBigInteger whose value is equivalent to x with the n-th bit set.
 void setValue(BigInteger b)
          Sets the value wrapped by this object to the given BigInteger value.
 void setValue(byte[] val)
          Translates a byte array containing the two's-complement binary representation of a BigInteger into a BigInteger that is stored internally in this XBigInteger.
 void setValue(long n)
          Sets the value wrapped by this object to the BigInteger value corresponding to the given long value.
 void setValue(String data)
          Sets the state of this XBigInteger using the information contained in the given string data.
 void setValue(String s, int radix)
          Sets the state of this XBigInteger using the information contained in the given string of digit data in the given radix with a possible minus sign in front.
 void setValue(XBigInteger b)
          Sets the value wrapped by this object to the internal value of the given XBigInteger value.
 void shiftLeft(int n)
          Sets this to (this << n); the shift distance, n, may be negative, in which case this method performs a right shift.
static XBigInteger shiftLeft(XBigInteger x, int n)
          Returns a new XBigInteger whose value is (x << n); the shift distance, n, may be negative, in which case this method performs a right shift.
 void shiftRight(int n)
          Sets this to (this >> n); the shift distance, n, may be negative, in which case this method performs a left shift.
static XBigInteger shiftRight(XBigInteger x, int n)
          Returns a new XBigInteger whose value is (x >> n); the shift distance, n, may be negative, in which case this method performs a left shift.
 short shortValue()
          Returns the value of this number as a short value.
 int signum()
          Returns -1, 0 or 1 as the value of this XBigInteger is negative, zero or positive.
 void subtract(XBigInteger y)
          Sets this to (this - y).
static XBigInteger subtract(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is x - y.
 boolean testBit(int n)
          Returns true if and only if the designated bit is set.
 String toBits()
          Returns a string representation of the wrapped BigInteger value in a binary bit representation that is in unsigned two's complement format.
static BigInteger[] toPrimitiveArray(XBigInteger[] x)
          Returns an array of BigInteger objects initialized from the given array of XBigInteger objects.
 String toString()
          Returns the string representation of the wrapped BigInteger value.
 String toString(int radix)
          Returns the string representation of the wrapped BigInteger value in the given radix.
 String toStringData()
          Returns a string encapsulation of this XBigInteger that contains the information needed to set the state of this XBigInteger at a later time.
static XBigInteger[] toXArray(BigInteger[] a)
          Returns an array of XBigInteger objects initialized from the given array of BigInteger objects.
 void xor(XBigInteger y)
          Sets this to (this ^ y).
static XBigInteger xor(XBigInteger x, XBigInteger y)
          Returns a new XBigInteger whose value is x ^ y.
 
Methods inherited from class edu.neu.ccs.XObject
addPropertyChangeListener, addPropertyChangeListener, formatErrorMessage, removePropertyChangeListener, removePropertyChangeListener, toStringArray
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ZERO

private static final BigInteger ZERO
The zero BigInteger.


MINUSONE

private static final BigInteger MINUSONE
The minus-one BigInteger.


zero

private static final char zero
The zero character for bit parsing.

See Also:
Constant Field Values

one

private static final char one
The one character for bit parsing.

See Also:
Constant Field Values

period

private static final char period
The period character for bit parsing.

See Also:
Constant Field Values

positive

private static final String positive
The introductory string for the bit represention of positive numbers.

See Also:
Constant Field Values

negative

private static final String negative
The introductory string for the bit represention of negative numbers.

See Also:
Constant Field Values

standardMessage

public static final String standardMessage
The standard error message for fromStringData.

See Also:
Constant Field Values

value

private BigInteger value
The wrapped value of this object.

Constructor Detail

XBigInteger

public XBigInteger()

Constructs a wrapper for the default BigInteger value of BigInteger.ZERO.


XBigInteger

public XBigInteger(BigInteger b)

Constructs a wrapper for the given BigInteger value.

If the given value is null, the wrapped value is set to BigInteger.ZERO.

Parameters:
b - the value to be wrapped

XBigInteger

public XBigInteger(XBigInteger b)

Constructs an XBigInteger by copying the internal value of the given XBigInteger.

If the given value is null, the wrapped value is set to BigInteger.ZERO.

Parameters:
b - the value to be copied

XBigInteger

public XBigInteger(long n)

Constructs a wrapper for the BigInteger value corresponding to the given long data.

Parameters:
n - a long to encapsulate

XBigInteger

public XBigInteger(String s)
            throws ParseException

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

Parameters:
s - a string representation of the desired value
Throws:
ParseException - if the string is null or malformed

XBigInteger

public XBigInteger(String s,
                   int radix)

Constructs an XBigInteger using the information contained in the given string of digit data in the given radix with a possible minus sign in front.

This constructor makes use of the parsing capabilities of the method setValue(String, int).

The character-to-digit mapping is provided by Character.digit.

The string may not contain any extraneous characters (whitespace, for example).

Throws NumberFormatException if:

Parameters:
s - a string representation of the desired value
radix - radix to be used in interpreting s
Throws:
NumberFormatException - as explained above

XBigInteger

public XBigInteger(byte[] val)

Translates a byte array containing the two's-complement binary representation of a BigInteger into a BigInteger that is stored internally.

The input array is assumed to be in big-endian byte-order: the most significant byte is in the zero-th element.

Unlike the corresponding constructor for the Java class BigInteger, this constructor will set the internal value to BigInteger.ZERO, if the given array is null or of length 0.

Parameters:
val - big-endian two's-complement binary representation of the internal BigInteger
Method Detail

fromStringData

public final void fromStringData(String data)
                          throws ParseException

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.

Fires property change: VALUE.

Specified by:
fromStringData in interface Stringable
Specified by:
fromStringData in class XObject
Parameters:
data - a string representation of the desired value
Throws:
ParseException - if the data is null or malformed

toStringData

public final String toStringData()

Returns a string encapsulation of this XBigInteger that contains the information needed to set the state of this XBigInteger at a later time.

Identical to toString.

Specified by:
toStringData in interface Stringable
Specified by:
toStringData in class XObject

toString

public final String toString()

Returns the string representation of the wrapped BigInteger value.

The digit-to-character mapping provided by Character.forDigit is used, and a minus sign is prepended if appropriate.

This representation is compatible with the (String) constructor.


toString

public final String toString(int radix)

Returns the string representation of the wrapped BigInteger value in the given radix.

If the radix is outside the range from Character.MIN_RADIX to Character.MAX_RADIX inclusive, it will default to 10 (as is the case for Integer.toString).

The digit-to-character mapping provided by Character.forDigit is used, and a minus sign is prepended if appropriate.

This representation is compatible with the (String, int) constructor.

Parameters:
radix - radix of the string representation

toBits

public String toBits()

Returns a string representation of the wrapped BigInteger value in a binary bit representation that is in unsigned two's complement format.

This representation is quite different from that returned by this.toString(2) which is a signed representation with the bits being those of the corresponding positive value.

Here, a positive value is represented as:

    ...0bbb

and a negative value is represented as:

    ...1bbb

where bbb stands for zero or more binary digits 0,1.

The significance of ...0 is that there are in principle infinitely many 0 bits to the left in the bit representation of a positive big integer.

The significance of ...1 is that there are in principle infinitely many 1 bits to the left in the bit representation of a negative big integer.

The representations returned by this method are visually compatible with the bit operations in this class and therefore make these operations much easier to understand.

The method fromStringData can read the representations output by this method.


fromBits

private void fromBits(String bits)
               throws ParseException

Sets the state of this XBigInteger by reading data in the format output by the method toBits.

This is a private helper method for fromStringData.

Parameters:
bits - the string containing the state information in bits
Throws:
ParseException - if bits is null or malformed

digits

public final int digits()

Returns the number of digits in toString() excluding the sign if any.


digits

public final int digits(int radix)

Returns the number of digits in toString(radix) excluding the sign if any.

If the radix is outside the range from Character.MIN_RADIX to Character.MAX_RADIX inclusive, it will default to 10.

Parameters:
radix - radix of the string representation

equals

public final boolean equals(Object other)
Returns true if the given object is of type XBigInteger and its BigInteger value is equal to the BigInteger value of this XBigInteger; returns false otherwise.

Parameters:
other - the object to be compared

hashCode

public final int hashCode()
Returns the int hash code of the wrapped BigInteger value.


setValue

public final void setValue(BigInteger b)

Sets the value wrapped by this object to the given BigInteger value.

If the given value is null, the internal value is set to BigInteger.ZERO.

Fires property change: VALUE.

Parameters:
b - the value to be wrapped

setValue

public final void setValue(XBigInteger b)

Sets the value wrapped by this object to the internal value of the given XBigInteger value.

If the given input is null, the internal value is set to BigInteger.ZERO.

Fires property change: VALUE.

Parameters:
b - the value to be copied

setValue

public final void setValue(long n)

Sets the value wrapped by this object to the BigInteger value corresponding to the given long value.

Uses the static method BigInteger.valueOf to take advantages of optimizations built into Java.

Fires property change: VALUE.

Parameters:
n - a long to encapsulate

setValue

public final void setValue(String data)
                    throws ParseException

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

Fires property change: VALUE.

Parameters:
data - a string representation of the desired value
Throws:
ParseException - if the data is null or malformed

setValue

public final void setValue(String s,
                           int radix)

Sets the state of this XBigInteger using the information contained in the given string of digit data in the given radix with a possible minus sign in front.

The character-to-digit mapping is provided by Character.digit.

The string may not contain any extraneous characters (whitespace, for example).

Throws NumberFormatException if:

Parameters:
s - a string representation of the desired value
radix - radix to be used in interpreting s
Throws:
NumberFormatException - as explained above

setValue

public final void setValue(byte[] val)

Translates a byte array containing the two's-complement binary representation of a BigInteger into a BigInteger that is stored internally in this XBigInteger.

The input array is assumed to be in big-endian byte-order: the most significant byte is in the zero-th element.

This method will set the internal value to BigInteger.ZERO, if the given array is null or of length 0.

Fires property change: VALUE.

Parameters:
val - big-endian two's-complement binary representation of the internal BigInteger

getValue

public final BigInteger getValue()

Returns the BigInteger value wrapped by this object.


byteValue

public final byte byteValue()
Description copied from class: XNumber
Returns the value of this number as a byte value.

Specified by:
byteValue in class XNumber

shortValue

public final short shortValue()
Description copied from class: XNumber
Returns the value of this number as a short value.

Specified by:
shortValue in class XNumber

intValue

public final int intValue()
Description copied from class: XNumber
Returns the value of this number as a int value.

Specified by:
intValue in class XNumber

longValue

public final long longValue()
Description copied from class: XNumber
Returns the value of this number as a long value.

Specified by:
longValue in class XNumber

floatValue

public final float floatValue()
Description copied from class: XNumber
Returns the value of this number as a float value.

Specified by:
floatValue in class XNumber

doubleValue

public final double doubleValue()
Description copied from class: XNumber
Returns the value of this number as a double value.

Specified by:
doubleValue in class XNumber

signum

public final int signum()

Returns -1, 0 or 1 as the value of this XBigInteger is negative, zero or positive.


abs

public final void abs()

Sets this to abs(this).

Fires property change: VALUE.


abs

public static XBigInteger abs(XBigInteger y)

Returns a new XBigInteger whose value is the absolute value of the given y.

Parameters:
y - the explicit argument

negate

public final void negate()

Sets this to (-this).

Mathematically, (-this) equals (~this)+1.

Fires property change: VALUE.


negate

public static XBigInteger negate(XBigInteger y)

Returns a new XBigInteger whose value is the negation of the given y.

Mathematically, (-y) equals (~y)+1.

Parameters:
y - the explicit argument

max

public final void max(XBigInteger y)

Sets this to max(this, y).

Fires property change: VALUE.

Parameters:
y - the explicit argument

max

public static XBigInteger max(XBigInteger x,
                              XBigInteger y)

Returns a new XBigInteger whose value is the maximum of the given x and y values.

Parameters:
x - the LHS argument
y - the RHS argument

min

public final void min(XBigInteger y)

Sets this to min(this, y).

Fires property change: VALUE.

Parameters:
y - the explicit argument

min

public static XBigInteger min(XBigInteger x,
                              XBigInteger y)

Returns a new XBigInteger whose value is the minimum of the given x and y values.

Parameters:
x - the LHS argument
y - the RHS argument

add

public final void add(XBigInteger y)

Sets this to (this + y).

Fires property change: VALUE.

Parameters:
y - the explicit argument

add

public static XBigInteger add(XBigInteger x,
                              XBigInteger y)

Returns a new XBigInteger whose value is x + y.

Parameters:
x - the LHS argument
y - the RHS argument

subtract

public final void subtract(XBigInteger y)

Sets this to (this - y).

Fires property change: VALUE.

Parameters:
y - the explicit argument

subtract

public static XBigInteger subtract(XBigInteger x,
                                   XBigInteger y)

Returns a new XBigInteger whose value is x - y.

Parameters:
x - the LHS argument
y - the RHS argument

multiply

public final void multiply(XBigInteger y)

Sets this to (this * y).

Fires property change: VALUE.

Parameters:
y - the explicit argument

multiply

public static XBigInteger multiply(XBigInteger x,
                                   XBigInteger y)

Returns a new XBigInteger whose value is x * y.

Parameters:
x - the LHS argument
y - the RHS argument

divide

public final void divide(XBigInteger y)

Sets this to (this / y).

Fires property change: VALUE.

Parameters:
y - the explicit argument
Throws:
ArithmeticException - on division by zero

divide

public static XBigInteger divide(XBigInteger x,
                                 XBigInteger y)

Returns a new XBigInteger whose value is x / y.

Parameters:
x - the LHS argument
y - the RHS argument
Throws:
ArithmeticException - on division by zero

remainder

public final void remainder(XBigInteger y)

Sets this to (this % y).

Fires property change: VALUE.

Parameters:
y - the explicit argument
Throws:
ArithmeticException - on division by zero

remainder

public static XBigInteger remainder(XBigInteger x,
                                    XBigInteger y)

Returns a new XBigInteger whose value is x % y.

Parameters:
x - the LHS argument
y - the RHS argument
Throws:
ArithmeticException - on division by zero

divideAndRemainder

public static XBigInteger[] divideAndRemainder(XBigInteger x,
                                               XBigInteger y)

Returns an array {quotient, remainder} after division of x by y.

Parameters:
x - the LHS argument
y - the RHS argument
Throws:
ArithmeticException - on division by zero

mod

public final void mod(XBigInteger y)

Sets this to (this mod y).

This method differs from remainder in that it always returns a non-negative XBigInteger.

Throws an ArithmeticException if y is null or is less than or equal to zero.

Fires property change: VALUE.

Parameters:
y - the explicit argument
Throws:
ArithmeticException - on division by zero

mod

public static XBigInteger mod(XBigInteger x,
                              XBigInteger y)

Returns a new XBigInteger whose value is x mod y.

This method differs from remainder in that it always returns a non-negative XBigInteger.

Throws an ArithmeticException if y is null or is less than or equal to zero.

Parameters:
x - the LHS argument
y - the RHS argument
Throws:
ArithmeticException - on division by zero

modInverse

public final void modInverse(XBigInteger y)

Sets this to the inverse modulo y of this.

Throws an ArithmeticException if y is null or is less than or equal to zero or if this number is not relatively prime to y.

Fires property change: VALUE.

Parameters:
y - the explicit argument
Throws:
ArithmeticException - as explained above

modInverse

public static XBigInteger modInverse(XBigInteger x,
                                     XBigInteger y)

Returns a new XBigInteger whose value is the inverse of x modulo y.

Throws an ArithmeticException if y is null or is less than or equal to zero or if x is null or is not relatively prime to y.

Parameters:
x - the LHS argument
y - the RHS argument
Throws:
ArithmeticException - as explained above

pow

public final void pow(int e)

Sets this to the value of this raised to the given integer exponent e which must be a non-negative integer.

Throws an ArithmeticException if the given integer exponent is negative.

Fires property change: VALUE.

Parameters:
e - the non-negative integer exponent
Throws:
ArithmeticException - as explained above

pow

public static XBigInteger pow(XBigInteger x,
                              int e)

Returns a new XBigInteger whose value is the given base x raised to the given exponent e which must be a non-negative integer.

Throws an ArithmeticException if the given integer exponent is negative.

Parameters:
x - the base
e - the non-negative integer exponent
Throws:
ArithmeticException - as explained above

modPow

public final void modPow(XBigInteger e,
                         XBigInteger y)

Sets this to the value of this raised to the given exponent e modulo the given modulus y.

Throws an ArithmeticException if:

Fires property change: VALUE.

Parameters:
e - the exponent
y - the modulus
Throws:
ArithmeticException - as explained above

modPow

public static XBigInteger modPow(XBigInteger x,
                                 XBigInteger e,
                                 XBigInteger y)

Returns a new XBigInteger whose value is the given base x raised to the given exponent e modulo the given modulus y.

Throws an ArithmeticException if:

Parameters:
x - the base
e - the exponent
y - the modulus
Throws:
ArithmeticException - as explained above

gcd

public final void gcd(XBigInteger y)

Sets this to gcd(this, y) where "gcd" stands for "greatest common divisor".

The "gcd" is always greater than or equal to zero and is zero if and only if both this and y are zero.

Fires property change: VALUE.

Parameters:
y - the explicit argument

gcd

public static XBigInteger gcd(XBigInteger x,
                              XBigInteger y)

Returns a new XBigInteger whose value is gcd(x, y) where "gcd" stands for "greatest common divisor".

The "gcd" is always greater than or equal to zero and is zero if and only if both x and y are zero.

Parameters:
x - the LHS argument
y - the RHS argument

lcm

public final void lcm(XBigInteger y)

Sets this to lcm(this, y) where "lcm" stands for "least common multiple".

The "lcm" is always greater than or equal to zero and is zero if and only if both this and y are zero.

Fires property change: VALUE.

Parameters:
y - the explicit argument

lcm

public static XBigInteger lcm(XBigInteger x,
                              XBigInteger y)

Returns a new XBigInteger whose value is lcm(x, y) where "lcm" stands for "least common multiple".

The "lcm" is always greater than or equal to zero and is zero if and only if both x and y are zero.

Parameters:
x - the LHS argument
y - the RHS argument

shiftLeft

public final void shiftLeft(int n)

Sets this to (this << n); the shift distance, n, may be negative, in which case this method performs a right shift.

Fires property change: VALUE.

Parameters:
n - the left shift in bits

shiftLeft

public static XBigInteger shiftLeft(XBigInteger x,
                                    int n)

Returns a new XBigInteger whose value is (x << n); the shift distance, n, may be negative, in which case this method performs a right shift.

Parameters:
x - the value to shift
n - the left shift in bits

shiftRight

public final void shiftRight(int n)

Sets this to (this >> n); the shift distance, n, may be negative, in which case this method performs a left shift.

Fires property change: VALUE.

Parameters:
n - the right shift in bits

shiftRight

public static XBigInteger shiftRight(XBigInteger x,
                                     int n)

Returns a new XBigInteger whose value is (x >> n); the shift distance, n, may be negative, in which case this method performs a left shift.

Parameters:
x - the value to shift
n - the right shift in bits

not

public final void not()

Sets this to (~this), which is the bitwise-not of the current value.

Mathematically, (~this) equals -(this+1).

Fires property change: VALUE.


not

public static XBigInteger not(XBigInteger y)

Returns a new XBigInteger whose value is the bitwise not of the given y.

Mathematically, (~y) equals -(y+1).

Parameters:
y - the explicit argument

and

public final void and(XBigInteger y)

Sets this to (this & y).

The value set is negative if and only if this and y are both negative.

Fires property change: VALUE.

Parameters:
y - the explicit argument

and

public static XBigInteger and(XBigInteger x,
                              XBigInteger y)

Returns a new XBigInteger whose value is x & y.

The value returned is negative if and only if x and y are both negative.

Parameters:
x - the LHS argument
y - the RHS argument

or

public final void or(XBigInteger y)

Sets this to (this | y).

The value set is negative if and only if at least one of this and y is negative.

Fires property change: VALUE.

Parameters:
y - the explicit argument

or

public static XBigInteger or(XBigInteger x,
                             XBigInteger y)

Returns a new XBigInteger whose value is x | y.

The value returned is negative if and only if at least one of x and y is negative.

Parameters:
x - the LHS argument
y - the RHS argument

xor

public final void xor(XBigInteger y)

Sets this to (this ^ y).

The value set is negative if and only if exactly one of this and y is negative.

Fires property change: VALUE.

Parameters:
y - the explicit argument

xor

public static XBigInteger xor(XBigInteger x,
                              XBigInteger y)

Returns a new XBigInteger whose value is x ^ y.

The value returned is negative if and only if exactly one of x and y is negative.

Parameters:
x - the LHS argument
y - the RHS argument

andNot

public final void andNot(XBigInteger y)

Sets this to (this & ~y).

The value set is negative if and only if this is negative and y is positive.

Fires property change: VALUE.

Parameters:
y - the explicit argument

andNot

public static XBigInteger andNot(XBigInteger x,
                                 XBigInteger y)

Returns a new XBigInteger whose value is x & ~y.

The value returned is negative if and only if x is negative and y is positive.

Parameters:
x - the LHS argument
y - the RHS argument

testBit

public final boolean testBit(int n)

Returns true if and only if the designated bit is set.

Computes ((this & (1<<n)) != 0).

Throws ArithmeticException if n is negative.

Parameters:
n - index of bit to test
Throws:
ArithmeticException - if n is negative

setBit

public final void setBit(int n)

Sets this to the equivalent value with the n-th bit set.

In other words, sets this to (this|(1<<n)).

Fires property change: VALUE.

Throws ArithmeticException if n is negative.

Parameters:
n - the bit to modify

setBit

public static XBigInteger setBit(XBigInteger x,
                                 int n)

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

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

Throws ArithmeticException if n is negative.

Parameters:
x - the initial value
n - the bit to modify

clearBit

public final void clearBit(int n)

Sets this to the equivalent value with the n-th bit cleared.

In other words, sets this to (this&~(1<<n)).

Fires property change: VALUE.

Throws ArithmeticException if n is negative.

Parameters:
n - the bit to modify

clearBit

public static XBigInteger clearBit(XBigInteger x,
                                   int n)

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

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

Throws ArithmeticException if n is negative.

Parameters:
x - the initial value
n - the bit to modify

flipBit

public final void flipBit(int n)

Sets this to the equivalent value with the n-th bit flipped.

In other words, sets this to (this^(1<<n)).

Fires property change: VALUE.

Throws ArithmeticException if n is negative.

Parameters:
n - the bit to modify

flipBit

public static XBigInteger flipBit(XBigInteger x,
                                  int n)

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

public final int compareTo(XBigInteger y)

Compares this XBigInteger with the specified XBigInteger y.

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.

Parameters:
y - the explicit argument
Throws:
NullPointerException - if y is null

compareTo

public final int compareTo(Object o)

Compares this XBigInteger with the specified Object o.

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 ClassCastException if the given object is null or is not of type XBigInteger. This is consistent with the specification of the interface Comparable which this method implements.

Specified by:
compareTo in interface Comparable
Parameters:
o - the Object to compare
Throws:
ClassCastException - if o is null or not of type XBigInteger

factorial

public static XBigInteger factorial(int n)

Returns factorial(n), that is, the product of the numbers from 1 to n.

This is equal to the number of permutations of a set of size n when n >= 0.

Returns 1 if n is 0 or 1 and returns 0 if n is negative.

Parameters:
n - the set size

binomial

public static XBigInteger binomial(int n,
                                   int k)

Returns the binomial coefficient for n, k.

When n >= k >= 0, this is equal to the number of subsets of size k in a set of size n.

Returns 1 if k is 0 and 0 if k is negative.

Computes: (n*...*(n-k+1)) / (k*...*1).

For k >= 0, the binomial coefficient is a polynomial of degree k in the parameter n. This polynomial is characterized by two conditions.

In particular, this polynomial has well-defined values when n is negative. These values are positive if k is even and negative if k is odd as is easily seen from the formula given above.

Parameters:
n - the set size
k - the subset size

toPrimitiveArray

public static BigInteger[] toPrimitiveArray(XBigInteger[] x)

Returns an array of BigInteger objects initialized from the given array of XBigInteger objects.

Parameters:
x - an array of XBigIntegers

toXArray

public static XBigInteger[] toXArray(BigInteger[] a)

Returns an array of XBigInteger objects initialized from the given array of BigInteger objects.

Parameters:
a - an array of BigIntegers