Class java.sql.Numeric
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class java.sql.Numeric

java.lang.Object
   |
   +----java.lang.Number
           |
           +----java.sql.Numeric

public final class Numeric
extends Number
The Numeric class represents arbitrary precision and scale numbers. It performs fixed point arithmetic.

The Numeric 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.

The scale of Numeric objects may be declared arbitrarily large. Calculations on Numeric objects always return a new Numeric object with the same scale as the Numeric that performed the calculation. Most operations are carried out to one extra decimal place and rounded to the desired scale. Rounding behavior for the class as a whole is controlled by changing the classes Rounding Value.

Numeric objects are composed of three properties:


Variable Index

 o ONE
 o ZERO

Constructor Index

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

Method Index

 o add(Numeric)
Returns the arithmetic sum of the Numeric and the argument.
 o createFromByteArray(byte[])
Return a Numeric created from the given byte array.
 o createFromIntegerArray(int[])
Return a Numeric created from the given byte array.
 o createFromRadixString(String, int)
Return a Numeric created from the given string and radix.
 o createFromScaled(long, int)
Return a numeric value created by dividing the argument by 10**scale.
 o divide(Numeric)
Returns the arithmentic quotient calculated by dividing the Numeric by the argument.
 o doubleValue()
Convert the Numeric value to the Java built-in type of double.
 o equals(Object)
Returns true if the arithmetic value of the Numeric equals the argument.
 o floatValue()
Convert the Numeric value to the Java built-in type of float.
 o getRoundingValue()
Returns the value of the roundingValue which is used in rounding operations.
 o getScale()
Return the number of digits to the right of the decimal point.
 o getScaled()
Return the value multiplied by 10**scale.
 o greaterThan(Numeric)
Returns true if the arithmetic value of the Numeric is greater than the argument.
 o greaterThanOrEquals(Numeric)
Returns true if the arithmetic value of the Numeric is greater than or equals the argument.
 o hashCode()
Returns an integer hashcode for the Numeric.
 o integerDivide(Numeric)
Returns an array of two Numeric objects.
 o intValue()
Convert the Numeric value to the Java built-in type of 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 time.
 o lessThan(Numeric)
Returns true if the arithmetic value of the Numeric is less than the argument.
 o lessThanOrEquals(Numeric)
Returns true if the arithmetic value of the Numeric is less than or equals the argument.
 o longValue()
Convert the Numeric value to the Java built-in type of long.
 o modExp(Numeric, Numeric)
Modular exponentiation.
 o modInverse(Numeric)
Returns the modular multiplicative inverse of this Numeric
 o multiply(Numeric)
Returns the arithmetic product of the object Numeric and the argument.
 o pi(int)
Returns pi to the number of places given by the argument.
 o pow(int)
Returns a new Numeric whose value is calculated by raising this numeric the the power of the given exponent.
 o random(int, Random)
Random number generator Returns a random number using randomSeed as a seed and of a size having a maximimum size in bits equal to bitSize.
 o remainder(Numeric)
Returns the arithmentic remainder calculated by dividing this Numeric object by the argument.
 o setRoundingValue(int)
Sets the value of the roundingValue which is used in rounding operations.
 o setScale(int)
Returns a numeric copied from the current object with the scale adjusted as specified by the argument.
 o shiftLeft(int)
Shift Left.
 o shiftRight(int)
Shift Right.
 o significantBits()
Returns the number of significant bits in the Numeric.
 o sqrt()
Square root Returns the square root of this Numeric.
 o subtract(Numeric)
Returns the arithmetic difference between the Numeric and the argument.
 o toString()
Convert the Numeric value to the Java built-in type of String.
 o toString(int)
Returns a String representation of the numeric in the given radix.

Variables

 o ZERO
  public final static Numeric ZERO
 o ONE
  public final static Numeric ONE

Constructors

 o Numeric
  public Numeric(String s)
Creates a numeric 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 Numeric.
 o Numeric
  public Numeric(String s,
                 int scale)
Construct a Numeric 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". 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, Numeric("99.995",2) would result in a numeric 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 Numeric("123",2) creates a Numeric 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 Numeric.
scale - the value greater than or equal to zero representing the desired number of digits to the right of the decimal point.
 o Numeric
  public Numeric(int x,
                 int scale)
Construct a Numeric 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 numeric will be "1234.00.
Parameters:
x - The int used to initialize the new Numeric.
scale - The desired number of digits after the decimal point.
 o Numeric
  public Numeric(int x)
Construct a Numeric from an integer given an integer value. The scale is set to zero.
Parameters:
x - The int used to initialize the new Numeric.
 o Numeric
  public Numeric(long x,
                 int scale)
Construct a Numeric 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 numeric will be "1234.00.
Parameters:
x - The long value used to initialize the new Numeric.
scale - The desired number of digits after the decimal point.
 o Numeric
  public Numeric(long x)
Construct a Numeric from an integer given an integer value. The scale is set to zero.
Parameters:
x - The int used to initialize the new Numeric.
 o Numeric
  public Numeric(double x,
                 int scale)
