org.apache.commons.math3.dfp
Class Dfp

java.lang.Object
  org.apache.commons.math3.dfp.Dfp

All Implemented Interfaces:

FieldElement<Dfp>

Direct Known Subclasses:

DfpDec

public class Dfp
extends Object
implements FieldElement<Dfp>

Decimal floating point library for Java

Another floating point class. This one is built using radix 10000 which is 10⁴, so its almost decimal.

The design goals here are:

1. Decimal math, or close to it
2. Settable precision (but no mix between numbers using different settings)
3. Portability. Code should be kept as portable as possible.
4. Performance
5. Accuracy - Results should always be +/- 1 ULP for basic algebraic operation
6. Comply with IEEE 854-1987 as much as possible. (See IEEE 854-1987 notes below)

Trade offs:

1. Memory foot print. I'm using more memory than necessary to represent numbers to get better performance.
2. Digits are bigger, so rounding is a greater loss. So, if you really need 12 decimal digits, better use 4 base 10000 digits there can be one partially filled.

Numbers are represented in the following form:

  n  =  sign × mant × (radix)exp;

  

where sign is ±1, mantissa represents a fractional number between zero and one. mant[0] is the least significant digit. exp is in the range of -32767 to 32768

IEEE 854-1987 Notes and differences

IEEE 854 requires the radix to be either 2 or 10. The radix here is 10000, so that requirement is not met, but it is possible that a subclassed can be made to make it behave as a radix 10 number. It is my opinion that if it looks and behaves as a radix 10 number then it is one and that requirement would be met.

The radix of 10000 was chosen because it should be faster to operate on 4 decimal digits at once instead of one at a time. Radix 10 behavior can be realized by adding an additional rounding step to ensure that the number of decimal digits represented is constant.

The IEEE standard specifically leaves out internal data encoding, so it is reasonable to conclude that such a subclass of this radix 10000 system is merely an encoding of a radix 10 system.

IEEE 854 also specifies the existence of "sub-normal" numbers. This class does not contain any such entities. The most significant radix 10000 digit is always non-zero. Instead, we support "gradual underflow" by raising the underflow flag for numbers less with exponent less than expMin, but don't flush to zero until the exponent reaches MIN_EXP-digits. Thus the smallest number we can represent would be: 1E(-(MIN_EXP-digits-1)*4), eg, for digits=5, MIN_EXP=-32767, that would be 1e-131092.

IEEE 854 defines that the implied radix point lies just to the right of the most significant digit and to the left of the remaining digits. This implementation puts the implied radix point to the left of all digits including the most significant one. The most significant digit here is the one just to the right of the radix point. This is a fine detail and is really only a matter of definition. Any side effects of this can be rendered invisible by a subclass.

Since:

2.2

Version:

$Id: Dfp.java 7721 2013-02-14 14:07:13Z CardosoP $

See Also:

DfpField

Field Summary

static int	ERR_SCALE The amount under/overflows are scaled by before going to trap handler
protected int	exp Exponent.
static byte	FINITE Indicator value for normal finite numbers.
static byte	INFINITE Indicator value for Infinity.
protected int[]	mant Mantissa.
static int	MAX_EXP The maximum exponent before overflow is signaled and results flushed to infinity
static int	MIN_EXP The minimum exponent before underflow is signaled.
protected byte	nans Indicator for non-finite / non-number values.
static byte	QNAN Indicator value for quiet NaN.
static int	RADIX The radix, or base of this system.
protected byte	sign Sign bit: 1 for positive, -1 for negative.
static byte	SNAN Indicator value for signaling NaN.

Constructor Summary

	Dfp(Dfp d) Copy constructor.
protected	Dfp(DfpField field) Makes an instance with a value of zero.
protected	Dfp(DfpField field, byte x) Create an instance from a byte value.
protected	Dfp(DfpField field, byte sign, byte nans) Creates an instance with a non-finite value.
protected	Dfp(DfpField field, double x) Create an instance from a double value.
protected	Dfp(DfpField field, int x) Create an instance from an int value.
protected	Dfp(DfpField field, long x) Create an instance from a long value.
protected	Dfp(DfpField field, String s) Create an instance from a String representation.

Method Summary

