org.apache.commons.math3.dfp
Class DfpField

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

All Implemented Interfaces:

Field<Dfp>

public class DfpField
extends Object
implements Field<Dfp>

Field for Decimal floating point instances.

Since:

2.2

Version:

$Id: DfpField.java 3720 2012-03-16 16:34:17Z CardosoP $

Nested Class Summary

static class

DfpField.RoundingMode Enumerate for rounding modes.

Field Summary

static int	FLAG_DIV_ZERO IEEE 854-1987 flag for division by zero.
static int	FLAG_INEXACT IEEE 854-1987 flag for inexact result.
static int	FLAG_INVALID IEEE 854-1987 flag for invalid operation.
static int	FLAG_OVERFLOW IEEE 854-1987 flag for overflow.
static int	FLAG_UNDERFLOW IEEE 854-1987 flag for underflow.

Constructor Summary

DfpField(int decimalDigits)
Create a factory for the specified number of radix digits.

Method Summary

void	clearIEEEFlags() Clears the IEEE 854 status flags.
static Dfp	computeExp(Dfp a, Dfp one) Compute exp(a).
static Dfp	computeLn(Dfp a, Dfp one, Dfp two) Compute ln(a).
Dfp	getE() Get the constant e.
Dfp[]	getESplit() Get the constant e split in two pieces.
int	getIEEEFlags() Get the IEEE 854 status flags.
Dfp	getLn10() Get the constant ln(10).
Dfp	getLn2() Get the constant ln(2).
Dfp[]	getLn2Split() Get the constant ln(2) split in two pieces.
Dfp	getLn5() Get the constant ln(5).
Dfp[]	getLn5Split() Get the constant ln(5) split in two pieces.
Dfp	getOne() Get the constant 1.
Dfp	getPi() Get the constant π.
Dfp[]	getPiSplit() Get the constant π split in two pieces.
int	getRadixDigits() Get the number of radix digits of the Dfp instances built by this factory.
DfpField.RoundingMode	getRoundingMode() Get the current rounding mode.
Class<? extends FieldElement<Dfp>>	getRuntimeClass() Returns the runtime class of the FieldElement.
Dfp	getSqr2() Get the constant √2.
Dfp	getSqr2Reciprocal() Get the constant √2 / 2.
Dfp[]	getSqr2Split() Get the constant √2 split in two pieces.
Dfp	getSqr3() Get the constant √3.
Dfp	getSqr3Reciprocal() Get the constant √3 / 3.
Dfp	getTwo() Get the constant 2.
Dfp	getZero() Get the constant 0.
Dfp	newDfp() Makes a Dfp with a value of 0.
Dfp	newDfp(byte x) Create an instance from a byte value.
Dfp	newDfp(byte sign, byte nans) Creates a Dfp with a non-finite value.
Dfp	newDfp(Dfp d) Copy constructor.
Dfp	newDfp(double x) Create an instance from a double value.
Dfp	newDfp(int x) Create an instance from an int value.
Dfp	newDfp(long x) Create an instance from a long value.
Dfp	newDfp(String s) Create a Dfp given a String representation.
void	setIEEEFlags(int flags) Sets the IEEE 854 status flags.
void	setIEEEFlagsBits(int bits) Sets some bits in the IEEE 854 status flags, without changing the already set bits.
void	setRoundingMode(DfpField.RoundingMode mode) Set the rounding mode.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FLAG_INVALID

public static final int FLAG_INVALID

IEEE 854-1987 flag for invalid operation.

See Also:

Constant Field Values

FLAG_DIV_ZERO

public static final int FLAG_DIV_ZERO

IEEE 854-1987 flag for division by zero.

See Also:

Constant Field Values

FLAG_OVERFLOW

public static final int FLAG_OVERFLOW

IEEE 854-1987 flag for overflow.

See Also:

Constant Field Values

FLAG_UNDERFLOW

public static final int FLAG_UNDERFLOW

IEEE 854-1987 flag for underflow.

See Also:

Constant Field Values

FLAG_INEXACT

public static final int FLAG_INEXACT

IEEE 854-1987 flag for inexact result.

See Also:

Constant Field Values

