Class java.lang.Bignum
All Packages Class Hierarchy This Package Previous Next Index
Class java.lang.Bignum
java.lang.Object
|
+----java.lang.Number
|
+----java.lang.Bignum
- public final class Bignum
- extends Number
The Bignum class represents fixed point numbers of practically
unlimited precision. The size of each instance depends on the
number of digits it represents(its precision). The precision of an
instance's fractional part is determined by its scale.
The rounding behaviors needed for business and scientific
computation often differ. To meet this requirement, the rounding
behavior for the class as a whole can be changed.
The Bignum class should be used for values that require high
precision fixed point or integer computation. Examples of this are
money values, security key values and values stored in databases
using the high precision SQL NUMERIC or DECIMAL type.
Calculations on Bignum objects always return a new Bignum object
with the same scale as the Bignum that performed the
calculation. Most operations are carried out to one extra decimal
place and rounded to the desired scale.
Bignum's are immutable and thread-safe.
Since Bignum values with 10's of thousands of digits can be
represented, the practical limit to their precision is the space
and time needed to work with them. The max scale value is max int;
the max precision of this implementation is limited only by Java's
maximum array size.
Bignum objects are composed of three properties:
- Scale: The number of digits to the right of the decimal point.
- Sign: Positive or negative.
- Value: In this implementation, a vector of integer digits of radix 2^30.
-
NO_ROUNDING
-
-
ONE
-
-
ROUND_ABOVE_4
-
-
ROUND_ABOVE_5
-
-
ROUND_ALWAYS
-
-
ROUND_STATISTICAL
-
-
TWO
-
-
ZERO
-
-
Bignum(Bignum)
- Construct a Bignum from another Bignum.
-
Bignum(Bignum, int)
- Given an existing Bignum and an integer scale value, construct
a new Bignum with the scale adjusted accordingly.
-
Bignum(double, int)
- Construct a Bignum from a double given a double value and an
integer scale.
-
Bignum(int)
- Construct a Bignum from an integer given an integer value.
-
Bignum(int, int)
- Construct a Bignum from an integer given an integer value and
an integer scale.
-
Bignum(long)
- Construct a Bignum from a long integer given a long integer value.
-
Bignum(long, int)
- Construct a Bignum from a long integer given a long value and
an integer scale.
-
Bignum(String)
- Creates a Bignum from a string.
-
Bignum(String, int)
- Construct a Bignum given a String and an integer scale.
-
add(Bignum)
- Returns the arithmetic sum of the Bignum and the argument.
-
compare(Bignum)
- Compare the value of this Bignum to the value of the argument.
-
createFromByteArray(byte[])
- Return a Bignum created from the given byte array.
-
createFromIntegerArray(int[])
- Return a Bignum created from the given Integer array.
-
createFromRadixString(String, int)
- Return a Bignum created from the given string and radix.
-
createFromScaled(long, int)
- Return a Bignum value created by dividing the argument by
10**scale.
-
divide(Bignum)
- Returns the arithmetic quotient calculated by dividing the
Bignum by the argument.
-
doubleValue()
- Convert the Bignum value to a double.
-
equals(Object)
- Returns true if the arithmetic value of the Bignum equals the
argument.
-
floatValue()
- Convert the Bignum value to a float.
-
getRoundingOption()
- Returns the current rounding option for all Bignum's in this
program.
-
getScale()
- Return the number of digits to the right of the decimal point.
-
greaterThan(Bignum)
- Returns true if the arithmetic value of the Bignum is greater
than the argument.
-
greaterThanOrEquals(Bignum)
- Returns true if the arithmetic value of the Bignum is greater
than or equals the argument.
-
hashCode()
- Returns an integer hashcode for the Bignum.
-
integerDivide(Bignum)
- Returns an array of two Bignum objects.
-
intValue()
- Convert the Bignum value an int.
-
isProbablePrime()
- This method tests for primality, first by attempting to divide
by a few small primes, then by using the Rabin probabilistic
primality test 50 times.
-
lessThan(Bignum)
- Returns true if the arithmetic value of the Bignum is less
than the argument.
-
lessThanOrEquals(Bignum)
- Returns true if the arithmetic value of the Bignum is less
than or equals the argument.
-
longValue()
- Convert the Bignum value to a long.
-
modExp(Bignum, Bignum)
- Modular exponentiation.
-
modInverse(Bignum)
- Returns the modular multiplicative inverse of this Bignum
-
multiply(Bignum)
- Returns the arithmetic product of the object Bignum and the
argument.
-
pow(int)
- Returns a new Bignum whose value is calculated by
raising this Bignum to the power of the given exponent.
-
random(int, Random)
- Random number generator
Returns a random number using randomSeed as a seed and with a number of bits of up to bitSize.
-
remainder(Bignum)
- Returns the arithmentic remainder calculated by dividing this
Bignum object by the argument.
-
setRoundingOption(int)
- Sets the rounding option for all Bignum's in a program; the
default rounding option is ROUND_ABOVE_4.
-
setScale(int)
- Returns a Bignum copied from the current object with the scale
set as specified by the argument.
-
shiftLeft(int)
- Returns a new Bignum calculated by shifting this Bignum to the
left by the number of bits given in shiftBits.
-
shiftRight(int)
- Returns a new Bignum whose value is calculated by shifting this
Bignum to the left by the number of bits given in shiftBits
-
significantBits()
- Returns the number of significant bits in the Bignum.
-
sqrt()
- Square root
Returns the square root of this Bignum.
-
subtract(Bignum)
- Returns the arithmetic difference between the Bignum and the
argument.
-
toByteArray()
- Returns a byte array derived from the value of the numeric.
-
toString()
- Convert the Bignum value to a String.
-
toString(int)
- Returns a String representation of the Bignum in the given radix.
-
truncate(Bignum)
- Returns a new Bignum whose value equals the
integer part of the input argument.
ROUND_STATISTICAL
public final static int ROUND_STATISTICAL
NO_ROUNDING
public final static int NO_ROUNDING
ROUND_ABOVE_5
public final static int ROUND_ABOVE_5
ROUND_ABOVE_4
public final static int ROUND_ABOVE_4
ROUND_ALWAYS
public final static int ROUND_ALWAYS
ZERO
public final static Bignum ZERO
ONE
public final static Bignum ONE
TWO
public final static Bignum TWO
Bignum
public Bignum(String s)
- Creates a Bignum from a string. The string may contain a sign
and a decimal point, e.g "-55.12". Spaces and other
non-numeric characters are ignored. Scientific notation, i.e.
mantissa with exponent (3E.05) is supported.
- Parameters:
- s - the string used to initialize the Bignum.
Bignum
public Bignum(String s,
int scale)
- Construct a Bignum given a String and an integer scale. The
scale represents the desired number of places to the right of
the decimal point.
The String may contain a sign and a decimal point,
e.g. "-55.12". Spaces and other non-numeric characters are
ignored. Scientific notation, i.e. mantissa with exponent
(3E.05) is supported. The scale must be an integer with value
greater than or equal to zero. If the scale differs from the
implicit decimal point given in the String the value is
adjusted to the given scale. This may involve rounding.
For example, Bignum("99.995",2) would result in a Bignum
with a scale of 2 and a value of "100.00". If the String
contains no decimal point, then the scale is determined solely
by the given integer scale. No implicit decimal point is
assumed. For example, the constructor Bignum("123",2) creates
a Bignum with a scale of 2 and a value of
"123.00".
Note: Rounding is controlled by the roundingIndex
function.
- Parameters:
- s - the string used to initialize the Bignum.
- scale - the value greater than or equal to zero
representing the desired number of digits to the right of the
decimal point.
Bignum
public Bignum(int x,
int scale)
- Construct a Bignum from an integer given an integer value and
an integer scale. The scale is set to the value specified. No
implicit decimal point is assumed, i.e., if the integer value is
"1234" and the scale 2, the resulting Bignum will be "1234.00.
- Parameters:
- x - The int used to initialize the new Bignum.
- scale - The desired number of digits after the decimal point.
Bignum
public Bignum(int x)
- Construct a Bignum from an integer given an integer value.
The scale is set to zero.
- Parameters:
- x - The long used to initialize the new Bignum.
Bignum
public Bignum(long x,
int scale)
- Construct a Bignum from a long integer given a long value and
an integer scale. The scale is set to the value specified. No
implicit decimal point is assumed, i.e., if the long value is
"1234" and the scale 2, the resulting Bignum will be "1234.00.
- Parameters:
- x - The long value used to initialize the new Bignum.
- scale - The desired number of digits after the decimal point.
Bignum
public Bignum(long x)
- Construct a Bignum from a long integer given a long integer value.
The scale is set to zero.
- Parameters:
- x - The long used to initialize the new Bignum.
Bignum
public Bignum(double x,
int scale)
- Construct a Bignum from a double given a double value and an
integer scale. The scale is set to the value specified. No
implicit decimal point is assumed, i.e., if the double value is
"1234" and the scale 2, the resulting Bignum will be "1234.00.
If the double value is "1234.5" and the scale 2 the value will
be "1234.50". Rounding may occur during this conversion.
- Parameters:
- x - The double value used to initialize the new Bignum.
- scale - The desired number of digits after the decimal point.
Bignum
public Bignum(Bignum x)
- Construct a Bignum from another Bignum. The
scale and value of the new Bignum are copied from the Bignum
given in the argument.
- Parameters:
- x - The Bignum used to initialize the new Bignum.
Bignum
public Bignum(Bignum x,
int scale)
- Given an existing Bignum and an integer scale value, construct
a new Bignum with the scale adjusted accordingly. The
scale and value of the new Bignum are copied from
the argument Bignum. The scale is then adjusted to the scale
given as a parameter. This may result in rounding of the value.
- Parameters:
- x - The Bignum to copy.
- scale - An integer representing the desired * scale of the
new Bignum.
setRoundingOption
public static void setRoundingOption(int val)
- Sets the rounding option for all Bignum's in a program; the
default rounding option is ROUND_ABOVE_4.
All Bignum computation is done using an extra digit of
precision which is truncated prior to returning the result. The
rounding option determines how the value of this extra digit
affects the returned value. Rounding also applies when the
scale of a Bignum is reduced; here, rounding defines how the
value of the most significant truncated digit affects the
result.
If rounding causes the least signifcant digit of a result to
be incremented by 1, we say the result has been 'rounded up'. If
the least signficant digit of a result is left as is, we say the
result has been 'rounded down'.
The following rounding options are provided:
- NO_ROUNDING:
- All results are rounded down regardless
of the value of the most significant truncated digit.
For example, 1.999 would round to 1.99.
- ROUND_ABOVE_4:
- If the value of the most significant truncated
digit is > 4, the result is rounded up; otherwise,
the result is rounded down. For example, 1.994 would
round down to 1.99 and 1.995 would round up to 2.00
- ROUND_ABOVE_5:
- If the value of the most significant truncated
digit is > 5, the result is rounded up; otherwise,
the result is rounded down. For example, 1.995 would
round down to 1.99 and 1.996 would round up to 2.00.
- ROUND_ALWAYS :
- If the value of the most significant truncated
digit is > 0, the result is rounded up; otherwise,
the result is rounded down. For example, 1.990 would
round down to 1.99 and 1.991 would round up to 2.00.
- ROUND_STATISTICAL :
- If the value of the most significant truncated
digit is > 5, the result is rounded up. If the value
of the most significant truncated digit is < 5, the
result is rounded down. If the value of the most
significant truncated digit is = 5, the result is
rounded down if the remaining least significant digit
is even; if it's odd the result is rounded up.
For example, 1.994 would round down to 1.99; 1.996 would
round up to 2.00; 1.985 would round down to 1.98; and, 1.995
would round up to 2.00. This option is used to help reduce
systematic rounding bias. See Bevington and Robinson,
'Data Reduction and Error Analysis for the Physical Sciences',
pp. 4, McGraw Hill, Inc., (1992).
- Parameters:
- val - The rounding option to use for all Bignum's.
getRoundingOption
public static int getRoundingOption()
- Returns the current rounding option for all Bignum's in this
program.
- Returns:
- current rounding option
createFromByteArray
public static Bignum createFromByteArray(byte byteArray[])
- Return a Bignum created from the given byte array.
The array is treated as a string of bits representing an unsigned
integer, with the most significant bit at the 0th position. This
function is supplied to simplify and optimize operations in
algorithms using large integers, such as hashing calculations.
- Parameters:
- byteArray - An array of bytes holding the bitstring value of
the desired Bignum.
- Returns:
- A new Bignum whose value is determined by the given byte array.
toByteArray
public byte[] toByteArray()
- Returns a byte array derived from the value of the numeric.
The array is considered a string of bits with the most significant bit
at the 0th position.This function should be used with great caution.
It is supplied to simplify and optimize calculations in algorithms that
used hashing calculations, e.g. many security algorithms.
- Returns:
- s A byte array derived from the value of the Bignum
createFromIntegerArray
public static Bignum createFromIntegerArray(int intArray[])
- Return a Bignum created from the given Integer array.
The array is considered a string of bits with the least significant bit
at the 0th position. This function should be used with great caution.
It is supplied to simplify and optimize calculations in algorithms that
used hashing calculations, e.g. many security algorithms.
- Parameters:
- intArray - An array of integers holding the desired value of the new Bignum.
- Returns:
- A new Bignum whose value is determined by the given integer array.
createFromScaled
public static Bignum createFromScaled(long scaled,
int s)
- Return a Bignum value created by dividing the argument by
10**scale. Thus, createFromScaled(504,2) would create the
value "5.04". A negative scale throws an IllegalArgumentException.
- Parameters:
- scaled - The scaled value as a long.
- s - The desired scale value
- Returns:
- A new Bignum.
createFromRadixString
public static Bignum createFromRadixString(String s,
int radix)
- Return a Bignum created from the given string and radix.
Decimal places are ignored and the scale is set to zero.
The string may contain a sign.
- Parameters:
- s - A string containing the intended value of the Bignum.
- radix - The base of the string representation.
- Returns:
- A new Bignum whose value is given by the string argument.
random
public static Bignum random(int bits,
Random randomSeed)
- Random number generator
Returns a random number using randomSeed as a seed and with a number of bits of up to bitSize.
- Parameters:
- bitSize - The position of the most significant bit in the random number
- randomSeed - a Random number used as the seed for the random number generated
- Returns:
- a new Bignum of maximium size bitSize
intValue
public int intValue()
- Convert the Bignum value an int.
This conversion may result in a loss of precision. Digits
after the decimal point are dropped.
- Returns:
- An int value representation of the Bignum.
- Overrides:
- intValue in class Number
longValue
public long longValue()
- Convert the Bignum value to a long.
This conversion may result in a loss of precision. Digits
after the decimal point are dropped.
- Returns:
- A long value representation of the Bignum.
- Overrides:
- longValue in class Number
floatValue
public float floatValue()
- Convert the Bignum value to a float.
This conversion may result in a loss of precision.
- Returns:
- A float value representation of the Bignum.
- Overrides:
- floatValue in class Number
doubleValue
public double doubleValue()
- Convert the Bignum value to a double.
This conversion may result in a loss of precision.
- Returns:
- A double value representation of the Bignum.
- Overrides:
- doubleValue in class Number
toString
public String toString()
- Convert the Bignum value to a String.
Negative numbers are represented by a leading "-". No sign is
added for positive numbers.
- Returns:
- A String representation of the Bignum.
- Overrides:
- toString in class Object
toString
public String toString(int radix)
- Returns a String representation of the Bignum in the given radix.
In this version scaling is ignored for any radix other than 10.
- Parameters:
- radix - the base of the number to be returned
- Returns:
- a String representation of the Bignum in the given radix
getScale
public int getScale()
- Return the number of digits to the right of the decimal point.
- Returns:
- An integer value representing the number of decimal
places to the right of the decimal point.
add
public Bignum add(Bignum n)
- Returns the arithmetic sum of the Bignum and the argument.
The scale of the sum is determined by this object not by the
argument. The calculation is performed using a
scale equal to the greater scale of the two operands. Rounding is
applied to the result.
- Parameters:
- n - The Bignum to add.
- Returns:
- The sum as a Bignum.
subtract
public Bignum subtract(Bignum n)
- Returns the arithmetic difference between the Bignum and the
argument. The scale of the difference is determined by this object
not by the argument. The calculation is performed using a
scale equal to the greater scale of the two operands. Rounding is
applied to the result.
- Parameters:
- n - The Bignum to subtract.
- Returns:
- The difference as a Bignum.
multiply
public Bignum multiply(Bignum x)
- Returns the arithmetic product of the object Bignum and the
argument. The scale of the product is determined by this object
not by the argument.
- Parameters:
- x - The multiplier as a Bignum.
- Returns:
- The product as a Bignum.
divide
public Bignum divide(Bignum x)
- Returns the arithmetic quotient calculated by dividing the
Bignum by the argument. The scale of the quotient is
determined by this object not by the argument.
- Parameters:
- x - The divisor as a Bignum.
- Returns:
- The quotient as a Bignum.
integerDivide
public Bignum[] integerDivide(Bignum x)
- Returns an array of two Bignum objects. The first element in
the array holds the quotient value resulting from the arithmetic
division of this Bignum object by the argument. The second element
in the array holds the remainder.
- Parameters:
- x - The divisor as a Bignum.
- Returns:
- An array of two Bignum objects containing the quotient and
remainder of the division.
remainder
public Bignum remainder(Bignum x)
- Returns the arithmentic remainder calculated by dividing this
Bignum object by the argument. No rounding is performed.
- Parameters:
- x - The divisor as a Bignum.
- Returns:
- The remainder as a Bignum.
sqrt
public Bignum sqrt()
- Square root
Returns the square root of this Bignum.
- Returns:
- the square root of this Bignum.
pow
public Bignum pow(int e)
- Returns a new Bignum whose value is calculated by
raising this Bignum to the power of the given exponent.
- Parameters:
- e - An integer value cotaining the exponent to be used.
- Returns:
- this Bignum raised to the power given by the exponent argument.
equals
public boolean equals(Object obj)
- Returns true if the arithmetic value of the Bignum equals the
argument.
- Parameters:
- obj - The object to compare.
- Returns:
- The boolean result of the comparison.
- Overrides:
- equals in class Object
lessThan
public boolean lessThan(Bignum x)
- Returns true if the arithmetic value of the Bignum is less
than the argument.
- Parameters:
- x - The object to compare.
- Returns:
- The boolean result of the comparison.
lessThanOrEquals
public boolean lessThanOrEquals(Bignum x)
- Returns true if the arithmetic value of the Bignum is less
than or equals the argument.
- Parameters:
- x - The object to compare.
- Returns:
- The boolean result of the comparison.
greaterThan
public boolean greaterThan(Bignum x)
- Returns true if the arithmetic value of the Bignum is greater
than the argument.
- Parameters:
- x - The object to compare.
- Returns:
- The boolean result of the comparison.
greaterThanOrEquals
public boolean greaterThanOrEquals(Bignum x)
- Returns true if the arithmetic value of the Bignum is greater
than or equals the argument.
- Parameters:
- x - The object to compare.
- Returns:
- The boolean result of the comparison.
hashCode
public int hashCode()
- Returns an integer hashcode for the Bignum.
- Returns:
- The hashcode as an integer.
- Overrides:
- hashCode in class Object
setScale
public Bignum setScale(int scale)
- Returns a Bignum copied from the current object with the scale
set as specified by the argument. Note that changing the scale
to a smaller value may result in rounding.
- Parameters:
- scale - the character to be converted
- Returns:
- A Bignum with the adjusted scale.
- See Also:
- setRoundingOption
significantBits
public int significantBits()
- Returns the number of significant bits in the Bignum.
- Returns:
- an integer containing the number of the most significant bit
of this Bignum.
shiftRight
public Bignum shiftRight(int shiftBits)
- Returns a new Bignum whose value is calculated by shifting this
Bignum to the left by the number of bits given in shiftBits
- Parameters:
- shiftBits - the number of bits to shift.
- Returns:
- A new Bignum whose value is this Bignum / 2^shiftBits
shiftLeft
public Bignum shiftLeft(int shiftBits)
- Returns a new Bignum calculated by shifting this Bignum to the
left by the number of bits given in shiftBits.
@param shiftBits The number of bits to shift
@return A new Bignum whose value is this Bignum * 2^shiftBits
modInverse
public Bignum modInverse(Bignum mod)
- Returns the modular multiplicative inverse of this Bignum
- Parameters:
- mod - the modulus to be used
- Returns:
- the modular multiplicative inverse of this Bignum using "mod" as
the modulus
modExp
public Bignum modExp(Bignum exponent,
Bignum mod)
- Modular exponentiation. Calculates a new Bignum
- Parameters:
- exponent - the exponent to be used
- mod - the modulus to be used
- Returns:
- a new Bignum whose values is this^exponent mod "mod".
isProbablePrime
public boolean isProbablePrime()
- This method tests for primality, first by attempting to divide
by a few small primes, then by using the Rabin probabilistic
primality test 50 times. The probability of failing this test
is less than 1 / (4^n).
- Returns:
- a boolean, true if this Bignum is probably prime, false
otherwise.
compare
public int compare(Bignum B)
- Compare the value of this Bignum to the value of the argument.
Returns 1 if this is greater than the argument,
-1 if this is less than the argument,
0 if this is equal to the argument.
- Parameters:
- B - A Bignum to compare.
- Returns:
- 1 if this > B,0 if this = B,-1 if this < B.
truncate
public static Bignum truncate(Bignum in)
- Returns a new Bignum whose value equals the
integer part of the input argument. The fractional part, if any,
is dropped.
- Parameters:
- Bignum - The input value to truncate
- Returns:
- s A new Bignum equal to the integer value of the argument
All Packages Class Hierarchy This Package Previous Next Index