Dfp	abs() Get the absolute value of instance.
Dfp	add(Dfp x) Add x to this.
protected int	align(int e) Make our exp equal to the supplied one, this may cause rounding.
Dfp	ceil() Round to an integer using the round ceil mode.
int	classify() Returns the type - one of FINITE, INFINITE, SNAN, QNAN.
protected int	complement(int extra) Negate the mantissa of this by computing the complement.
static Dfp	copysign(Dfp x, Dfp y) Creates an instance that is the same as x except that it has the sign of y.
protected String	dfp2sci() Convert an instance to a string using scientific notation.
protected String	dfp2string() Convert an instance to a string using normal notation.
Dfp	divide(Dfp divisor) Divide this by divisor.
Dfp	divide(int divisor) Divide by a single digit less than radix.
Dfp	dotrap(int type, String what, Dfp oper, Dfp result) Raises a trap.
boolean	equals(Object other) Check if instance is equal to x.
Dfp	floor() Round to an integer using the round floor mode.
DfpField	getField() Get the Field (really a DfpField) to which the instance belongs.
Dfp	getOne() Get the constant 1.
int	getRadixDigits() Get the number of radix digits of the instance.
Dfp	getTwo() Get the constant 2.
Dfp	getZero() Get the constant 0.
boolean	greaterThan(Dfp x) Check if instance is greater than x.
int	hashCode() Gets a hashCode for the instance.
int	intValue() Convert this to an integer.
boolean	isInfinite() Check if instance is infinite.
boolean	isNaN() Check if instance is not a number.
boolean	isZero() Check if instance is equal to zero.
boolean	lessThan(Dfp x) Check if instance is less than x.
int	log10() Get the exponent of the greatest power of 10 that is less than or equal to abs(this).
int	log10K() Get the exponent of the greatest power of 10000 that is less than or equal to the absolute value of this.
Dfp	multiply(Dfp x) Multiply this by x.
Dfp	multiply(int x) Multiply this by a single digit x.
Dfp	negate() Returns a number that is this number with the sign bit reversed.
boolean	negativeOrNull() Check if instance is less than or equal to 0.
Dfp	newInstance() Create an instance with a value of 0.
Dfp	newInstance(byte x) Create an instance from a byte value.
Dfp	newInstance(byte sig, byte code) Creates an instance with a non-finite value.
Dfp	newInstance(Dfp d) Create an instance by copying an existing one.
Dfp	newInstance(double x) Create an instance from a double value.
Dfp	newInstance(int x) Create an instance from an int value.
Dfp	newInstance(long x) Create an instance from a long value.
Dfp	newInstance(String s) Create an instance from a String representation.
Dfp	nextAfter(Dfp x) Returns the next number greater than this one in the direction of x.
boolean	positiveOrNull() Check if instance is greater than or equal to 0.
Dfp	power10(int e) Return the specified power of 10.
Dfp	power10K(int e) Get the specified power of 10000.
Dfp	reciprocal() Returns the multiplicative inverse of this element.
Dfp	remainder(Dfp d) Returns the IEEE remainder.
Dfp	rint() Round to nearest integer using the round-half-even method.
protected int	round(int n) Round this given the next digit n using the current rounding mode.
protected void	shiftLeft() Shift the mantissa left, and adjust the exponent to compensate.
protected void	shiftRight() Shift the mantissa right, and adjust the exponent to compensate.
Dfp	sqrt() Compute the square root.
boolean	strictlyNegative() Check if instance is strictly less than 0.
boolean	strictlyPositive() Check if instance is strictly greater than 0.
Dfp	subtract(Dfp x) Subtract x from this.
double	toDouble() Convert the instance into a double.
double[]	toSplitDouble() Convert the instance into a split double.
String	toString() Get a string representation of the instance.
protected Dfp	trap(int type, String what, Dfp oper, Dfp def, Dfp result) Trap handler.
protected Dfp	trunc(DfpField.RoundingMode rmode) Does the integer conversions with the specified rounding.
boolean	unequal(Dfp x) Check if instance is not equal to x.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

RADIX

public static final int RADIX

The radix, or base of this system. Set to 10000

See Also:

Constant Field Values

MIN_EXP

public static final int MIN_EXP

The minimum exponent before underflow is signaled. Flush to zero occurs at minExp-DIGITS

