Interface DecimalQuantity

  • All Superinterfaces:
    PluralRules.IFixedDecimal
    All Known Implementing Classes:
    DecimalQuantity_AbstractBCD, DecimalQuantity_DualStorageBCD

    public interface DecimalQuantity
    extends PluralRules.IFixedDecimal
    An interface representing a number to be processed by the decimal formatting pipeline. Includes methods for rounding, plural rules, and decimal digit extraction.

    By design, this is NOT IMMUTABLE and NOT THREAD SAFE. It is intended to be an intermediate object holding state during a pass through the decimal formatting pipeline.

    Implementations of this interface are free to use any internal storage mechanism.

    TODO: Should I change this to an abstract class so that logic for min/max digits doesn't need to be copied to every implementation?

    • Method Detail

      • setMinInteger

        void setMinInteger​(int minInt)
        Sets the minimum integer digits that this DecimalQuantity should generate. This method does not perform rounding.
        Parameters:
        minInt - The minimum number of integer digits.
      • setMinFraction

        void setMinFraction​(int minFrac)
        Sets the minimum fraction digits that this DecimalQuantity should generate. This method does not perform rounding.
        Parameters:
        minFrac - The minimum number of fraction digits.
      • applyMaxInteger

        void applyMaxInteger​(int maxInt)
        Truncates digits from the upper magnitude of the number in order to satisfy the specified maximum number of integer digits.
        Parameters:
        maxInt - The maximum number of integer digits.
      • roundToIncrement

        void roundToIncrement​(java.math.BigDecimal roundingInterval,
                              java.math.MathContext mathContext)
        Rounds the number to a specified interval, such as 0.05.

        If rounding to a power of ten, use the more efficient roundToMagnitude(int, java.math.MathContext) instead.

        Parameters:
        roundingInterval - The increment to which to round.
        mathContext - The MathContext to use if rounding is necessary. Undefined behavior if null.
      • roundToNickel

        void roundToNickel​(int magnitude,
                           java.math.MathContext mathContext)
        Rounds the number to the nearest multiple of 5 at the specified magnitude. For example, when magnitude == -2, this performs rounding to the nearest 0.05.
        Parameters:
        magnitude - The magnitude at which the digit should become either 0 or 5.
        mathContext - Rounding strategy.
      • roundToMagnitude

        void roundToMagnitude​(int roundingMagnitude,
                              java.math.MathContext mathContext)
        Rounds the number to a specified magnitude (power of ten).
        Parameters:
        roundingMagnitude - The power of ten to which to round. For example, a value of -2 will round to 2 decimal places.
        mathContext - The MathContext to use if rounding is necessary. Undefined behavior if null.
      • roundToInfinity

        void roundToInfinity()
        Rounds the number to an infinite number of decimal points. This has no effect except for forcing the double in DecimalQuantity_AbstractBCD to adopt its exact representation.
      • multiplyBy

        void multiplyBy​(java.math.BigDecimal multiplicand)
        Multiply the internal value.
        Parameters:
        multiplicand - The value by which to multiply.
      • negate

        void negate()
        Flips the sign from positive to negative and back.
      • adjustMagnitude

        void adjustMagnitude​(int delta)
        Scales the number by a power of ten. For example, if the value is currently "1234.56", calling this method with delta=-3 will change the value to "1.23456".
        Parameters:
        delta - The number of magnitudes of ten to change by.
      • getMagnitude

        int getMagnitude()
                  throws java.lang.ArithmeticException
        Returns:
        The power of ten corresponding to the most significant nonzero digit.
        Throws:
        java.lang.ArithmeticException - If the value represented is zero.
      • getExponent

        int getExponent()
        Returns:
        The value of the (suppressed) exponent after the number has been put into a notation with exponents (ex: compact, scientific). Ex: given the number 1000 as "1K" / "1E3", the return value will be 3 (positive).
      • adjustExponent

        void adjustExponent​(int delta)
        Adjusts the value for the (suppressed) exponent stored when using notation with exponents (ex: compact, scientific).

        Adjusting the exponent is decoupled from adjustMagnitude(int) in order to allow flexibility for StandardPlural to be selected in formatting (ex: for compact notation) either with or without the exponent applied in the value of the number.

        Parameters:
        delta - The value to adjust the exponent by.
      • resetExponent

        void resetExponent()
        Resets the DecimalQuantity to the value before adjustMagnitude and adjustExponent.
      • isZeroish

        boolean isZeroish()
        Returns:
        Whether the value represented by this DecimalQuantity is zero, infinity, or NaN.
      • isNegative

        boolean isNegative()
        Returns:
        Whether the value represented by this DecimalQuantity is less than zero.
      • signum

        Modifier.Signum signum()
        Returns:
        The appropriate value from the Signum enum.
      • toDouble

        double toDouble()
        Returns:
        The value contained in this DecimalQuantity approximated as a double.
      • toBigDecimal

        java.math.BigDecimal toBigDecimal()
      • toLong

        long toLong​(boolean truncateIfOverflow)
        Returns a long approximating the decimal quantity. A long can only represent the integral part of the number. Note: this method incorporates the value of getExponent (for cases such as compact notation) to return the proper long value represented by the result.
        Parameters:
        truncateIfOverflow - if false and the number does NOT fit, fails with an error. See comment about call site guards in DecimalQuantity_AbstractBCD.java
        Returns:
        A 64-bit integer representation of the internal number.
      • setToBigDecimal

        void setToBigDecimal​(java.math.BigDecimal input)
      • maxRepresentableDigits

        int maxRepresentableDigits()
      • getStandardPlural

        StandardPlural getStandardPlural​(PluralRules rules)
        Computes the plural form for this number based on the specified set of rules.
        Parameters:
        rules - A PluralRules object representing the set of rules.
        Returns:
        The StandardPlural according to the PluralRules. If the plural form is not in the set of standard plurals, StandardPlural.OTHER is returned instead.
      • getDigit

        byte getDigit​(int magnitude)
        Gets the digit at the specified magnitude. For example, if the represented number is 12.3, getDigit(-1) returns 3, since 3 is the digit corresponding to 10^-1.
        Parameters:
        magnitude - The magnitude of the digit.
        Returns:
        The digit at the specified magnitude.
      • getUpperDisplayMagnitude

        int getUpperDisplayMagnitude()
        Gets the largest power of ten that needs to be displayed. The value returned by this function will be bounded between minInt and maxInt.
        Returns:
        The highest-magnitude digit to be displayed.
      • getLowerDisplayMagnitude

        int getLowerDisplayMagnitude()
        Gets the smallest power of ten that needs to be displayed. The value returned by this function will be bounded between -minFrac and -maxFrac.
        Returns:
        The lowest-magnitude digit to be displayed.
      • toPlainString

        java.lang.String toPlainString()
        Returns the string in "plain" format (no exponential notation) using ASCII digits.
      • toExponentString

        java.lang.String toExponentString()
        Returns the string using ASCII digits and using exponential notation for non-zero exponents, following the UTS 35 specification for plural rule samples.
      • createCopy

        DecimalQuantity createCopy()
        Like clone, but without the restrictions of the Cloneable interface clone.
        Returns:
        A copy of this instance which can be mutated without affecting this instance.
      • copyFrom

        void copyFrom​(DecimalQuantity other)
        Sets this instance to be equal to another instance.
        Parameters:
        other - The instance to copy from.
      • getPositionFingerprint

        long getPositionFingerprint()
        This method is for internal testing only.
      • populateUFieldPosition

        void populateUFieldPosition​(java.text.FieldPosition fp)
        If the given FieldPosition is a UFieldPosition, populates it with the fraction length and fraction long value. If the argument is not a UFieldPosition, nothing happens.
        Parameters:
        fp - The UFieldPosition to populate.