Class Dfp

  • All Implemented Interfaces:
    CalculusFieldElement<Dfp>, FieldElement<Dfp>
    Direct Known Subclasses:
    DfpDec

    public class Dfp
    extends Object
    implements CalculusFieldElement<Dfp>
    Decimal floating point library for Java

    Another floating point class. This one is built using radix 10000 which is 104, so its almost decimal.

    The design goals here are:

    1. Decimal math, or close to it
    2. Settable precision (but no mix between numbers using different settings)
    3. Portability. Code should be kept as portable as possible.
    4. Performance
    5. Accuracy - Results should always be +/- 1 ULP for basic algebraic operation
    6. Comply with IEEE 854-1987 as much as possible. (See IEEE 854-1987 notes below)

    Trade offs:

    1. Memory foot print. I'm using more memory than necessary to represent numbers to get better performance.
    2. Digits are bigger, so rounding is a greater loss. So, if you really need 12 decimal digits, better use 4 base 10000 digits there can be one partially filled.

    Numbers are represented in the following form: \[ n = \mathrm{sign} \times \mathrm{mant} \times \mathrm{radix}^\mathrm{exp} \] where sign is ±1, mantissa represents a fractional number between zero and one. mant[0] is the least significant digit. exp is in the range of -32767 to 32768

    IEEE 854-1987 Notes and differences

    IEEE 854 requires the radix to be either 2 or 10. The radix here is 10000, so that requirement is not met, but it is possible that a subclassed can be made to make it behave as a radix 10 number. It is my opinion that if it looks and behaves as a radix 10 number then it is one and that requirement would be met.

    The radix of 10000 was chosen because it should be faster to operate on 4 decimal digits at once instead of one at a time. Radix 10 behavior can be realized by adding an additional rounding step to ensure that the number of decimal digits represented is constant.

    The IEEE standard specifically leaves out internal data encoding, so it is reasonable to conclude that such a subclass of this radix 10000 system is merely an encoding of a radix 10 system.

    IEEE 854 also specifies the existence of "sub-normal" numbers. This class does not contain any such entities. The most significant radix 10000 digit is always non-zero. Instead, we support "gradual underflow" by raising the underflow flag for numbers less with exponent less than expMin, but don't flush to zero until the exponent reaches MIN_EXP-digits. Thus the smallest number we can represent would be: 1E(-(MIN_EXP-digits-1)*4), eg, for digits=5, MIN_EXP=-32767, that would be 1e-131092.

    IEEE 854 defines that the implied radix point lies just to the right of the most significant digit and to the left of the remaining digits. This implementation puts the implied radix point to the left of all digits including the most significant one. The most significant digit here is the one just to the right of the radix point. This is a fine detail and is really only a matter of definition. Any side effects of this can be rendered invisible by a subclass.

    See Also:
    DfpField
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int ERR_SCALE
      The amount under/overflows are scaled by before going to trap handler
      protected int exp
      Exponent.
      static byte FINITE
      Indicator value for normal finite numbers.
      static byte INFINITE
      Indicator value for Infinity.
      protected int[] mant
      Mantissa.
      static int MAX_EXP
      The maximum exponent before overflow is signaled and results flushed to infinity
      static int MIN_EXP
      The minimum exponent before underflow is signaled.
      protected byte nans
      Indicator for non-finite / non-number values.
      static byte QNAN
      Indicator value for quiet NaN.
      static int RADIX
      The radix, or base of this system.
      protected byte sign
      Sign bit: 1 for positive, -1 for negative.
      static byte SNAN
      Indicator value for signaling NaN.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        Dfp​(Dfp d)
      Copy constructor.
      protected Dfp​(DfpField field)
      Makes an instance with a value of zero.
      protected Dfp​(DfpField field, byte x)
      Create an instance from a byte value.
      protected Dfp​(DfpField field, byte sign, byte nans)
      Creates an instance with a non-finite value.
      protected Dfp​(DfpField field, double x)
      Create an instance from a double value.
      protected Dfp​(DfpField field, int x)
      Create an instance from an int value.
      protected Dfp​(DfpField field, long x)
      Create an instance from a long value.
      protected Dfp​(DfpField field, String s)
      Create an instance from a String representation.
    • Field Detail

      • RADIX

        public static final int RADIX
        The radix, or base of this system. Set to 10000
        See Also:
        Constant Field Values
      • MIN_EXP

        public static final int MIN_EXP
        The minimum exponent before underflow is signaled. Flush to zero occurs at minExp-DIGITS
        See Also:
        Constant Field Values
      • MAX_EXP

        public static final int MAX_EXP
        The maximum exponent before overflow is signaled and results flushed to infinity
        See Also:
        Constant Field Values
      • ERR_SCALE

        public static final int ERR_SCALE
        The amount under/overflows are scaled by before going to trap handler
        See Also:
        Constant Field Values
      • FINITE

        public static final byte FINITE
        Indicator value for normal finite numbers.
        See Also:
        Constant Field Values
      • INFINITE

        public static final byte INFINITE
        Indicator value for Infinity.
        See Also:
        Constant Field Values
      • mant

        protected int[] mant
        Mantissa.
      • sign

        protected byte sign
        Sign bit: 1 for positive, -1 for negative.
      • exp

        protected int exp
        Exponent.
      • nans

        protected byte nans
        Indicator for non-finite / non-number values.
    • Constructor Detail

      • Dfp

        protected Dfp​(DfpField field)
        Makes an instance with a value of zero.
        Parameters:
        field - field to which this instance belongs
      • Dfp

        protected Dfp​(DfpField field,
                      byte x)
        Create an instance from a byte value.
        Parameters:
        field - field to which this instance belongs
        x - value to convert to an instance
      • Dfp

        protected Dfp​(DfpField field,
                      int x)
        Create an instance from an int value.
        Parameters:
        field - field to which this instance belongs
        x - value to convert to an instance
      • Dfp

        protected Dfp​(DfpField field,
                      long x)
        Create an instance from a long value.
        Parameters:
        field - field to which this instance belongs
        x - value to convert to an instance
      • Dfp

        protected Dfp​(DfpField field,
                      double x)
        Create an instance from a double value.
        Parameters:
        field - field to which this instance belongs
        x - value to convert to an instance
      • Dfp

        public Dfp​(Dfp d)
        Copy constructor.
        Parameters:
        d - instance to copy
      • Dfp

        protected Dfp​(DfpField field,
                      String s)
        Create an instance from a String representation.
        Parameters:
        field - field to which this instance belongs
        s - string representation of the instance
      • Dfp

        protected Dfp​(DfpField field,
                      byte sign,
                      byte nans)
        Creates an instance with a non-finite value.
        Parameters:
        field - field to which this instance belongs
        sign - sign of the Dfp to create
        nans - code of the value, must be one of INFINITE, SNAN, QNAN
    • Method Detail

      • newInstance

        public Dfp newInstance()
        Create an instance with a value of 0. Use this internally in preference to constructors to facilitate subclasses
        Returns:
        a new instance with a value of 0
      • newInstance

        public Dfp newInstance​(byte x)
        Create an instance from a byte value.
        Parameters:
        x - value to convert to an instance
        Returns:
        a new instance with value x
      • newInstance

        public Dfp newInstance​(int x)
        Create an instance from an int value.
        Parameters:
        x - value to convert to an instance
        Returns:
        a new instance with value x
      • newInstance

        public Dfp newInstance​(long x)
        Create an instance from a long value.
        Parameters:
        x - value to convert to an instance
        Returns:
        a new instance with value x
      • newInstance

        public Dfp newInstance​(double x)
        Create an instance corresponding to a constant real value.
        Specified by:
        newInstance in interface CalculusFieldElement<Dfp>
        Parameters:
        x - constant real value
        Returns:
        instance corresponding to a constant real value
      • newInstance

        public Dfp newInstance​(Dfp d)
        Create an instance by copying an existing one. Use this internally in preference to constructors to facilitate subclasses.
        Parameters:
        d - instance to copy
        Returns:
        a new instance with the same value as d
      • newInstance

        public Dfp newInstance​(String s)
        Create an instance from a String representation. Use this internally in preference to constructors to facilitate subclasses.
        Parameters:
        s - string representation of the instance
        Returns:
        a new instance parsed from specified string
      • newInstance

        public Dfp newInstance​(byte sig,
                               byte code)
        Creates an instance with a non-finite value.
        Parameters:
        sig - sign of the Dfp to create
        code - code of the value, must be one of INFINITE, SNAN, QNAN
        Returns:
        a new instance with a non-finite value
      • newInstance

        public Dfp newInstance​(DfpField targetField,
                               DfpField.RoundingMode rmode)
        Creates an instance by converting the instance to a different field (i.e. different accuracy).

        If the target field as a greater number of digits, the extra least significant digits will be set to zero.

        Parameters:
        targetField - field to convert the instance to
        rmode - rounding mode to use if target field as less digits than the instance, can be null otherwise
        Returns:
        converted instance (or the instance itself if it already has the required number of digits)
        Since:
        1.7
        See Also:
        DfpField.getExtendedField(int, boolean)
      • getField

        public DfpField getField()
        Get the Field (really a DfpField) to which the instance belongs.

        The field is linked to the number of digits and acts as a factory for Dfp instances.

        Specified by:
        getField in interface FieldElement<Dfp>
        Returns:
        Field (really a DfpField) to which the instance belongs
      • getRadixDigits

        public int getRadixDigits()
        Get the number of radix digits of the instance.
        Returns:
        number of radix digits
      • getZero

        public Dfp getZero()
        Get the constant 0.
        Returns:
        a Dfp with value zero
      • getOne

        public Dfp getOne()
        Get the constant 1.
        Returns:
        a Dfp with value one
      • getTwo

        public Dfp getTwo()
        Get the constant 2.
        Returns:
        a Dfp with value two
      • shiftLeft

        protected void shiftLeft()
        Shift the mantissa left, and adjust the exponent to compensate.
      • shiftRight

        protected void shiftRight()
        Shift the mantissa right, and adjust the exponent to compensate.
      • align

        protected int align​(int e)
        Make our exp equal to the supplied one, this may cause rounding. Also causes de-normalized numbers. These numbers are generally dangerous because most routines assume normalized numbers. Align doesn't round, so it will return the last digit destroyed by shifting right.
        Parameters:
        e - desired exponent
        Returns:
        last digit destroyed by shifting right
      • lessThan

        public boolean lessThan​(Dfp x)
        Check if instance is less than x.
        Parameters:
        x - number to check instance against
        Returns:
        true if instance is less than x and neither are NaN, false otherwise
      • greaterThan

        public boolean greaterThan​(Dfp x)
        Check if instance is greater than x.
        Parameters:
        x - number to check instance against
        Returns:
        true if instance is greater than x and neither are NaN, false otherwise
      • negativeOrNull

        public boolean negativeOrNull()
        Check if instance is less than or equal to 0.
        Returns:
        true if instance is not NaN and less than or equal to 0, false otherwise
      • strictlyNegative

        public boolean strictlyNegative()
        Check if instance is strictly less than 0.
        Returns:
        true if instance is not NaN and less than or equal to 0, false otherwise
      • positiveOrNull

        public boolean positiveOrNull()
        Check if instance is greater than or equal to 0.
        Returns:
        true if instance is not NaN and greater than or equal to 0, false otherwise
      • strictlyPositive

        public boolean strictlyPositive()
        Check if instance is strictly greater than 0.
        Returns:
        true if instance is not NaN and greater than or equal to 0, false otherwise
      • isInfinite

        public boolean isInfinite()
        Check if the instance is infinite.
        Specified by:
        isInfinite in interface CalculusFieldElement<Dfp>
        Returns:
        true if the instance is infinite
      • isNaN

        public boolean isNaN()
        Check if the instance is Not a Number.
        Specified by:
        isNaN in interface CalculusFieldElement<Dfp>
        Returns:
        true if the instance is Not a Number
      • isZero

        public boolean isZero()
        Check if instance is equal to zero.
        Specified by:
        isZero in interface FieldElement<Dfp>
        Returns:
        true if instance is equal to zero
      • equals

        public boolean equals​(Object other)
        Check if instance is equal to x.
        Overrides:
        equals in class Object
        Parameters:
        other - object to check instance against
        Returns:
        true if instance is equal to x and neither are NaN, false otherwise
      • hashCode

        public int hashCode()
        Gets a hashCode for the instance.
        Overrides:
        hashCode in class Object
        Returns:
        a hash code value for this object
      • unequal

        public boolean unequal​(Dfp x)
        Check if instance is not equal to x.
        Parameters:
        x - number to check instance against
        Returns:
        true if instance is not equal to x and neither are NaN, false otherwise
      • rint

        public Dfp rint()
        Round to nearest integer using the round-half-even method. That is round to nearest integer unless both are equidistant. In which case round to the even one.
        Specified by:
        rint in interface CalculusFieldElement<Dfp>
        Returns:
        rounded value
      • floor

        public Dfp floor()
        Round to an integer using the round floor mode. That is, round toward -Infinity
        Specified by:
        floor in interface CalculusFieldElement<Dfp>
        Returns:
        rounded value
      • ceil

        public Dfp ceil()
        Round to an integer using the round ceil mode. That is, round toward +Infinity
        Specified by:
        ceil in interface CalculusFieldElement<Dfp>
        Returns:
        rounded value
      • remainder

        public Dfp remainder​(Dfp d)
        Returns the IEEE remainder.
        Specified by:
        remainder in interface CalculusFieldElement<Dfp>
        Parameters:
        d - divisor
        Returns:
        this less n × d, where n is the integer closest to this/d
      • trunc

        protected Dfp trunc​(DfpField.RoundingMode rmode)
        Does the integer conversions with the specified rounding.
        Parameters:
        rmode - rounding mode to use
        Returns:
        truncated value
      • intValue

        public int intValue()
        Convert this to an integer. If greater than 2147483647, it returns 2147483647. If less than -2147483648 it returns -2147483648.
        Returns:
        converted number
      • log10K

        public int log10K()
        Get the exponent of the greatest power of 10000 that is less than or equal to the absolute value of this. I.E. if this is 106 then log10K would return 1.
        Returns:
        integer base 10000 logarithm
      • power10K

        public Dfp power10K​(int e)
        Get the specified power of 10000.
        Parameters:
        e - desired power
        Returns:
        10000e
      • intLog10

        public int intLog10()
        Get the exponent of the greatest power of 10 that is less than or equal to abs(this).
        Returns:
        integer base 10 logarithm
      • power10

        public Dfp power10​(int e)
        Return the specified power of 10.
        Parameters:
        e - desired power
        Returns:
        10e
      • complement

        protected int complement​(int extra)
        Negate the mantissa of this by computing the complement. Leaves the sign bit unchanged, used internally by add. Denormalized numbers are handled properly here.
        Parameters:
        extra - ???
        Returns:
        ???
      • add

        public Dfp add​(Dfp x)
        Add x to this.
        Specified by:
        add in interface FieldElement<Dfp>
        Parameters:
        x - number to add
        Returns:
        sum of this and x
      • negate

        public Dfp negate()
        Returns a number that is this number with the sign bit reversed.
        Specified by:
        negate in interface FieldElement<Dfp>
        Returns:
        the opposite of this
      • subtract

        public Dfp subtract​(Dfp x)
        Subtract x from this.
        Specified by:
        subtract in interface FieldElement<Dfp>
        Parameters:
        x - number to subtract
        Returns:
        difference of this and a
      • round

        protected int round​(int n)
        Round this given the next digit n using the current rounding mode.
        Parameters:
        n - ???
        Returns:
        the IEEE flag if an exception occurred
      • multiply

        public Dfp multiply​(Dfp x)
        Multiply this by x.
        Specified by:
        multiply in interface FieldElement<Dfp>
        Parameters:
        x - multiplicand
        Returns:
        product of this and x
      • multiply

        public Dfp multiply​(int x)
        Multiply this by a single digit x.
        Specified by:
        multiply in interface FieldElement<Dfp>
        Parameters:
        x - multiplicand
        Returns:
        product of this and x
      • divide

        public Dfp divide​(Dfp divisor)
        Divide this by divisor.
        Specified by:
        divide in interface FieldElement<Dfp>
        Parameters:
        divisor - divisor
        Returns:
        quotient of this by divisor
      • divide

        public Dfp divide​(int divisor)
        Divide by a single digit less than radix. Special case, so there are speed advantages. 0 <= divisor < radix
        Parameters:
        divisor - divisor
        Returns:
        quotient of this by divisor
      • toString

        public String toString()
        Get a string representation of the instance.
        Overrides:
        toString in class Object
        Returns:
        string representation of the instance
      • dfp2sci

        protected String dfp2sci()
        Convert an instance to a string using scientific notation.
        Returns:
        string representation of the instance in scientific notation
      • dfp2string

        protected String dfp2string()
        Convert an instance to a string using normal notation.
        Returns:
        string representation of the instance in normal notation
      • dotrap

        public Dfp dotrap​(int type,
                          String what,
                          Dfp oper,
                          Dfp result)
        Raises a trap. This does not set the corresponding flag however.
        Parameters:
        type - the trap type
        what - - name of routine trap occurred in
        oper - - input operator to function
        result - - the result computed prior to the trap
        Returns:
        The suggested return value from the trap handler
      • trap

        protected Dfp trap​(int type,
                           String what,
                           Dfp oper,
                           Dfp def,
                           Dfp result)
        Trap handler. Subclasses may override this to provide trap functionality per IEEE 854-1987.
        Parameters:
        type - The exception type - e.g. FLAG_OVERFLOW
        what - The name of the routine we were in e.g. divide()
        oper - An operand to this function if any
        def - The default return value if trap not enabled
        result - The result that is specified to be delivered per IEEE 854, if any
        Returns:
        the value that should be return by the operation triggering the trap
      • classify

        public int classify()
        Returns the type - one of FINITE, INFINITE, SNAN, QNAN.
        Returns:
        type of the number
      • copysign

        public static Dfp copysign​(Dfp x,
                                   Dfp y)
        Creates an instance that is the same as x except that it has the sign of y. abs(x) = dfp.copysign(x, dfp.one)
        Parameters:
        x - number to get the value from
        y - number to get the sign from
        Returns:
        a number with the value of x and the sign of y
      • nextAfter

        public Dfp nextAfter​(Dfp x)
        Returns the next number greater than this one in the direction of x. If this==x then simply returns this.
        Parameters:
        x - direction where to look at
        Returns:
        closest number next to instance in the direction of x
      • toDouble

        public double toDouble()
        Convert the instance into a double.
        Returns:
        a double approximating the instance
        See Also:
        toSplitDouble()
      • toSplitDouble

        public double[] toSplitDouble()
        Convert the instance into a split double.
        Returns:
        an array of two doubles which sum represent the instance
        See Also:
        toDouble()
      • getReal

        public double getReal()
        Get the real value of the number.
        Specified by:
        getReal in interface FieldElement<Dfp>
        Returns:
        real value
      • add

        public Dfp add​(double a)
        '+' operator.
        Specified by:
        add in interface CalculusFieldElement<Dfp>
        Parameters:
        a - right hand side parameter of the operator
        Returns:
        this+a
      • subtract

        public Dfp subtract​(double a)
        '-' operator.
        Specified by:
        subtract in interface CalculusFieldElement<Dfp>
        Parameters:
        a - right hand side parameter of the operator
        Returns:
        this-a
      • multiply

        public Dfp multiply​(double a)
        '×' operator.
        Specified by:
        multiply in interface CalculusFieldElement<Dfp>
        Parameters:
        a - right hand side parameter of the operator
        Returns:
        this×a
      • divide

        public Dfp divide​(double a)
        '÷' operator.
        Specified by:
        divide in interface CalculusFieldElement<Dfp>
        Parameters:
        a - right hand side parameter of the operator
        Returns:
        this÷a
      • remainder

        public Dfp remainder​(double a)
        IEEE remainder operator.
        Specified by:
        remainder in interface CalculusFieldElement<Dfp>
        Parameters:
        a - right hand side parameter of the operator
        Returns:
        this - n × a where n is the closest integer to this/a
      • sign

        public Dfp sign()
        Compute the sign of the instance. The sign is -1 for negative numbers, +1 for positive numbers and 0 otherwise, for Complex number, it is extended on the unit circle (equivalent to z/|z|, with special handling for 0 and NaN)
        Specified by:
        sign in interface CalculusFieldElement<Dfp>
        Returns:
        -1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a
      • copySign

        public Dfp copySign​(Dfp s)
        Returns the instance with the sign of the argument. A NaN sign argument is treated as positive.
        Specified by:
        copySign in interface CalculusFieldElement<Dfp>
        Parameters:
        s - the sign for the returned value
        Returns:
        the instance with the same sign as the sign argument
      • copySign

        public Dfp copySign​(double s)
        Returns the instance with the sign of the argument. A NaN sign argument is treated as positive.
        Specified by:
        copySign in interface CalculusFieldElement<Dfp>
        Parameters:
        s - the sign for the returned value
        Returns:
        the instance with the same sign as the sign argument
      • getExponent

        public int getExponent()
        Return the exponent of the instance, removing the bias.

        For double numbers of the form 2x, the unbiased exponent is exactly x.

        Specified by:
        getExponent in interface CalculusFieldElement<Dfp>
        Returns:
        exponent for the instance, without bias
      • scalb

        public Dfp scalb​(int n)
        Multiply the instance by a power of 2.
        Specified by:
        scalb in interface CalculusFieldElement<Dfp>
        Parameters:
        n - power of 2
        Returns:
        this × 2n
      • ulp

        public Dfp ulp()
        Compute least significant bit (Unit in Last Position) for a number.
        Specified by:
        ulp in interface CalculusFieldElement<Dfp>
        Returns:
        ulp(this)
      • hypot

        public Dfp hypot​(Dfp y)
        Returns the hypotenuse of a triangle with sides this and y - sqrt(this2 +y2) avoiding intermediate overflow or underflow.
        • If either argument is infinite, then the result is positive infinity.
        • else, if either argument is NaN then the result is NaN.
        Specified by:
        hypot in interface CalculusFieldElement<Dfp>
        Parameters:
        y - a value
        Returns:
        sqrt(this2 +y2)
      • rootN

        public Dfp rootN​(int n)
        Nth root.
        Specified by:
        rootN in interface CalculusFieldElement<Dfp>
        Parameters:
        n - order of the root
        Returns:
        nth root of the instance
      • pow

        public Dfp pow​(double p)
        Power operation.
        Specified by:
        pow in interface CalculusFieldElement<Dfp>
        Parameters:
        p - power to apply
        Returns:
        thisp
      • pow

        public Dfp pow​(int n)
        Integer power operation.
        Specified by:
        pow in interface CalculusFieldElement<Dfp>
        Parameters:
        n - power to apply
        Returns:
        thisn
      • expm1

        public Dfp expm1()
        Exponential minus 1.
        Specified by:
        expm1 in interface CalculusFieldElement<Dfp>
        Returns:
        exponential minus one of the instance
      • log1p

        public Dfp log1p()
        Shifted natural logarithm.
        Specified by:
        log1p in interface CalculusFieldElement<Dfp>
        Returns:
        logarithm of one plus the instance
      • atan2

        public Dfp atan2​(Dfp x)
                  throws MathIllegalArgumentException
        Two arguments arc tangent operation.

        Beware of the order or arguments! As this is based on a two-arguments functions, in order to be consistent with arguments order, the instance is the first argument and the single provided argument is the second argument. In order to be consistent with programming languages atan2, this method computes atan2(this, x), i.e. the instance represents the y argument and the x argument is the one passed as a single argument. This may seem confusing especially for users of Wolfram alpha, as this site is not consistent with programming languages atan2 two-arguments arc tangent and puts x as its first argument.

        Specified by:
        atan2 in interface CalculusFieldElement<Dfp>
        Parameters:
        x - second argument of the arc tangent
        Returns:
        atan2(this, x)
        Throws:
        MathIllegalArgumentException - if number of free parameters or orders are inconsistent
      • toDegrees

        public Dfp toDegrees()
        Convert radians to degrees, with error of less than 0.5 ULP
        Specified by:
        toDegrees in interface CalculusFieldElement<Dfp>
        Returns:
        instance converted into degrees
      • toRadians

        public Dfp toRadians()
        Convert degrees to radians, with error of less than 0.5 ULP
        Specified by:
        toRadians in interface CalculusFieldElement<Dfp>
        Returns:
        instance converted into radians
      • getPi

        public Dfp getPi()
        Get the Archimedes constant π.

        Archimedes constant is the ratio of a circle's circumference to its diameter.

        Specified by:
        getPi in interface CalculusFieldElement<Dfp>
        Returns:
        Archimedes constant π