See Also:

Constant Field Values

MAX_EXP

public static final int MAX_EXP

The maximum exponent before overflow is signaled and results flushed to infinity

See Also:

Constant Field Values

ERR_SCALE

public static final int ERR_SCALE

The amount under/overflows are scaled by before going to trap handler

See Also:

Constant Field Values

FINITE

public static final byte FINITE

Indicator value for normal finite numbers.

See Also:

Constant Field Values

INFINITE

public static final byte INFINITE

Indicator value for Infinity.

See Also:

Constant Field Values

SNAN

public static final byte SNAN

Indicator value for signaling NaN.

See Also:

Constant Field Values

QNAN

public static final byte QNAN

Indicator value for quiet NaN.

See Also:

Constant Field Values

mant

protected int[] mant

Mantissa.

sign

protected byte sign

Sign bit: 1 for positive, -1 for negative.

exp

protected int exp

Exponent.

nans

protected byte nans

Indicator for non-finite / non-number values.

Constructor Detail

Dfp

protected Dfp(DfpField field)

Makes an instance with a value of zero.

Parameters:

field - field to which this instance belongs

Dfp

protected Dfp(DfpField field,
              byte x)

Create an instance from a byte value.

Parameters:

field - field to which this instance belongs

x - value to convert to an instance

Dfp

protected Dfp(DfpField field,
              int x)

Create an instance from an int value.

Parameters:

field - field to which this instance belongs

x - value to convert to an instance

Dfp

protected Dfp(DfpField field,
              long x)

Create an instance from a long value.

Parameters:

field - field to which this instance belongs

x - value to convert to an instance

Dfp

protected Dfp(DfpField field,
              double x)

Create an instance from a double value.

Parameters:

field - field to which this instance belongs

x - value to convert to an instance

Dfp

public Dfp(Dfp d)

Copy constructor.

Parameters:

d - instance to copy

Dfp

protected Dfp(DfpField field,
              String s)

Create an instance from a String representation.

Parameters:

field - field to which this instance belongs

s - string representation of the instance

Dfp

protected Dfp(DfpField field,
              byte sign,
              byte nans)

Creates an instance with a non-finite value.

Parameters:

field - field to which this instance belongs

sign - sign of the Dfp to create

nans - code of the value, must be one of INFINITE, SNAN, QNAN

Method Detail

newInstance

public Dfp newInstance()

Create an instance with a value of 0. Use this internally in preference to constructors to facilitate subclasses

Returns:

a new instance with a value of 0

newInstance

public Dfp newInstance(byte x)

Create an instance from a byte value.

Parameters:

x - value to convert to an instance

Returns:

a new instance with value x

newInstance

public Dfp newInstance(int x)

Create an instance from an int value.

Parameters:

x - value to convert to an instance

Returns:

a new instance with value x

newInstance

public Dfp newInstance(long x)

Create an instance from a long value.

Parameters:

x - value to convert to an instance

Returns:

a new instance with value x

newInstance

public Dfp newInstance(double x)

Create an instance from a double value.

Parameters:

x - value to convert to an instance

Returns:

a new instance with value x

newInstance

public Dfp newInstance(Dfp d)

Create an instance by copying an existing one. Use this internally in preference to constructors to facilitate subclasses.

Parameters:

d - instance to copy

Returns:

a new instance with the same value as d

newInstance

public Dfp newInstance(String s)

Create an instance from a String representation. Use this internally in preference to constructors to facilitate subclasses.

Parameters:

s - string representation of the instance

Returns:

a new instance parsed from specified string

newInstance

public Dfp newInstance(byte sig,
                       byte code)

Creates an instance with a non-finite value.

Parameters:

sig - sign of the Dfp to create

code - code of the value, must be one of INFINITE, SNAN, QNAN

Returns:

a new instance with a non-finite value

getField

public DfpField getField()

Get the Field (really a DfpField) to which the instance belongs.

The field is linked to the number of digits and acts as a factory for Dfp instances.

Specified by:

getField in interface FieldElement<Dfp>

Returns:

Field (really a DfpField) to which the instance belongs

getRadixDigits

public int getRadixDigits()

Get the number of radix digits of the instance.

Returns:

number of radix digits

getZero

