Class au.net.aba.math.BigInteger
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class au.net.aba.math.BigInteger

java.lang.Object
   |
   +----au.net.aba.math.BigInteger

public class BigInteger
extends Object
A class that provides the capability of performing arithmetic on integers that exceed the size of the built-in Java data types. This class is a compatibility class for the JDK 1.1 BigInteger version.

Immutable arbitrary-precision integers. All operations behave as if BigIntegers were represented in two's-complement notation (like Java's primitive integer types). BigIntegers provide analogues to all of Java's primitive integer operators, and all relevant static methods from java.lang.Math. Additionally, BigIntegers provide operations for modular arithmetic, GCD calculation, primality testing, prime generation, single-bit manipulation, and a few other odds and ends.

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

Single-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 number with a different sign from the 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.

NOTE: Not all methods present in the real BigInteger are supported and differences in behaviour should be noted in the documentation.

See Also:
BigDecimal

Variable Index

 o ident

Constructor Index

 o BigInteger(byte[])
Translates a byte array containing the two's-complement representation of a (signed) integer into a BigInteger.
 o BigInteger(int, byte[])
Translates the sign-magnitude representation of an integer into a BigInteger.
 o BigInteger(int, SecureRandom)
Returns a random number uniformly distributed on [0, 2**numBits - 1] (assuming a fair source of random bits is provided in rndSrc).
 o BigInteger(String)
Translates a string containing an optional minus sign followed by a sequence of one or more decimal digits into a BigInteger.
 o BigInteger(String, int)
Translates a string containing an optional minus sign followed by a sequence of one or more digits in the specified radix into a BigInteger.

Method Index

 o abs()
Returns a BigInteger whose value is the absolute value of this number.
 o add(BigInteger)
Returns a BigInteger whose value is (this + val).
 o bitLength()
Returns the number of bits in the minimal two's-complement representation of this number, *excluding* a sign bit, i.e., (ceil(log2(this < 0 ? -this : this + 1))).
 o compareTo(BigInteger)
Returns -1, 0 or 1 as this number is less than, equal to, or greater than val.
 o divide(BigInteger)
Returns a BigInteger whose value is (this / val).
 o divideAndRemainder(BigInteger)
Returns an array of two BigIntegers.
 o equals(Object)
Returns true iff x is a BigInteger whose value is equal to this number.
 o gcd(BigInteger)
Returns a BigInteger whose value is the greatest common denominator of abs(this) and abs(val).
 o integerDivide(int)
Division by an integer.
 o max(BigInteger)
Returns the BigInteger whose value is the greater of this and val.
 o min(BigInteger)
Returns the BigInteger whose value is the lesser of this and val.
 o mod(BigInteger)
Returns a BigInteger whose value is this mod m.
 o modInverse(BigInteger)
Returns modular multiplicative inverse of this, mod m.
 o modPow(BigInteger, BigInteger)
Returns a BigInteger whose value is (this ** exponent) mod m.
 o multiply(BigInteger)
Returns a BigInteger whose value is (this * val).
 o negate()
Returns a BigInteger whose value is (-1 * this).
 o pow(int)
Returns a BigInteger whose value is (this ** exponent).
 o remainder(BigInteger)
Returns a BigInteger whose value is (this % val).
 o shiftLeft(int)
Returns a BigInteger whose value is (this << n).
 o shiftRight(int)
Returns a BigInteger whose value is (this >> n).
 o signum()
Returns the signum function of this number (i.e., -1, 0 or 1 as the value of this number is negative, zero or positive).
 o subtract(BigInteger)
Returns a BigInteger whose value is (this - val).
 o toByteArray()
Returns the two's-complement representation of this number.
 o toString()
Returns the string representation of this number, radix 10.
 o toString(int)
Returns the string representation of this number in the given radix.
 o valueOf(long)
Returns a BigInteger with the specified value.

Variables

 o ident
  public final static String ident

Constructors

 o BigInteger
  public BigInteger(byte val[]) throws NumberFormatException
Translates a byte array containing the two's-complement representation of a (signed) integer into a BigInteger. The input array is assumed to be big-endian (i.e., the most significant byte is in the [0] position). (The most significant bit of the most significant byte is the sign bit.) The array must contain at least one byte or a NumberFormatException will be thrown.
 o BigInteger
  public BigInteger(int signum,
                    byte magnitude[]) throws NumberFormatException
Translates the sign-magnitude representation of an integer into a BigInteger. The sign is represented as an integer signum value (-1 for negative, 0 for zero, 1 for positive). The magnitude is represented as a big-endian byte array (i.e., the most significant byte is in the [0] position). An invalid signum value or a 0 signum value coupled with a nonzero magnitude will result in a NumberFormatException. A zero length magnitude array is permissible, and will result in in a value of 0 (irrespective of the given signum value).
 o BigInteger
  public BigInteger(String val,
                    int radix) throws NumberFormatException
Translates a string containing an optional minus sign followed by a sequence of one or more digits in the specified radix into a BigInteger. The character-to-digit mapping is provided by Character.digit. Any extraneous characters (including whitespace), or a radix outside the range from Character.MIN_RADIX(2) to Character.MAX_RADIX(36), inclusive, will result in a NumberFormatException.
 o BigInteger
  public BigInteger(String val) throws NumberFormatException
