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 1416643 2012-12-03 19:37:14Z tn $

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DfpField.RoundingMode` Enumerate for rounding modes.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier | Constructor and Description
    --- | ---
    `` | `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
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `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.
    `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

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

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