Top Description Methods
com.ibm.icu.impl.number

public Interface DecimalQuantity

extends IFixedDecimal
Known Direct Implementers
com.ibm.icu.impl.number.DecimalQuantity_AbstractBCD
Imports
java.math.BigDecimal, .MathContext, java.text.FieldPosition, com.ibm.icu.impl.StandardPlural, com.ibm.icu.impl.number.Modifier.Signum, com.ibm.icu.text.PluralRules, .UFieldPosition

Deprecated

as a consequence of PluralRules.IFixedDecimal being deprecated. See corresponding docs for further information.

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 Summary

Modifier and TypeMethod and Description
public void
adjustExponent(int
The value to adjust the exponent by.
delta)

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

public void
adjustMagnitude(int
The number of magnitudes of ten to change by.
delta)

Scales the number by a power of ten.

public void
applyMaxInteger(int
The maximum number of integer digits.
maxInt)

Truncates digits from the upper magnitude of the number in order to satisfy the specified maximum number of integer digits.

public void
copyFrom(DecimalQuantity
The instance to copy from.
other)

Deprecated as a consequence of DecimalQuantity being deprecated.
Sets this instance to be equal to another instance.
public DecimalQuantity

Returns:

A copy of this instance which can be mutated without affecting this instance.
createCopy()

Deprecated as a consequence of DecimalQuantity being deprecated.
Like clone, but without the restrictions of the Cloneable interface clone.
public byte

Returns:

The digit at the specified magnitude.
getDigit(int
The magnitude of the digit.
magnitude)

Gets the digit at the specified magnitude.

public int

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

public int

Returns:

The lowest-magnitude digit to be displayed.
getLowerDisplayMagnitude()

Gets the smallest power of ten that needs to be displayed.

public int

Returns:

The power of ten corresponding to the most significant nonzero digit.
getMagnitude()

public long
getPositionFingerprint()

This method is for internal testing only.

public StandardPlural

Returns:

The StandardPlural according to the PluralRules. If the plural form is not in the set of standard plurals, StandardPlural#OTHER is returned instead.
getStandardPlural(PluralRules
A PluralRules object representing the set of rules.
rules)

Computes the plural form for this number based on the specified set of rules.

public int

Returns:

The highest-magnitude digit to be displayed.
getUpperDisplayMagnitude()

Gets the largest power of ten that needs to be displayed.

public boolean

Returns:

Whether the value represented by this DecimalQuantity is infinite.
isInfinite()

Redeclares com.ibm.icu.text.PluralRules.IFixedDecimal.isInfinite.

public boolean

Returns:

Whether the value represented by this DecimalQuantity is not a number.
isNaN()

Redeclares com.ibm.icu.text.PluralRules.IFixedDecimal.isNaN.

public boolean

Returns:

Whether the value represented by this DecimalQuantity is less than zero.
isNegative()

public boolean

Returns:

Whether the value represented by this DecimalQuantity is zero, infinity, or NaN.
isZeroish()

public int
maxRepresentableDigits()

public void
multiplyBy(BigDecimal
The value by which to multiply.
multiplicand)

Multiply the internal value.

public void
negate()

Flips the sign from positive to negative and back.

public void
populateUFieldPosition(FieldPosition
The UFieldPosition to populate.
fp)

If the given FieldPosition is a UFieldPosition, populates it with the fraction length and fraction long value.

public void
resetExponent()

Resets the DecimalQuantity to the value before adjustMagnitude and adjustExponent.

public void
roundToIncrement(BigDecimal
The increment to which to round.
roundingInterval, MathContext
The MathContext to use if rounding is necessary. Undefined behavior if null.
mathContext)

Rounds the number to a specified interval, such as 0.05.

public void
roundToInfinity()

Rounds the number to an infinite number of decimal points.

public void
roundToMagnitude(int
The power of ten to which to round. For example, a value of -2 will round to 2 decimal places.
roundingMagnitude, MathContext
The MathContext to use if rounding is necessary. Undefined behavior if null.
mathContext)

Rounds the number to a specified magnitude (power of ten).

public void
roundToNickel(int
The magnitude at which the digit should become either 0 or 5.
magnitude, MathContext
Rounding strategy.
mathContext)

Rounds the number to the nearest multiple of 5 at the specified magnitude.

public void
setMinFraction(int
The minimum number of fraction digits.
minFrac)

Sets the minimum fraction digits that this DecimalQuantity should generate.

public void
setMinInteger(int
The minimum number of integer digits.
minInt)

Sets the minimum integer digits that this DecimalQuantity should generate.

public void
setToBigDecimal(BigDecimal input)

public Modifier.Signum

Returns:

The appropriate value from the Signum enum.
signum()

public BigDecimal
toBigDecimal()

public double

Returns:

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

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

public long

Returns:

A 64-bit integer representation of the internal number.
toLong(boolean
if false and the number does NOT fit, fails with an error. See comment about call site guards in DecimalQuantity_AbstractBCD.java
truncateIfOverflow)

Returns a long approximating the decimal quantity.

public String
toPlainString()

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

Inherited from com.ibm.icu.text.PluralRules.IFixedDecimal:
getPluralOperandisHasIntegerValue