Translates a string containing an optional minus sign followed by a sequence of one or more decimal digits into a BigInteger. The character-to-digit mapping is provided by Character.digit. Any extraneous characters (including whitespace) will result in a NumberFormatException.
 o BigInteger
  public BigInteger(int numBits,
                    SecureRandom rndSrc) throws IllegalArgumentException
Returns a random number uniformly distributed on [0, 2**numBits - 1] (assuming a fair source of random bits is provided in rndSrc). Note that this constructor always returns a non-negative BigInteger. Throws an IllegalArgumentException if numBits < 0.

Methods

 o valueOf
  public static BigInteger valueOf(long val)
Returns a BigInteger with the specified value. This factory is provided in preference to a (long) constructor because it allows for reuse of frequently used BigIntegers (like 0 and 1), obviating the need for exported constants.
 o add
  public BigInteger add(BigInteger val) throws ArithmeticException
Returns a BigInteger whose value is (this + val).
 o subtract
  public BigInteger subtract(BigInteger val)
Returns a BigInteger whose value is (this - val).
 o multiply
  public BigInteger multiply(BigInteger val)
Returns a BigInteger whose value is (this * val).
 o divide
  public BigInteger divide(BigInteger val) throws ArithmeticException
Returns a BigInteger whose value is (this / val). Throws an ArithmeticException if val == 0.
 o remainder
  public BigInteger remainder(BigInteger val) throws ArithmeticException
Returns a BigInteger whose value is (this % val). Throws an ArithmeticException if val == 0.
 o divideAndRemainder
  public BigInteger[] divideAndRemainder(BigInteger val) throws ArithmeticException
Returns an array of two BigIntegers. The first ([0]) element of the return value is the quotient (this / val), and the second ([1]) element is the remainder (this % val). Throws an ArithmeticException if val == 0.
 o pow
  public BigInteger pow(int exponent) throws ArithmeticException
Returns a BigInteger whose value is (this ** exponent). Throws an ArithmeticException if exponent < 0 (as the operation would yield a non-integer value). Note that exponent is an integer rather than a BigInteger.
 o gcd
  public BigInteger gcd(BigInteger val)
Returns a BigInteger whose value is the greatest common denominator of abs(this) and abs(val). Returns 0 if this == 0 && val == 0.
 o abs
  public BigInteger abs()
Returns a BigInteger whose value is the absolute value of this number.
 o negate
  public BigInteger negate()
Returns a BigInteger whose value is (-1 * this).
 o signum
  public int signum()
Returns the signum function of this number (i.e., -1, 0 or 1 as the value of this number is negative, zero or positive).
 o mod
  public BigInteger mod(BigInteger m)
Returns a BigInteger whose value is this mod m. Throws an ArithmeticException if m <= 0.
 o modPow
  public BigInteger modPow(BigInteger exponent,
                           BigInteger m)
Returns a BigInteger whose value is (this ** exponent) mod m. (If exponent == 1, the returned value is (this mod m). If exponent < 0, the returned value is the modular multiplicative inverse of (this ** -exponent).) Throws an ArithmeticException if m <= 0.

NOTE: there is no support for negative exponents.

 o modInverse
  public BigInteger modInverse(BigInteger m) throws ArithmeticException
Returns modular multiplicative inverse of this, mod m. Throws an ArithmeticException if m <= 0 or this has no multiplicative inverse mod m (i.e., gcd(this, m) != 1).
 o shiftLeft
  public BigInteger shiftLeft(int n)
Returns a BigInteger whose value is (this << n). (Computes floor(this * 2**n).)
 o shiftRight
  public BigInteger shiftRight(int n)
Returns a BigInteger whose value is (this >> n). Sign extension is performed. (Computes floor(this / 2**n).)
 o bitLength
  public int bitLength()
Returns the number of bits in the minimal two's-complement representation of this number, *excluding* a sign bit, i.e., (ceil(log2(this < 0 ? -this : this + 1))). (For positive numbers, this is equivalent to the number of bits in the ordinary binary representation.)
 o compareTo
  public int compareTo(BigInteger val)
Returns -1, 0 or 1 as this number is less than, equal to, or greater than val. 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) 0), where is one of the six comparison operators.
 o equals
  public boolean equals(Object x)
Returns true iff x is a BigInteger whose value is equal to this number. This method is provided so that BigIntegers can be used as hash keys.
Overrides:
equals in class Object
 o min
  public BigInteger min(BigInteger val)
Returns the BigInteger whose value is the lesser of this and val. If the values are equal, either may be returned.
 o max
  public BigInteger max(BigInteger val)
Returns the BigInteger whose value is the greater of this and val. If the values are equal, either may be returned.
 o toString
  public String toString(int radix)
Returns the string representation of this number in the given radix. If the radix is outside the range from Character.MIN_RADIX(2) to Character.MAX_RADIX(36) 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.)
 o toString
  public String toString()
Returns the string representation of this number, radix 10. 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, and allows for string concatenation with Java's + operator.)
Overrides:
toString in class Object
 o toByteArray
  public byte[] toByteArray()
Returns the two's-complement representation of this number. The array is big-endian (i.e., the most significant byte is in the [0] position). The array contains the minimum number of bytes required to represent the number (ceil((this.bitLength() + 1)/8)). (This representation is compatible with the (byte[]) constructor.)
 o integerDivide
  public BigInteger[] integerDivide(int value)
Division by an integer.
Parameters:
value - the long to be divided by.
Returns:
two BigIntegers, the first being the result of the division, the second being the remainder.

All Packages  Class Hierarchy  This Package  Previous  Next  Index