public Dfp getZero()

Get the constant 0.

Returns:

a Dfp with value zero

getOne

public Dfp getOne()

Get the constant 1.

Returns:

a Dfp with value one

getTwo

public Dfp getTwo()

Get the constant 2.

Returns:

a Dfp with value two

shiftLeft

protected void shiftLeft()

Shift the mantissa left, and adjust the exponent to compensate.

shiftRight

protected void shiftRight()

Shift the mantissa right, and adjust the exponent to compensate.

align

protected int align(int e)

Make our exp equal to the supplied one, this may cause rounding. Also causes de-normalized numbers. These numbers are generally dangerous because most routines assume normalized numbers. Align doesn't round, so it will return the last digit destroyed by shifting right.

Parameters:

e - desired exponent

Returns:

last digit destroyed by shifting right

lessThan

public boolean lessThan(Dfp x)

Check if instance is less than x.

Parameters:

x - number to check instance against

Returns:

true if instance is less than x and neither are NaN, false otherwise

greaterThan

public boolean greaterThan(Dfp x)

Check if instance is greater than x.

Parameters:

x - number to check instance against

Returns:

true if instance is greater than x and neither are NaN, false otherwise

negativeOrNull

public boolean negativeOrNull()

Check if instance is less than or equal to 0.

Returns:

true if instance is not NaN and less than or equal to 0, false otherwise

strictlyNegative

public boolean strictlyNegative()

Check if instance is strictly less than 0.

Returns:

true if instance is not NaN and less than or equal to 0, false otherwise

positiveOrNull

public boolean positiveOrNull()

Check if instance is greater than or equal to 0.

Returns:

true if instance is not NaN and greater than or equal to 0, false otherwise

strictlyPositive

public boolean strictlyPositive()

Check if instance is strictly greater than 0.

Returns:

true if instance is not NaN and greater than or equal to 0, false otherwise

abs

public Dfp abs()

Get the absolute value of instance.

Returns:

absolute value of instance

isInfinite

public boolean isInfinite()

Check if instance is infinite.

Returns:

true if instance is infinite

isNaN

public boolean isNaN()

Check if instance is not a number.

Returns:

true if instance is not a number

isZero

public boolean isZero()

Check if instance is equal to zero.

Returns:

true if instance is equal to zero

equals

public boolean equals(Object other)

Check if instance is equal to x.

Overrides:

equals in class Object

Parameters:

other - object to check instance against

Returns:

true if instance is equal to x and neither are NaN, false otherwise

hashCode

public int hashCode()

Gets a hashCode for the instance.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object

unequal

public boolean unequal(Dfp x)

Check if instance is not equal to x.

Parameters:

x - number to check instance against

Returns:

true if instance is not equal to x and neither are NaN, false otherwise

rint

public Dfp rint()

Round to nearest integer using the round-half-even method. That is round to nearest integer unless both are equidistant. In which case round to the even one.

Returns:

rounded value

floor

public Dfp floor()

Round to an integer using the round floor mode. That is, round toward -Infinity

Returns:

rounded value

ceil

public Dfp ceil()

Round to an integer using the round ceil mode. That is, round toward +Infinity

Returns:

rounded value

remainder

public Dfp remainder(Dfp d)

Returns the IEEE remainder.

Parameters:

d - divisor

Returns:

this less n × d, where n is the integer closest to this/d

trunc

protected Dfp trunc(DfpField.RoundingMode rmode)

Does the integer conversions with the specified rounding.

Parameters:

rmode - rounding mode to use

Returns:

truncated value

intValue

public int intValue()

Convert this to an integer. If greater than 2147483647, it returns 2147483647. If less than -2147483648 it returns -2147483648.

Returns:

converted number

log10K

public int log10K()

Get the exponent of the greatest power of 10000 that is less than or equal to the absolute value of this. I.E. if this is 10⁶ then log10K would return 1.

Returns:

integer base 10000 logarithm

power10K

public Dfp power10K(int e)

Get the specified power of 10000.

Parameters:

e - desired power

Returns:

10000^e

log10

public int log10()

Get the exponent of the greatest power of 10 that is less than or equal to abs(this).

Returns:

integer base 10 logarithm

power10

public Dfp power10(int e)

Return the specified power of 10.

