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:


Variable Index

 o NO_ROUNDING
 o ONE
 o ROUND_ABOVE_4
 o ROUND_ABOVE_5
 o ROUND_ALWAYS
 o ROUND_STATISTICAL
 o TWO
 o ZERO

Constructor Index

 o Bignum(Bignum)
Construct a Bignum from another Bignum.
 o Bignum(Bignum, int)
Given an existing Bignum and an integer scale value, construct a new Bignum with the scale adjusted accordingly.
 o Bignum(double, int)
Construct a Bignum from a double given a double value and an integer scale.
 o Bignum(int)
Construct a Bignum from an integer given an integer value.
 o Bignum(int, int)
Construct a Bignum from an integer given an integer value and an integer scale.
 o Bignum(long)
Construct a Bignum from a long integer given a long integer value.
 o Bignum(long, int)
Construct a Bignum from a long integer given a long value and an integer scale.
 o Bignum(String)
Creates a Bignum from a string.
 o Bignum(String, int)
Construct a Bignum given a String and an integer scale.

Method Index

 o add(Bignum)
Returns the arithmetic sum of the Bignum and the argument.
 o compare(Bignum)
Compare the value of this Bignum to the value of the argument.
 o createFromByteArray(byte[])
Return a Bignum created from the given byte array.
 o createFromIntegerArray(int[])
Return a Bignum created from the given Integer array.
 o createFromRadixString(String, int)
Return a Bignum created from the given string and radix.
 o createFromScaled(long, int)
Return a Bignum value created by dividing the argument by 10**scale.
 o divide(Bignum)
Returns the arithmetic quotient calculated by dividing the Bignum by the argument.
 o doubleValue()
Convert the Bignum value to a double.
 o equals(Object)
Returns true if the arithmetic value of the Bignum equals the argument.
 o floatValue()
Convert the Bignum value to a float.
 o getRoundingOption()
Returns the current rounding option for all Bignum's in this program.
 o getScale()
Return the number of digits to the right of the decimal point.
 o greaterThan(Bignum)
Returns true if the arithmetic value of the Bignum is greater than the argument.
 o greaterThanOrEquals(Bignum)
Returns true if the arithmetic value of the Bignum is greater than or equals the argument.
 o hashCode()
Returns an integer hashcode for the Bignum.
 o integerDivide(Bignum)
Returns an array of two Bignum objects.
 o intValue()
Convert the Bignum value an int.
 o 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.
 o lessThan(Bignum)
Returns true if the arithmetic value of the Bignum is less than the argument.
 o lessThanOrEquals(Bignum)
Returns true if the arithmetic value of the Bignum is less than or equals the argument.
 o longValue()
Convert the Bignum value to a long.
 o modExp(Bignum, Bignum)
Modular exponentiation.
 o modInverse(Bignum)
Returns the modular multiplicative inverse of this Bignum
 o multiply(Bignum)
Returns the arithmetic product of the object Bignum and the argument.
 o pow(int)
Returns a new Bignum whose value is calculated by raising this Bignum to the power of the given exponent.
 o 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.
 o remainder(Bignum)
Returns the arithmentic remainder calculated by dividing this Bignum object by the argument.
 o setRoundingOption(int)
Sets the rounding option for all Bignum's in a program; the default rounding option is ROUND_ABOVE_4.
 o setScale(int)
Returns a Bignum copied from the current object with the scale set as specified by the argument.
 o shiftLeft(int)
Returns a new Bignum calculated by shifting this Bignum to the left by the number of bits given in shiftBits.
 o 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
 o significantBits()
Returns the number of significant bits in the Bignum.
 o sqrt()
Square root Returns the square root of this Bignum.
 o subtract(Bignum)
Returns the arithmetic difference between the Bignum and the argument.
 o toByteArray()
Returns a byte array derived from the value of the numeric.
 o toString()
Convert the Bignum value to a String.
 o toString(int)
Returns a String representation of the Bignum in the given radix.
 o truncate(Bignum)
Returns a new Bignum whose value equals the integer part of the input argument.

Variables

 o ROUND_STATISTICAL
  public final static int ROUND_STATISTICAL
 o NO_ROUNDING
  public final static int NO_ROUNDING
 o ROUND_ABOVE_5
  public final static int ROUND_ABOVE_5
 o ROUND_ABOVE_4
  public final static int ROUND_ABOVE_4
 o ROUND_ALWAYS
  public final static int ROUND_ALWAYS
 o ZERO
  public final static Bignum ZERO
 o ONE
  public final static Bignum ONE
 o TWO
  public final static Bignum TWO

Constructors

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

Methods

 o 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.
 o getRoundingOption
  public static int getRoundingOption()
Returns the current rounding option for all Bignum's in this program.
Returns:
current rounding option
 o 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.
 o 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
 o 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.
 o 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.
 o 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.
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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.
 o 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.
 o 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.
 o 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.
 o 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.
 o 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.
 o 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.
 o sqrt
  public Bignum sqrt()
Square root Returns the square root of this Bignum.
Returns:
the square root of this Bignum.
 o 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.
 o 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
 o 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.
 o 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.
 o 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.
 o 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.
 o hashCode
  public int hashCode()
Returns an integer hashcode for the Bignum.
Returns:
The hashcode as an integer.
Overrides:
hashCode in class Object
 o 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
 o 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.
 o 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
 o 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
 o 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
 o 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".
 o 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.
 o 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.
 o 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