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 Details

    • 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(BigDecimal roundingInterval, 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, 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, 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(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 ArithmeticException
      Returns:
      The power of ten corresponding to the most significant nonzero digit.
      Throws:
      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.

    • isInfinite

      boolean isInfinite()
      Specified by:
      isInfinite in interface PluralRules.IFixedDecimal
      Returns:
      Whether the value represented by this DecimalQuantity is infinite.

    • isNaN

      boolean isNaN()
      Specified by:
      isNaN in interface PluralRules.IFixedDecimal
      Returns:
      Whether the value represented by this DecimalQuantity is not a number.

    • toDouble

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

    • toBigDecimal

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

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

    • toExponentString

      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(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.