Parameters:

e - desired power

Returns:

10^e

complement

protected int complement(int extra)

Negate the mantissa of this by computing the complement. Leaves the sign bit unchanged, used internally by add. Denormalized numbers are handled properly here.

Parameters:

extra - ???

Returns:

???

add

public Dfp add(Dfp x)

Add x to this.

Specified by:

add in interface FieldElement<Dfp>

Parameters:

x - number to add

Returns:

sum of this and x

negate

public Dfp negate()

Returns a number that is this number with the sign bit reversed.

Specified by:

negate in interface FieldElement<Dfp>

Returns:

the opposite of this

subtract

public Dfp subtract(Dfp x)

Subtract x from this.

Specified by:

subtract in interface FieldElement<Dfp>

Parameters:

x - number to subtract

Returns:

difference of this and a

round

protected int round(int n)

Round this given the next digit n using the current rounding mode.

Parameters:

n - ???

Returns:

the IEEE flag if an exception occurred

multiply

public Dfp multiply(Dfp x)

Multiply this by x.

Specified by:

multiply in interface FieldElement<Dfp>

Parameters:

x - multiplicand

Returns:

product of this and x

multiply

public Dfp multiply(int x)

Multiply this by a single digit x.

Specified by:

multiply in interface FieldElement<Dfp>

Parameters:

x - multiplicand

Returns:

product of this and x

divide

public Dfp divide(Dfp divisor)

Divide this by divisor.

Specified by:

divide in interface FieldElement<Dfp>

Parameters:

divisor - divisor

Returns:

quotient of this by divisor

divide

public Dfp divide(int divisor)

Divide by a single digit less than radix. Special case, so there are speed advantages. 0 <= divisor < radix

Parameters:

divisor - divisor

Returns:

quotient of this by divisor

reciprocal

public Dfp reciprocal()

Returns the multiplicative inverse of this element.

Specified by:

reciprocal in interface FieldElement<Dfp>

Returns:

the inverse of this.

sqrt

public Dfp sqrt()

Compute the square root.

Returns:

square root of the instance

toString

public String toString()

Get a string representation of the instance.

Overrides:

toString in class Object

Returns:

string representation of the instance

dfp2sci

protected String dfp2sci()

Convert an instance to a string using scientific notation.

Returns:

string representation of the instance in scientific notation

dfp2string

protected String dfp2string()

Convert an instance to a string using normal notation.

Returns:

string representation of the instance in normal notation

dotrap

public Dfp dotrap(int type,
                  String what,
                  Dfp oper,
                  Dfp result)

Raises a trap. This does not set the corresponding flag however.

Parameters:

type - the trap type

what - - name of routine trap occurred in

oper - - input operator to function

result - - the result computed prior to the trap

Returns:

The suggested return value from the trap handler

trap

protected Dfp trap(int type,
                   String what,
                   Dfp oper,
                   Dfp def,
                   Dfp result)

Trap handler. Subclasses may override this to provide trap functionality per IEEE 854-1987.

Parameters:

type - The exception type - e.g. FLAG_OVERFLOW

what - The name of the routine we were in e.g. divide()

oper - An operand to this function if any

def - The default return value if trap not enabled

result - The result that is specified to be delivered per IEEE 854, if any

Returns:

the value that should be return by the operation triggering the trap

classify

public int classify()

Returns the type - one of FINITE, INFINITE, SNAN, QNAN.

Returns:

type of the number

copysign

public static Dfp copysign(Dfp x,
                           Dfp y)

Creates an instance that is the same as x except that it has the sign of y. abs(x) = dfp.copysign(x, dfp.one)

Parameters:

x - number to get the value from

y - number to get the sign from

Returns:

a number with the value of x and the sign of y

nextAfter

public Dfp nextAfter(Dfp x)

Returns the next number greater than this one in the direction of x. If this==x then simply returns this.

Parameters:

x - direction where to look at

Returns:

closest number next to instance in the direction of x

toDouble

public double toDouble()

Convert the instance into a double.

Returns:

a double approximating the instance

See Also:

toSplitDouble()

toSplitDouble

public double[] toSplitDouble()

Convert the instance into a split double.

Returns:

an array of two doubles which sum represent the instance

See Also:

toDouble()