org.apache.commons.math.dfp

## Class DfpField

- java.lang.Object
- - org.apache.commons.math.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:
  $Revision: 995987 $ $Date: 2010-09-10 23:24:15 +0200 (ven. 10 sept. 2010) $

### Nested Class Summary

Nested Classes
`static class` `DfpField.RoundingMode` Enumerate for rounding modes.

### Field Summary

Fields
`private Dfp` `e` A `Dfp` with value e.
`private Dfp[]` `eSplit` A two elements `Dfp` array with value e split in two pieces.
`private static String` `eString` High precision string representation of e.
`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.
`private int` `ieeeFlags` IEEE 854-1987 signals.
`private Dfp` `ln10` A `Dfp` with value ln(10).
`private static String` `ln10String` High precision string representation of ln(10).
`private Dfp` `ln2` A `Dfp` with value ln(2).
`private Dfp[]` `ln2Split` A two elements `Dfp` array with value ln(2) split in two pieces.
`private static String` `ln2String` High precision string representation of ln(2).
`private Dfp` `ln5` A `Dfp` with value ln(5).
`private Dfp[]` `ln5Split` A two elements `Dfp` array with value ln(5) split in two pieces.
`private static String` `ln5String` High precision string representation of ln(5).
`private Dfp` `one` A `Dfp` with value 1.
`private Dfp` `pi` A `Dfp` with value π.
`private Dfp[]` `piSplit` A two elements `Dfp` array with value π split in two pieces.
`private static String` `piString` High precision string representation of π.
`private int` `radixDigits` The number of radix digits.
`private DfpField.RoundingMode` `rMode` Current rounding mode.
`private Dfp` `sqr2` A `Dfp` with value √2.
`private Dfp` `sqr2Reciprocal` A `Dfp` with value √2 / 2.
`private static String` `sqr2ReciprocalString` High precision string representation of √2 / 2.
`private Dfp[]` `sqr2Split` A two elements `Dfp` array with value √2 split in two pieces.
`private static String` `sqr2String` High precision string representation of √2.
`private Dfp` `sqr3` A `Dfp` with value √3.
`private Dfp` `sqr3Reciprocal` A `Dfp` with value √3 / 3.
`private static String` `sqr3ReciprocalString` High precision string representation of √3 / 3.
`private static String` `sqr3String` High precision string representation of √3.
`private Dfp` `two` A `Dfp` with value 2.
`private Dfp` `zero` A `Dfp` with value 0.

### Constructor Summary

Constructors
`` `DfpField(int decimalDigits)` Create a factory for the specified number of radix digits.
`private` `DfpField(int decimalDigits, boolean computeConstants)` Create a factory for the specified number of radix digits.

### Method Summary

Methods
`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).
`private static Dfp` `computePi(Dfp one, Dfp two, Dfp three)` Compute π using Jonathan and Peter Borwein quartic formula.
`private static void` `computeStringConstants(int highPrecisionDecimalDigits)` Recompute the high precision string constants.
`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.
`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.
`private Dfp[]` `split(String a)` Breaks a string representation up into two `Dfp`'s.

### 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

#### sqr2String

    private static String sqr2String

High precision string representation of √2.

#### sqr2ReciprocalString

    private static String sqr2ReciprocalString

High precision string representation of √2 / 2.

#### sqr3String

    private static String sqr3String

High precision string representation of √3.

#### sqr3ReciprocalString

    private static String sqr3ReciprocalString

High precision string representation of √3 / 3.

#### piString

    private static String piString

High precision string representation of π.

#### eString

    private static String eString

High precision string representation of e.

#### ln2String

    private static String ln2String

High precision string representation of ln(2).

#### ln5String

    private static String ln5String

High precision string representation of ln(5).

#### ln10String

    private static String ln10String

High precision string representation of ln(10).

#### radixDigits

    private final int radixDigits

The number of radix digits. Note these depend on the radix which is 10000 digits, so each one is equivalent to 4 decimal digits.

#### zero

    private final Dfp zero

A `Dfp` with value 0.

#### one

    private final Dfp one

A `Dfp` with value 1.

#### two

    private final Dfp two

A `Dfp` with value 2.

#### sqr2

    private final Dfp sqr2

A `Dfp` with value √2.

#### sqr2Split

    private final Dfp[] sqr2Split

A two elements `Dfp` array with value √2 split in two pieces.

#### sqr2Reciprocal

    private final Dfp sqr2Reciprocal

A `Dfp` with value √2 / 2.

#### sqr3

    private final Dfp sqr3

A `Dfp` with value √3.

#### sqr3Reciprocal

    private final Dfp sqr3Reciprocal

A `Dfp` with value √3 / 3.

#### pi

    private final Dfp pi

A `Dfp` with value π.

#### piSplit

    private final Dfp[] piSplit

A two elements `Dfp` array with value π split in two pieces.

#### e

    private final Dfp e

A `Dfp` with value e.

#### eSplit

    private final Dfp[] eSplit

A two elements `Dfp` array with value e split in two pieces.

#### ln2

    private final Dfp ln2

A `Dfp` with value ln(2).

#### ln2Split

    private final Dfp[] ln2Split

A two elements `Dfp` array with value ln(2) split in two pieces.

#### ln5

    private final Dfp ln5

A `Dfp` with value ln(5).

#### ln5Split

    private final Dfp[] ln5Split

A two elements `Dfp` array with value ln(5) split in two pieces.

#### ln10

    private final Dfp ln10

A `Dfp` with value ln(10).

#### rMode

    private DfpField.RoundingMode rMode

Current rounding mode.

#### ieeeFlags

    private int ieeeFlags

IEEE 854-1987 signals.

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

#### DfpField

    private DfpField(int decimalDigits,
            boolean computeConstants)

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
  `computeConstants` - if true, the transcendental constants for the given precision must be computed (setting this flag to false is RESERVED for the internal recursive call)

### 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

#### 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)

#### split

    private Dfp[] split(String a)

Breaks a string representation up into two `Dfp`'s. The split is such that the sum of them is equivalent to the input string, but has higher precision than using a single Dfp.

Parameters:
  `a` - string representation of the number to split
Returns:
  an array of two `Dfp` instances which sum equals a

#### computeStringConstants

    private static void computeStringConstants(int highPrecisionDecimalDigits)

Recompute the high precision string constants.

Parameters:
  `highPrecisionDecimalDigits` - precision at which the string constants mus be computed

#### computePi

    private static Dfp computePi(Dfp one,
                Dfp two,
                Dfp three)

Compute π using Jonathan and Peter Borwein quartic formula.

Parameters:
  `one` - constant with value 1 at desired precision
  `two` - constant with value 2 at desired precision
  `three` - constant with value 3 at desired precision
Returns:
  π

#### 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)