Construct a Numeric 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 numeric 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 Numeric.
scale - The desired number of digits after the decimal point.
 o Numeric
  public Numeric(Numeric x)
Construct a Numeric from another Numeric. The scale and value of the new Numeric are copied from the Numeric given in the argument.
Parameters:
x - The Numeric used to initialize the new Numeric.
 o Numeric
  public Numeric(Numeric x,
                 int scale)
Given an existing Numeric and an integer scale value, construct a new Numeric with the scale adjusted accordingly. The scale and value of the new Numeric are copied from the argument Numeric. The scale is then adjusted to the scale given as a parameter. This may result in rounding of the value.
Parameters:
x - The Numeric to copy.
scale - An integer representing the desired * scale of the new Numeric.

Methods

 o setRoundingValue
  public static void setRoundingValue(int val)
Sets the value of the roundingValue which is used in rounding operations. The roundingValue is a digit between 0 and 9 that determines rounding behavior. When the scale of a Numeric is reduced either by request or in a calculation, rounding is performed if the value of the scale + 1 digit to the right of the decimal point is greater than the rounding index.

For example, if the number is 1.995, and the scale is set to 2 and the roundingValue is 4, then the number would be rounded to 2.00. The default roundingValue is 4. A roundingValue of 9 cancels rounding.

Parameters:
val - The value between 0 and 9 of the desired roundingValue.
 o getRoundingValue
  public static int getRoundingValue()
Returns the value of the roundingValue which is used in rounding operations. The roundingValue is a digit between 0 and 9 that determines rounding behavior. When the scale of a Numeric is reduced either by request or in a calculation, rounding is performed if the value of the scale + 1 digit to the right of the decimal point is greater than the rounding index.

For example, if the number is 1.995, and the scale is set to 2 and the RoundingValue is 4, then the number would be rounded to 2.00. The default roundingValue is 4. A roundingValue of 9 cancels rounding.

Returns:
rounding value
 o createFromByteArray
  public static Numeric createFromByteArray(byte byteArray[])
Return a Numeric created from the given byte array. 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.
Parameters:
byteArray - An array of bytes holding the desired value of the new Numeric.
Returns:
s A new Numeric whose value is determined by the given byte array.
 o createFromIntegerArray
  public static Numeric createFromIntegerArray(int intArray[])
Return a Numeric created from the given byte array. 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.
Parameters:
intArray - An array of integers holding the desired value of the new Numeric.
Returns:
s A new Numeric whose value is determined by the given integer array.
 o createFromScaled
  public static Numeric createFromScaled(long scaled,
                                         int s)
Return a numeric value created by dividing the argument by 10**scale. Thus, createFromScaled(504,2) would create the value "5.04".
Parameters:
scaled - The scaled value as a long.
s - The desired scale value
Returns:
A new numeric.
 o createFromRadixString
  public static Numeric createFromRadixString(String s,
                                              int radix)
Return a Numeric 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 numeric.
radix - The base of the string representation.
Returns:
s A new Numeric whose value is given by the string argument.
 o random
  public static Numeric random(int bits,
                               Random rnd)
Random number generator Returns a random number using randomSeed as a seed and of a size having a maximimum size in bits equal 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:
s a new Numeric of maximium size gitSize
 o intValue
  public int intValue()
Convert the Numeric value to the Java built-in type of int. This conversion may result in a loss of precision. Digits after the decimal point are dropped.
Returns:
An integer representation of the Numeric value.
Overrides:
intValue in class Number
 o longValue
  public long longValue()
Convert the Numeric value to the Java built-in type of long. This conversion may result in a loss of precision. Digits after the decimal point are dropped.
Returns:
A long integer representation of the Numeric value.
Overrides:
longValue in class Number
 o floatValue
  public float floatValue()
Convert the Numeric value to the Java built-in type of float. This conversion may result in a loss of precision.
Returns:
A float representation of the Numeric value.
Overrides:
floatValue in class Number
 o doubleValue
  public double doubleValue()
Convert the Numeric value to the Java built-in type of double. This conversion may result in a loss of precision.
Returns:
A double representation of the Numeric value.
Overrides:
doubleValue in class Number
 o toString
  public String toString()
Convert the Numeric value to the Java built-in type of String. Negative numbers are represented by a leading "-". No sign is added for positive numbers.
Returns:
A String representation of the Numeric value.
Overrides:
toString in class Object
 o toString
  public String toString(int radix)
Returns a String representation of the numeric in the given radix.
Parameters:
radix - the base of the number to be returned
Returns:
a String representation of the numeric 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 getScaled
  public long getScaled()
Return the value multiplied by 10**scale. Precision may be lost. Thus, if a currency value was being kept with scale "2" as "5.04", the getScaled function would return the long integer "504".
Returns:
The scaled value as a long.
 o add
  public Numeric add(Numeric n)
Returns the arithmetic sum of the Numeric and the argument. The scale of the sum is determined by this object not by the argument.
Parameters:
n - The Numeric to add.
Returns:
The sum as a Numeric.
 o subtract
  public Numeric subtract(Numeric n)
