DfpField (Apache Commons Math 3.3 API)

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 1538368 2013-11-03 13:57:37Z erans $

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

    Constructors
    Constructor and Description
    `DfpField(int decimalDigits)` 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).
    `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)

Copyright © 2003–2014 The Apache Software Foundation. All rights reserved.