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
-
ident
-
-
BigInteger(byte[])
- Translates a byte array containing the two's-complement
representation of a (signed) integer into a BigInteger.
-
BigInteger(int, byte[])
- Translates the sign-magnitude representation of an integer into
a BigInteger.
-
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).
-
BigInteger(String)
- Translates a string containing an optional minus sign followed
by a sequence of one or more decimal digits into a BigInteger.
-
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.
-
abs()
- Returns a BigInteger whose value is the absolute value of this
number.
-
add(BigInteger)
- Returns a BigInteger whose value is (this + val).
-
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))).
-
compareTo(BigInteger)
- Returns -1, 0 or 1 as this number is less than, equal to, or
greater than val.
-
divide(BigInteger)
- Returns a BigInteger whose value is (this / val).
-
divideAndRemainder(BigInteger)
- Returns an array of two BigIntegers.
-
equals(Object)
- Returns true iff x is a BigInteger whose value is equal to this
number.
-
gcd(BigInteger)
- Returns a BigInteger whose value is the greatest common
denominator of abs(this) and abs(val).
-
integerDivide(int)
- Division by an integer.
-
max(BigInteger)
- Returns the BigInteger whose value is the greater of this and
val.
-
min(BigInteger)
- Returns the BigInteger whose value is the lesser of this and
val.
-
mod(BigInteger)
- Returns a BigInteger whose value is this mod m.
-
modInverse(BigInteger)
- Returns modular multiplicative inverse of this, mod m.
-
modPow(BigInteger, BigInteger)
- Returns a BigInteger whose value is (this ** exponent) mod m.
-
multiply(BigInteger)
- Returns a BigInteger whose value is (this * val).
-
negate()
- Returns a BigInteger whose value is (-1 * this).
-
pow(int)
- Returns a BigInteger whose value is (this ** exponent).
-
remainder(BigInteger)
- Returns a BigInteger whose value is (this % val).
-
shiftLeft(int)
- Returns a BigInteger whose value is (this << n).
-
shiftRight(int)
- Returns a BigInteger whose value is (this >> n).
-
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).
-
subtract(BigInteger)
- Returns a BigInteger whose value is (this - val).
-
toByteArray()
- Returns the two's-complement representation of this number.
-
toString()
- Returns the string representation of this number, radix 10.
-
toString(int)
- Returns the string representation of this number in the given
radix.
-
valueOf(long)
- Returns a BigInteger with the specified value.
ident
public final static String ident
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.
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).
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.
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.
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.
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.
add
public BigInteger add(BigInteger val) throws ArithmeticException
- Returns a BigInteger whose value is (this + val).
subtract
public BigInteger subtract(BigInteger val)
- Returns a BigInteger whose value is (this - val).
multiply
public BigInteger multiply(BigInteger val)
- Returns a BigInteger whose value is (this * val).
divide
public BigInteger divide(BigInteger val) throws ArithmeticException
- Returns a BigInteger whose value is (this / val). Throws an
ArithmeticException if val == 0.
remainder
public BigInteger remainder(BigInteger val) throws ArithmeticException
- Returns a BigInteger whose value is (this % val). Throws an
ArithmeticException if val == 0.
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.
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.
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.
abs
public BigInteger abs()
- Returns a BigInteger whose value is the absolute value of this
number.
negate
public BigInteger negate()
- Returns a BigInteger whose value is (-1 * this).
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).
mod
public BigInteger mod(BigInteger m)
- Returns a BigInteger whose value is this mod m. Throws an
ArithmeticException if m <= 0.
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.
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).
shiftLeft
public BigInteger shiftLeft(int n)
- Returns a BigInteger whose value is (this << n). (Computes
floor(this * 2**n).)
shiftRight
public BigInteger shiftRight(int n)
- Returns a BigInteger whose value is (this >> n). Sign extension
is performed. (Computes floor(this / 2**n).)
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.)
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.
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
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.
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.
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.)
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
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.)
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