com.devexperts.qd.util
Class Decimal

java.lang.Object
  extended by java.lang.Number
      extended by com.devexperts.qd.util.Decimal
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable

public class Decimal
extends java.lang.Number
implements java.lang.Comparable

The Decimal class contains a set of methods to work with floating-point numbers packed into int primitive type. Also, it can be used to wrap a single value in an object with interface like that of the Number class.

Unlike floating-point numbers represented by double and float primitive types, the Decimal uses exponent with base 10, allowing absolute precision for decimal fractions. It has the standard precision of 8 decimal digits and is able to represent numbers as large as 13,421,772,700,000,000 by absolute value or as precise as 0.000,001 (if precision permits). It uses variable of type int for representation, which is divided into two parts as follows:

To calculate described parts and the real value one may use following code:
int mantissa = decimal >> 4;
int power = decimal & 0x0F;
double real_value = (double)mantissa * MULTIPLIERS[power];

The real formula in toDouble method is more complex, because it guarantees that the resulting double is the value closest to the true decimal number and it also supports extra precision formats.

All numbers have single canonical representation in this format which is defined as a number with smallest possible power without loss of precision. The Decimal supports Not-a-Number and Infinities in the same way as standard floating-point numbers do; these numbers also have appropriate canonical representations - see corresponding constants.

The Decimal format is so designed that canonical representation of Not-a-Number is numerical value of zero. Thus uninitialized fields with default numerical value of zero will be properly treated as Not-a-Numbers.

Extra precision formats and special cases

Zero in the lowest 4 bits indicates a special case, which includes NaN values, infinities, and extra precision formats. The interpretation of the number depends on the value of the lowest 7 bits. The highest 25 bits represent mantissa for extra precision formats.

See Also:
Serialized Form

Field Summary
protected  int decimal
           
static int MAX_VALUE
           
static int MIN_VALUE
           
static int NaN
           
static java.lang.String NAN_STRING
           
static int NEGATIVE_INFINITY
           
static java.lang.String NEGATIVE_INFINITY_STRING
           
static int POSITIVE_INFINITY
           
static java.lang.String POSITIVE_INFINITY_STRING
           
static int ZERO
           
 
Constructor Summary
Decimal(int decimal)
           
Decimal(java.lang.String s)
           
 
Method Summary
static int abs(int decimal)
           
static int add(int d1, int d2)
          Adds two specified decimals and returns result as decimal.
static int average(int d1, int d2)
          Averages two specified decimals and returns result as decimal.
 byte byteValue()
           
static int compare(int d1, int d2)
          Compares two specified decimals for order.
 int compareTo(java.lang.Object obj)
           
static int compose(double value)
          Returns decimal value for the corresponding double.
static int composeDecimal(long mantissa, int precision)
          Returns decimal value that corresponds to mantissa / 10^precision.
 double doubleValue()
           
 boolean equals(java.lang.Object obj)
           
 float floatValue()
           
static long getDecimalMantissa(int decimal)
          Returns decimal mantissa of the decimal number.
static int getDecimalPrecision(int decimal)
          Returns decimal precision of the decimal number.
 int hashCode()
           
 int intValue()
           
static boolean isInfinite(int decimal)
           
static boolean isNaN(int decimal)
           
 long longValue()
           
static int neg(int decimal)
           
static int parse(java.lang.String s)
          Deprecated. Use parseDecimal(String) instead -- it is much faster (though does not support scientific notation yet).
static int parseDecimal(char[] chars, int offset, int count)
          The same as parseDecimal(String) but works directly with array of characters.
static int parseDecimal(java.lang.String s)
          Parses string into a packed decimal integer.
 short shortValue()
           
static int sign(int decimal)
           
static int subtract(int d1, int d2)
          Subtracts the second specified decimal from the first specified decimal and returns result as decimal.
static double toDouble(int decimal)
          Returns double value of the corresponding decimal.
 java.lang.String toString()
           
static java.lang.String toString(int decimal)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

NaN

public static final int NaN
See Also:
Constant Field Values

POSITIVE_INFINITY

public static final int POSITIVE_INFINITY
See Also:
Constant Field Values

NEGATIVE_INFINITY

public static final int NEGATIVE_INFINITY
See Also:
Constant Field Values

ZERO

public static final int ZERO
See Also:
Constant Field Values

MAX_VALUE

public static final int MAX_VALUE
See Also:
Constant Field Values

MIN_VALUE

public static final int MIN_VALUE
See Also:
Constant Field Values

NAN_STRING

public static final java.lang.String NAN_STRING
See Also:
Constant Field Values

POSITIVE_INFINITY_STRING

public static final java.lang.String POSITIVE_INFINITY_STRING
See Also:
Constant Field Values