Method Detail

adjustExponentback to summary
public 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 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:int

The value to adjust the exponent by.

adjustMagnitudeback to summary
public 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:int

The number of magnitudes of ten to change by.

applyMaxIntegerback to summary
public 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:int

The maximum number of integer digits.

copyFromback to summary
public void copyFrom(DecimalQuantity other)

Deprecated

as a consequence of DecimalQuantity being deprecated. See corresponding docs for further information.

Sets this instance to be equal to another instance.

Parameters
other:DecimalQuantity

The instance to copy from.

createCopyback to summary
public DecimalQuantity createCopy()

Deprecated

as a consequence of DecimalQuantity being deprecated. See corresponding docs for further information.

Like clone, but without the restrictions of the Cloneable interface clone.

Returns:DecimalQuantity

A copy of this instance which can be mutated without affecting this instance.

getDigitback to summary
public 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:int

The magnitude of the digit.

Returns:byte

The digit at the specified magnitude.

getExponentback to summary
public int getExponent()
Returns:int

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

getLowerDisplayMagnitudeback to summary
public 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:int

The lowest-magnitude digit to be displayed.

getMagnitudeback to summary
public int getMagnitude() throws ArithmeticException
Returns:int

The power of ten corresponding to the most significant nonzero digit.

Exceptions
ArithmeticException:
If the value represented is zero.
getPositionFingerprintback to summary
public long getPositionFingerprint()

This method is for internal testing only.

getStandardPluralback to summary
public StandardPlural getStandardPlural(PluralRules rules)

Computes the plural form for this number based on the specified set of rules.

Parameters
rules:PluralRules

A PluralRules object representing the set of rules.

Returns:StandardPlural

The StandardPlural according to the PluralRules. If the plural form is not in the set of standard plurals, StandardPlural#OTHER is returned instead.

getUpperDisplayMagnitudeback to summary
public 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:int

The highest-magnitude digit to be displayed.

isInfiniteback to summary
public boolean isInfinite()

Redeclares com.ibm.icu.text.PluralRules.IFixedDecimal.isInfinite.

Returns:boolean

Whether the value represented by this DecimalQuantity is infinite.

Annotations
@Override
isNaNback to summary
public boolean isNaN()

Redeclares com.ibm.icu.text.PluralRules.IFixedDecimal.isNaN.

Returns:boolean

Whether the value represented by this DecimalQuantity is not a number.

Annotations
@Override
isNegativeback to summary
public boolean isNegative()
Returns:boolean

Whether the value represented by this DecimalQuantity is less than zero.

isZeroishback to summary
public boolean isZeroish()
Returns:boolean

Whether the value represented by this DecimalQuantity is zero, infinity, or NaN.

maxRepresentableDigitsback to summary
public int maxRepresentableDigits()
multiplyByback to summary
public void multiplyBy(BigDecimal multiplicand)

Multiply the internal value.

Parameters
multiplicand:BigDecimal

The value by which to multiply.

negateback to summary
public void negate()

Flips the sign from positive to negative and back.

populateUFieldPositionback to summary
public 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:FieldPosition

The UFieldPosition to populate.

resetExponentback to summary
public void resetExponent()

Resets the DecimalQuantity to the value before adjustMagnitude and adjustExponent.

roundToIncrementback to summary
public 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 instead.

Parameters
roundingInterval:BigDecimal

The increment to which to round.

mathContext:MathContext

The MathContext to use if rounding is necessary. Undefined behavior if null.

roundToInfinityback to summary
public 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.

roundToMagnitudeback to summary
public void roundToMagnitude(int roundingMagnitude, MathContext mathContext)

Rounds the number to a specified magnitude (power of ten).

Parameters
roundingMagnitude:int

The power of ten to which to round. For example, a value of -2 will round to 2 decimal places.

mathContext:MathContext

The MathContext to use if rounding is necessary. Undefined behavior if null.

roundToNickelback to summary
public 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:int

The magnitude at which the digit should become either 0 or 5.

mathContext:MathContext

Rounding strategy.

setMinFractionback to summary
public void setMinFraction(int minFrac)

Sets the minimum fraction digits that this DecimalQuantity should generate. This method does not perform rounding.

Parameters
minFrac:int

The minimum number of fraction digits.

setMinIntegerback to summary
public void setMinInteger(int minInt)

Sets the minimum integer digits that this DecimalQuantity should generate. This method does not perform rounding.

Parameters
minInt:int

The minimum number of integer digits.

setToBigDecimalback to summary
public void setToBigDecimal(BigDecimal input)
signumback to summary
public Modifier.Signum signum()
Returns:Modifier.Signum

The appropriate value from the Signum enum.

toBigDecimalback to summary
public BigDecimal toBigDecimal()
toDoubleback to summary
public double toDouble()
Returns:double

The value contained in this DecimalQuantity approximated as a double.

toExponentStringback to summary
public 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.

toLongback to summary
public 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:boolean

if false and the number does NOT fit, fails with an error. See comment about call site guards in DecimalQuantity_AbstractBCD.java

Returns:long

A 64-bit integer representation of the internal number.

toPlainStringback to summary
public String toPlainString()

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