Returns the arithmetic difference between the Numeric and the argument. The scale of the sum is determined by this object not by the argument.
Parameters:
n - The Numeric to subtract.
Returns:
The difference as a Numeric.
 o multiply
  public Numeric multiply(Numeric x)
Returns the arithmetic product of the object Numeric and the argument. The scale of the product is determined by this object not by the argument.
Parameters:
x - The multiplier as a Numeric.
Returns:
The product as a Numeric.
 o divide
  public Numeric divide(Numeric x)
Returns the arithmentic quotient calculated by dividing the Numeric by the argument. The scale of the quotient is determined by this object not by the argument.
Parameters:
x - The divisor as a Numeric.
Returns:
The quotient as a Numeric.
 o integerDivide
  public Numeric[] integerDivide(Numeric x)
Returns an array of two Numeric objects. The first element in the array holds the quotient value resulting from the arithmetic division of this Numeric object by the argument. The second element in the array holds the remainder. If the scale of either the divisor or dividend is not zero, then the remainder will be set to zero.
Parameters:
x - The divisor as a Numeric.
Returns:
An array of two Numeric objects containing the quotient and remainder of the division.
 o remainder
  public Numeric remainder(Numeric x)
Returns the arithmentic remainder calculated by dividing this Numeric object by the argument. If either the dividend or the divisor has a scale other than zero, then the remainder is set to zero.
Parameters:
x - The divisor as a Numeric.
Returns:
The remainder as a Numeric.
 o sqrt
  public Numeric sqrt()
Square root Returns the square root of this Numeric. Uses a Newtonian convergence algorithm. Not terrifically, efficient.
Returns:
s the square root of this Numeric.
 o pow
  public Numeric pow(int e)
Returns a new Numeric whose value is calculated by raising this numeric the the power of the given exponent. A binary power algorithm is used.
Returns:
s this Numeric raised to the power given by the exponent argument.
 o equals
  public boolean equals(Object obj)
Returns true if the arithmetic value of the Numeric 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(Numeric x)
Returns true if the arithmetic value of the Numeric is less than the argument.
Parameters:
x - The object to compare.
Returns:
The boolean result of the comparison.
 o lessThanOrEquals
  public boolean lessThanOrEquals(Numeric x)
Returns true if the arithmetic value of the Numeric 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(Numeric x)
Returns true if the arithmetic value of the Numeric is greater than the argument.
Parameters:
x - The object to compare.
Returns:
The boolean result of the comparison.
 o greaterThanOrEquals
  public boolean greaterThanOrEquals(Numeric x)
Returns true if the arithmetic value of the Numeric 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 Numeric. Note that the code returned for 03.00 will equal the code for 3.0.
Returns:
The hashcode as an integer.
Overrides:
hashCode in class Object
 o setScale
  public Numeric setScale(int scale)
Returns a numeric copied from the current object with the scale adjusted as specified by the argument. Sets the number of the digits to the right of the decimal point. The value of the Numeric will be adjusted accordingly. Note that changing the scale to a smaller value may result in rounding the value.
Parameters:
scale - the character to be converted
Returns:
A Numeric with the adjusted scale.
See Also:
roundingValue
 o significantBits
  public int significantBits()
Returns the number of significant bits in the Numeric.
Returns:
s an integer containing the number of the most significant bit of this numeric.
 o shiftRight
  public Numeric shiftRight(int shiftBits)
Shift Right. Returns a new Numeric whose value is calculated by shifting this numeric to the left by the number of bits given in shiftBits
Parameters:
shiftBits - the number of bits to shift.
Returns:
s A new Numeric whose value is this Numeric / 2^shiftBits
 o shiftLeft
  public Numeric shiftLeft(int shiftBits)
Shift Left. Returns a new Numeric calculated by shifting this numeric to the left by the number of bits given in shiftBits. @param shiftBits The number of bits to shift @returns A new Numeric whose value is this Numeric * 2^shiftBits
 o modInverse
  public Numeric modInverse(Numeric mod)
Returns the modular multiplicative inverse of this Numeric
Parameters:
mod - the modulus to be used
Returns:
s the modular multiplicative inverse of this numeric using "mod" as the modulus
 o modExp
  public Numeric modExp(Numeric exponent,
                        Numeric mod)
Modular exponentiation. Calculates a new numeric
Parameters:
exponent - the exponent to be used
mod - the modulus to be used
Returns:
s a new Numeric 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 time. The probability of failing this test is less than 1 / (4^n).
Returns:
s a boolean, true if this Numeric is probably prime, false otherwise.
 o pi
  public static Numeric pi(int numberOfPlaces)
Returns pi to the number of places given by the argument. This is good for about 700 places.
Parameters:
numberOfPlaces - the number of decimal places that will be returned. numberofPlaces must be >= 0 and <= 700.
Returns:
s a new Numeric whose value is pi to the given number of places

All Packages  Class Hierarchy  This Package  Previous  Next  Index