NEGATIVE_INFINITY_STRING

public static final java.lang.String NEGATIVE_INFINITY_STRING
See Also:
Constant Field Values

decimal

protected final int decimal
Constructor Detail

Decimal

public Decimal(int decimal)

Decimal

public Decimal(java.lang.String s)
        throws java.lang.NumberFormatException
Throws:
java.lang.NumberFormatException
Method Detail

isNaN

public static boolean isNaN(int decimal)

isInfinite

public static boolean isInfinite(int decimal)

sign

public static int sign(int decimal)

neg

public static int neg(int decimal)

abs

public static int abs(int decimal)

toDouble

public static double toDouble(int decimal)
Returns double value of the corresponding decimal. The result is the double value closest to the true decimal number.


getDecimalMantissa

public static long getDecimalMantissa(int decimal)
Returns decimal mantissa of the decimal number.

See Also:
composeDecimal(long, int)

getDecimalPrecision

public static int getDecimalPrecision(int decimal)
Returns decimal precision of the decimal number.

See Also:
composeDecimal(long, int)

composeDecimal

public static int composeDecimal(long mantissa,
                                 int precision)
Returns decimal value that corresponds to mantissa / 10^precision. The result is positive or negative infinity if the value is too large by absolute value to represent. The result is zero if value is too small to represent with extra precision format of decimal.

Precision equal or smaller than -19 is considered to produce infinitely large multiplier, thus composeDecimal(0, -19) returns NaN.

This method always returns decimal in a standard precision format if it can represent the value exactly. Extra precision is used only if the standard one does not have enough precision.

Mantissa and precision of the decimal number can be retrieved with getDecimalMantissa(int) and getDecimalPrecision(int) methods. Generally, for well-formed decimal number:

composeDecimal(getDecimalMantissa(decimal), getDecimalPrecision(decimal)) == decimal


compose

public static int compose(double value)
Returns decimal value for the corresponding double. The result is NaN if the value is not-a-number. The result is positive or negative infinity if the value is too large by absolute value to represent. The result is ZERO if value is too small to represent with extra precision format of decimal.

This method always returns decimal in a standard precision format if it can represent the value exactly. Extra precision is used only if the standard one does not have enough precision.


parseDecimal

public static int parseDecimal(java.lang.String s)
                        throws java.lang.NumberFormatException
Parses string into a packed decimal integer. It supports standard floating point representation and can parse any string that was produced by toString(int). This method shall support everything that Double.parseDouble(java.lang.String) supports with the exception of hexadecimal floating point notation and "f|d" suffixes, but currently there are certain other limitations:
todo: support "e" notation, so that any string produced by Double.toString(double) can be parsed.

Note:Use parseDecimal(char[],int,int) if you are parsing buffer of incoming characters and you want to avoid creation of new string objects.

Throws:
java.lang.NumberFormatException

parseDecimal

public static int parseDecimal(char[] chars,
                               int offset,
                               int count)
                        throws java.lang.NumberFormatException
The same as parseDecimal(String) but works directly with array of characters.

Parameters:
chars - the character array.
offset - the initial offset into the chars.
count - the number of chars to parse.
Throws:
java.lang.NumberFormatException

toString

public static java.lang.String toString(int decimal)

parse

public static int parse(java.lang.String s)
                 throws java.lang.NumberFormatException
Deprecated. Use parseDecimal(String) instead -- it is much faster (though does not support scientific notation yet).

Throws:
java.lang.NumberFormatException

compare

public static int compare(int d1,
                          int d2)
Compares two specified decimals for order. Returns a negative integer, zero, or positive integer as the first decimal is less than, equal to, or greater than the second decimal.

Note: this method treats NaN as a largest value (even larger than POSITIVE_INFINITY) that is equal to itself.


subtract

public static int subtract(int d1,
                           int d2)
Subtracts the second specified decimal from the first specified decimal and returns result as decimal.


add

public static int add(int d1,
                      int d2)
Adds two specified decimals and returns result as decimal.


average

public static int average(int d1,
                          int d2)
Averages two specified decimals and returns result as decimal.


byteValue

public byte byteValue()
Overrides:
byteValue in class java.lang.Number

shortValue

public short shortValue()
Overrides:
shortValue in class java.lang.Number

intValue

public int intValue()
Specified by:
intValue in class java.lang.Number

longValue

public long longValue()
Specified by:
longValue in class java.lang.Number

floatValue

public float floatValue()
Specified by:
floatValue in class java.lang.Number

doubleValue

public double doubleValue()
Specified by:
doubleValue in class java.lang.Number

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)
Overrides:
equals in class java.lang.Object

compareTo

public int compareTo(java.lang.Object obj)
Specified by:
compareTo in interface java.lang.Comparable