Constructor Detail

DfpField

public DfpField(int decimalDigits)

Create a factory for the specified number of radix digits.

Note that since the Dfp class uses 10000 as its radix, each radix digit is equivalent to 4 decimal digits. This implies that asking for 13, 14, 15 or 16 decimal digits will really lead to a 4 radix 10000 digits in all cases.

Parameters:

decimalDigits - minimal number of decimal digits.

Method Detail

getRadixDigits

public int getRadixDigits()

Get the number of radix digits of the Dfp instances built by this factory.

Returns:

number of radix digits

setRoundingMode

public void setRoundingMode(DfpField.RoundingMode mode)

Set the rounding mode. If not set, the default value is DfpField.RoundingMode.ROUND_HALF_EVEN.

Parameters:

mode - desired rounding mode Note that the rounding mode is common to all Dfp instances belonging to the current DfpField in the system and will affect all future calculations.

getRoundingMode

public DfpField.RoundingMode getRoundingMode()

Get the current rounding mode.

Returns:

current rounding mode

getIEEEFlags

public int getIEEEFlags()

Get the IEEE 854 status flags.

Returns:

IEEE 854 status flags

See Also:

clearIEEEFlags(), setIEEEFlags(int), setIEEEFlagsBits(int), FLAG_INVALID, FLAG_DIV_ZERO, FLAG_OVERFLOW, FLAG_UNDERFLOW, FLAG_INEXACT

clearIEEEFlags

public void clearIEEEFlags()

Clears the IEEE 854 status flags.

See Also:

getIEEEFlags(), setIEEEFlags(int), setIEEEFlagsBits(int), FLAG_INVALID, FLAG_DIV_ZERO, FLAG_OVERFLOW, FLAG_UNDERFLOW, FLAG_INEXACT

setIEEEFlags

public void setIEEEFlags(int flags)

Sets the IEEE 854 status flags.

Parameters:

flags - desired value for the flags

See Also:

getIEEEFlags(), clearIEEEFlags(), setIEEEFlagsBits(int), FLAG_INVALID, FLAG_DIV_ZERO, FLAG_OVERFLOW, FLAG_UNDERFLOW, FLAG_INEXACT

setIEEEFlagsBits

public void setIEEEFlagsBits(int bits)

Sets some bits in the IEEE 854 status flags, without changing the already set bits.

Calling this method is equivalent to call setIEEEFlags(getIEEEFlags() | bits)

Parameters:

bits - bits to set

See Also:

getIEEEFlags(), clearIEEEFlags(), setIEEEFlags(int), FLAG_INVALID, FLAG_DIV_ZERO, FLAG_OVERFLOW, FLAG_UNDERFLOW, FLAG_INEXACT

newDfp

public Dfp newDfp()

Makes a Dfp with a value of 0.

Returns:

a new Dfp with a value of 0

newDfp

public Dfp newDfp(byte x)

Create an instance from a byte value.

Parameters:

x - value to convert to an instance

Returns:

a new Dfp with the same value as x

newDfp

public Dfp newDfp(int x)

Create an instance from an int value.

Parameters:

x - value to convert to an instance

Returns:

a new Dfp with the same value as x

newDfp

public Dfp newDfp(long x)

Create an instance from a long value.

Parameters:

x - value to convert to an instance

Returns:

a new Dfp with the same value as x

newDfp

public Dfp newDfp(double x)

Create an instance from a double value.

Parameters:

x - value to convert to an instance

Returns:

a new Dfp with the same value as x

newDfp

public Dfp newDfp(Dfp d)

Copy constructor.

Parameters:

d - instance to copy

Returns:

a new Dfp with the same value as d

newDfp

public Dfp newDfp(String s)

Create a Dfp given a String representation.

Parameters:

s - string representation of the instance

Returns:

a new Dfp parsed from specified string

newDfp

public Dfp newDfp(byte sign,
                  byte nans)

Creates a Dfp with a non-finite value.

Parameters:

sign - sign of the Dfp to create

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

Returns:

a new Dfp with a non-finite value

getZero

public Dfp getZero()

Get the constant 0.

Specified by:

getZero in interface Field<Dfp>

Returns:

