Package 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

## Nested Class Summary

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

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`FLAG_DIV_ZERO`
IEEE 854-1987 flag for division by zero.
`static final int`
`FLAG_INEXACT`
IEEE 854-1987 flag for inexact result.
`static final int`
`FLAG_INVALID`
IEEE 854-1987 flag for invalid operation.
`static final int`
`FLAG_OVERFLOW`
IEEE 854-1987 flag for overflow.
`static final int`
`FLAG_UNDERFLOW`
IEEE 854-1987 flag for underflow.

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
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(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.
`Dfp`
`newDfp(Dfp d)`
Copy constructor.
`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 Details

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

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

### 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 invalid input: '<'= n invalid input: '<'= 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)