## 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
`static class` `DfpField.RoundingMode` Enumerate for rounding modes.

Field Summary
`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
`` `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
`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)

Copyright (c) 2003-2013 Apache Software Foundation