a Dfp with value 0

getOne

public Dfp getOne()

Get the constant 1.

Specified by:

getOne in interface Field<Dfp>

Returns:

a Dfp with value 1

getRuntimeClass

public Class<? extends FieldElement<Dfp>> getRuntimeClass()

Returns the runtime class of the FieldElement.

Specified by:

getRuntimeClass in interface Field<Dfp>

Returns:

The Class object that represents the runtime class of this object.

getTwo

public Dfp getTwo()

Get the constant 2.

Returns:

a Dfp with value 2

getSqr2

public Dfp getSqr2()

Get the constant √2.

Returns:

a Dfp with value √2

getSqr2Split

public Dfp[] getSqr2Split()

Get the constant √2 split in two pieces.

Returns:

a Dfp with value √2 split in two pieces

getSqr2Reciprocal

public Dfp getSqr2Reciprocal()

Get the constant √2 / 2.

Returns:

a Dfp with value √2 / 2

getSqr3

public Dfp getSqr3()

Get the constant √3.

Returns:

a Dfp with value √3

getSqr3Reciprocal

public Dfp getSqr3Reciprocal()

Get the constant √3 / 3.

Returns:

a Dfp with value √3 / 3

getPi

public Dfp getPi()

Get the constant π.

Returns:

a Dfp with value π

getPiSplit

public Dfp[] getPiSplit()

Get the constant π split in two pieces.

Returns:

a Dfp with value π split in two pieces

getE

public Dfp getE()

Get the constant e.

Returns:

a Dfp with value e

getESplit

public Dfp[] getESplit()

Get the constant e split in two pieces.

Returns:

a Dfp with value e split in two pieces

getLn2

public Dfp getLn2()

Get the constant ln(2).

Returns:

a Dfp with value ln(2)

getLn2Split

public Dfp[] getLn2Split()

Get the constant ln(2) split in two pieces.

Returns:

a Dfp with value ln(2) split in two pieces

getLn5

public Dfp getLn5()

Get the constant ln(5).

Returns:

a Dfp with value ln(5)

getLn5Split

public Dfp[] getLn5Split()

Get the constant ln(5) split in two pieces.

Returns:

a Dfp with value ln(5) split in two pieces

getLn10

public Dfp getLn10()

Get the constant ln(10).

Returns:

a Dfp with value ln(10)

computeExp

public static Dfp computeExp(Dfp a,
                             Dfp one)

Compute exp(a).

Parameters:

a - number for which we want the exponential

one - constant with value 1 at desired precision

Returns:

exp(a)

computeLn

public static Dfp computeLn(Dfp a,
                            Dfp one,
                            Dfp two)

Compute ln(a). Let f(x) = ln(x), We know that f'(x) = 1/x, thus from Taylor's theorem we have: ----- n+1 n f(x) = \ (-1) (x - 1) / ---------------- for 1 <= n <= infinity ----- n or 2 3 4 (x-1) (x-1) (x-1) ln(x) = (x-1) - ----- + ------ - ------ + ... 2 3 4 alternatively, 2 3 4 x x x ln(x+1) = x - - + - - - + ... 2 3 4 This series can be used to compute ln(x), but it converges too slowly. If we substitute -x for x above, we get 2 3 4 x x x ln(1-x) = -x - - - - - - + ... 2 3 4 Note that all terms are now negative. Because the even powered ones absorbed the sign. Now, subtract the series above from the previous one to get ln(x+1) - ln(1-x). Note the even terms cancel out leaving only the odd ones 3 5 7 2x 2x 2x ln(x+1) - ln(x-1) = 2x + --- + --- + ---- + ... 3 5 7 By the property of logarithms that ln(a) - ln(b) = ln (a/b) we have: 3 5 7 x+1 / x x x \ ln ----- = 2 * | x + ---- + ---- + ---- + ... | x-1 \ 3 5 7 / But now we want to find ln(a), so we need to find the value of x such that a = (x+1)/(x-1). This is easily solved to find that x = (a-1)/(a+1).

Parameters:

a - number for which we want the exponential

one - constant with value 1 at desired precision

two - constant with value 2 at desired precision

Returns:

ln(a)