Added in API level 24

CompactDecimalFormat


open class CompactDecimalFormat : DecimalFormat

Formats numbers in compact (abbreviated) notation, like "1.2K" instead of "1200".

IMPORTANT: New users are strongly encouraged to see if NumberFormatter fits their use case. Although not deprecated, this class, CompactDecimalFormat, is provided for backwards compatibility only.

The CompactDecimalFormat produces abbreviated numbers, suitable for display in environments will limited real estate. For example, 'Hits: 1.2B' instead of 'Hits: 1,200,000,000'. The format will be appropriate for the given language, such as "1,2 Mrd." for German.

For numbers under 1000 trillion (under 10^15, such as 123,456,789,012,345), the result will be short for supported languages. However, the result may sometimes exceed 7 characters, such as when there are combining marks or thin characters. In such cases, the visual width in fonts should still be short.

By default, there are 2 significant digits. After creation, if more than three significant digits are set (with setMaximumSignificantDigits), or if a fixed number of digits are set (with setMaximumIntegerDigits or setMaximumFractionDigits), then result may be wider.

The "short" style is also capable of formatting currency amounts, such as "$1.2M" instead of "$1,200,000.00" (English) or "5,3 Mio. €" instead of "5.300.000,00 €" (German). Localized data concerning longer formats is not available yet in the Unicode CLDR. Because of this, attempting to format a currency amount using the "long" style will produce an UnsupportedOperationException.

At this time, negative numbers and parsing are not supported, and will produce an UnsupportedOperationException. Resetting the pattern prefixes or suffixes is not supported; the method calls are ignored.

Note that important methods, like setting the number of decimals, will be moved up from DecimalFormat to NumberFormat.

Summary

Nested classes

Style parameter for CompactDecimalFormat.

Inherited constants
Int ACCOUNTINGCURRENCYSTYLE

[icu] Constant to specify currency style of format which uses currency symbol to represent currency for accounting, for example: "($3.00), instead of "-$3.00" (CURRENCYSTYLE). Overrides any style specified using -cf- key in locale.

Int CASHCURRENCYSTYLE

[icu] Constant to specify currency cash style of format which uses currency ISO code to represent currency, for example: "NT$3" instead of "NT$3.23".

Int CURRENCYSTYLE

[icu] Constant to specify general currency style of format. Defaults to STANDARDCURRENCYSTYLE, using currency symbol, for example "$3.00", with non-accounting style for negative values (e.g. minus sign). The specific style may be specified using the -cf- locale key.

Int FRACTION_FIELD

Field constant used to construct a FieldPosition object. Signifies that the position of the fraction part of a formatted number should be returned.

Int INTEGERSTYLE

[icu] Constant to specify a integer number style format.

Int INTEGER_FIELD

Field constant used to construct a FieldPosition object. Signifies that the position of the integer part of a formatted number should be returned.

Int ISOCURRENCYSTYLE

[icu] Constant to specify currency style of format which uses currency ISO code to represent currency, for example: "USD3.00".

Int NUMBERSTYLE

[icu] Constant to specify normal number style of format.

Int PERCENTSTYLE

[icu] Constant to specify a style of format to display percent.

Int PLURALCURRENCYSTYLE

[icu] Constant to specify currency style of format which uses currency long name with plural format to represent currency, for example, "3.00 US Dollars".

Int SCIENTIFICSTYLE

[icu] Constant to specify a style of format to display scientific number.

Int STANDARDCURRENCYSTYLE

[icu] Constant to specify currency style of format which uses currency symbol to represent currency, for example "$3.00", using non-accounting style for negative values (e.g. minus sign). Overrides any style specified using -cf- key in locale.

Int MINIMUM_GROUPING_DIGITS_AUTO

[icu] Constant for setMinimumGroupingDigits(int) to specify display grouping using the default strategy for all locales.

Int MINIMUM_GROUPING_DIGITS_MIN2

[icu] Constant for setMinimumGroupingDigits(int) to specify display grouping using locale defaults, except do not show grouping on values smaller than 10000 (such that there is a minimum of two digits before the first separator).

Int PAD_AFTER_PREFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted after the prefix.

Int PAD_AFTER_SUFFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted after the suffix.

Int PAD_BEFORE_PREFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted before the prefix.

Int PAD_BEFORE_SUFFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted before the suffix.

Public methods
open static CompactDecimalFormat!

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

open static CompactDecimalFormat!

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

open Number!
parse(text: String!, parsePosition: ParsePosition!)

Parsing is currently unsupported, and throws an UnsupportedOperationException.

open CurrencyAmount!
parseCurrency(text: CharSequence!, parsePosition: ParsePosition!)

Parsing is currently unsupported, and throws an UnsupportedOperationException.

Inherited functions
Unit applyLocalizedPattern(localizedPattern: String!)

Converts the given string to standard notation and then parses it using applyPattern. This method is provided for backwards compatibility and should not be used in new projects.

Localized notation means that instead of using generic placeholders in the pattern, you use the corresponding locale-specific characters instead. For example, in locale fr-FR, the period in the pattern "0.000" means "decimal" in standard notation (as it does in every other locale), but it means "grouping" in localized notation.

Unit applyPattern(pattern: String!)

Parses the given pattern string and overwrites the settings specified in the pattern string. The properties corresponding to the following setters are overwritten, either with their default values or with the value specified in the pattern string:

  1. setDecimalSeparatorAlwaysShown
  2. setExponentSignAlwaysShown
  3. setFormatWidth
  4. setGroupingSize
  5. setMultiplier (percent/permille)
  6. setMaximumFractionDigits
  7. setMaximumIntegerDigits
  8. setMaximumSignificantDigits
  9. setMinimumExponentDigits
  10. setMinimumFractionDigits
  11. setMinimumIntegerDigits
  12. setMinimumSignificantDigits
  13. setPadPosition
  14. setPadCharacter
  15. setRoundingIncrement
  16. setSecondaryGroupingSize
All other settings remain untouched.

For more information on pattern strings, see UTS #35.

Boolean areSignificantDigitsUsed()

[icu] Returns whether significant digits are being used in rounding.

Any clone()

Boolean equals(other: Any?)

Tests for equality between this formatter and another formatter.

If two DecimalFormat instances are equal, then they will always produce the same output. However, the reverse is not necessarily true: if two DecimalFormat instances always produce the same output, they are not necessarily equal.

StringBuffer! format(number: BigDecimal!, result: StringBuffer!, fieldPosition: FieldPosition!)

[icu] Formats an ICU BigDecimal. Specialization of format.

StringBuffer! format(currAmt: CurrencyAmount!, result: StringBuffer!, fieldPosition: FieldPosition!)

[icu] Formats a CurrencyAmount. Specialization of format.

StringBuffer! format(number: Double, result: StringBuffer!, fieldPosition: FieldPosition!)

Specialization of format.

StringBuffer! format(number: BigDecimal!, result: StringBuffer!, fieldPosition: FieldPosition!)

[icu] Formats a BigDecimal. Specialization of format.

StringBuffer! format(number: BigInteger!, result: StringBuffer!, fieldPosition: FieldPosition!)

[icu] Formats a BigInteger. Specialization of format.

StringBuffer! format(number: Long, result: StringBuffer!, fieldPosition: FieldPosition!)

Specialization of format.

AttributedCharacterIterator! formatToCharacterIterator(obj: Any!)

Formats an Object producing an AttributedCharacterIterator. You can use the returned AttributedCharacterIterator to build the resulting String, as well as to determine information about the resulting String.

Each attribute key of the AttributedCharacterIterator will be of type Field. It is up to each Format implementation to define what the legal values are for each attribute in the AttributedCharacterIterator, but typically the attribute key is also used as the attribute value.

The default implementation creates an AttributedCharacterIterator with no attributes. Subclasses that support fields should override this and create an AttributedCharacterIterator with meaningful attributes.

Currency! getCurrency()

Returns the currency used to display currency amounts. May be null.

CurrencyPluralInfo! getCurrencyPluralInfo()

[icu] Returns the current instance of CurrencyPluralInfo.

Currency.CurrencyUsage! getCurrencyUsage()

[icu] Returns the strategy for rounding currency amounts.

DecimalFormatSymbols! getDecimalFormatSymbols()

Returns a copy of the decimal format symbols used by this formatter.

Int getFormatWidth()

Returns the minimum number of characters in formatted output.

Int getGroupingSize()

Returns the primary grouping size in use.

MathContext! getMathContext()

[icu] Returns the java.math.MathContext being used to round numbers.

MathContext! getMathContextICU()

[icu] Returns the android.icu.math.MathContext being used to round numbers.

Int getMaximumFractionDigits()

Returns the effective maximum number of integer digits after the decimal separator.

Int getMaximumIntegerDigits()

Returns the effective maximum number of digits before the decimal separator.

Int getMaximumSignificantDigits()

[icu] Returns the effective maximum number of significant digits displayed.

Byte getMinimumExponentDigits()

[icu] Returns the minimum number of digits printed in the exponent in scientific notation.

Int getMinimumFractionDigits()

Returns the effective minimum number of integer digits after the decimal separator.

Int getMinimumGroupingDigits()

[icu] Returns the minimum number of digits before grouping is triggered.

Int getMinimumIntegerDigits()

Returns the effective minimum number of digits before the decimal separator.

Int getMinimumSignificantDigits()

[icu] Returns the effective minimum number of significant digits displayed.

Int getMultiplier()

Returns the multiplier being applied to numbers before they are formatted.

String! getNegativePrefix()

Affixes: Gets the negative prefix string currently being used to format numbers.

If the affix was specified via the pattern, the string returned by this method will have locale symbols substituted in place of special characters according to the LDML specification. If the affix was specified via setNegativePrefix, the string will be returned literally.

String! getNegativeSuffix()

Affixes: Gets the negative suffix string currently being used to format numbers.

If the affix was specified via the pattern, the string returned by this method will have locale symbols substituted in place of special characters according to the LDML specification. If the affix was specified via setNegativeSuffix, the string will be returned literally.

Char getPadCharacter()

[icu] Returns the character used for padding.

Int getPadPosition()

[icu] Returns the position used for padding.

Int getParseMaxDigits()

Always returns 1000, the default prior to ICU 59.

String! getPositivePrefix()

Affixes: Gets the positive prefix string currently being used to format numbers.

If the affix was specified via the pattern, the string returned by this method will have locale symbols substituted in place of special characters according to the LDML specification. If the affix was specified via setPositivePrefix, the string will be returned literally.

String! getPositiveSuffix()

Affixes: Gets the positive suffix string currently being used to format numbers.

If the affix was specified via the pattern, the string returned by this method will have locale symbols substituted in place of special characters according to the LDML specification. If the affix was specified via setPositiveSuffix, the string will be returned literally.

BigDecimal! getRoundingIncrement()

[icu] Returns the increment to which numbers are being rounded.

Int getRoundingMode()

Returns the rounding mode being used to round numbers.

Int getSecondaryGroupingSize()

[icu] Returns the secondary grouping size in use.

Int hashCode()

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

Boolean isDecimalPatternMatchRequired()

[icu] Returns whether the presence of a decimal point must match the pattern.

Boolean isDecimalSeparatorAlwaysShown()

Returns whether the decimal separator is shown on integers.

Boolean isExponentSignAlwaysShown()

[icu] Returns whether the sign (plus or minus) is always printed in scientific notation.

Boolean isGroupingUsed()

Returns whether or not grouping separators are being printed in the output.

Boolean isParseBigDecimal()

Returns whether #parse will always return a BigDecimal.

Boolean isParseCaseSensitive()

[icu] Returns whether to force case (uppercase/lowercase) to match when parsing.

Boolean isParseIntegerOnly()

Returns true if this format will parse numbers as integers only. For example in the English locale, with ParseIntegerOnly true, the string "1234." would be parsed as the integer value 1234 and parsing would stop at the "." character. The decimal separator accepted by the parse operation is locale-dependent and determined by the subclass.

Boolean isParseNoExponent()

[icu] Returns whether to ignore exponents when parsing.

Boolean isParseStrict()

[icu] Returns whether strict parsing is in effect.

Boolean isScientificNotation()

[icu] Returns whether scientific (exponential) notation is enabled on this formatter.

Boolean isSignAlwaysShown()

[icu] Returns whether the sign is being shown on positive numbers.

Unit setCurrency(currency: Currency!)

Sets the currency to be used when formatting numbers. The effect is twofold:

  1. Substitutions for currency symbols in the pattern string will use this currency
  2. The rounding mode will obey the rules for this currency (see setCurrencyUsage)
Important: Displaying the currency in the output requires that the patter associated with this formatter contains a currency symbol '¤'. This will be the case if the instance was created via #getCurrencyInstance or one of its friends.

Unit setCurrencyPluralInfo(newInfo: CurrencyPluralInfo!)

[icu] Sets a custom instance of CurrencyPluralInfo. CurrencyPluralInfo generates pattern strings for printing currency long names.

Most users should not call this method directly. You should instead create your formatter via NumberFormat.getInstance(NumberFormat.PLURALCURRENCYSTYLE).

Unit setCurrencyUsage(usage: Currency.CurrencyUsage!)

[icu] Sets the currency-dependent strategy to use when rounding numbers. There are two strategies:

  • STANDARD: When the amount displayed is intended for banking statements or electronic transfer.
  • CASH: When the amount displayed is intended to be representable in physical currency, like at a cash register.
CASH mode is relevant in currencies that do not have tender down to the penny. For more information on the two rounding strategies, see UTS #35. If omitted, the strategy defaults to STANDARD. To override currency rounding altogether, use setMinimumFractionDigits and setMaximumFractionDigits or #setRoundingIncrement.

Unit setDecimalFormatSymbols(newSymbols: DecimalFormatSymbols!)

Sets the decimal format symbols used by this formatter. The formatter uses a copy of the provided symbols.

Unit setDecimalPatternMatchRequired(value: Boolean)

[icu] Parsing: This method is used to either require or the presence of a decimal point in the string being parsed (disabled by default). This feature was designed to be an extra layer of strictness on top of strict parsing, although it can be used in either lenient mode or strict mode.

To require a decimal point, call this method in combination with either a pattern containing a decimal point or with setDecimalSeparatorAlwaysShown.

// Require a decimal point in the string being parsed:
  df.applyPattern("#.");
  df.setDecimalPatternMatchRequired(true);
 
  // Alternatively:
  df.setDecimalSeparatorAlwaysShown(true);
  df.setDecimalPatternMatchRequired(true);
  
To forbid a decimal point, call this method in combination with a pattern containing no decimal point. Alternatively, use setParseIntegerOnly for the same behavior without depending on the contents of the pattern string.
// Forbid a decimal point in the string being parsed:
  df.applyPattern("#");
  df.setDecimalPatternMatchRequired(true);
  

Unit setDecimalSeparatorAlwaysShown(value: Boolean)

Separators: Sets whether the decimal separator (a period in en-US) is shown on integers. For example, if this setting is turned on, formatting 123 will result in "123." with the decimal separator.

This setting can be specified in the pattern for integer formats: "#,##0." is an example.

Unit setExponentSignAlwaysShown(expSignAlways: Boolean)

[icu] Scientific Notation: Sets whether the sign (plus or minus) is always to be shown in the exponent in scientific notation. For example, if this setting is enabled, the number 123000 will be printed as "1.23E+5" in locale en-US. The number 0.0000123 will always be printed as "1.23E-5" in locale en-US whether or not this setting is enabled.

This setting corresponds to the '+' in a pattern such as "0.00E+0".

Unit setFormatWidth(width: Int)

Padding: Sets the minimum width of the string output by the formatting pipeline. For example, if padding is enabled and paddingWidth is set to 6, formatting the number "3.14159" with the pattern "0.00" will result in "··3.14" if '·' is your padding string.

If the number is longer than your padding width, the number will display as if no padding width had been specified, which may result in strings longer than the padding width.

Padding can be specified in the pattern string using the '*' symbol. For example, the format "*x######0" has a format width of 7 and a pad character of 'x'.

Padding is currently counted in UTF-16 code units; see ticket #13034 for more information.

Unit setGroupingSize(width: Int)

Grouping: Sets the primary grouping size (distance between grouping separators) used when formatting large numbers. For most locales, this defaults to 3: the number of digits between the ones and thousands place, between thousands and millions, and so forth.

For example, with a grouping size of 3, the number 1234567 will be formatted as "1,234,567".

Grouping size can also be specified in the pattern: for example, "#,##0" corresponds to a grouping size of 3.

Unit setGroupingUsed(enabled: Boolean)

Grouping: Sets whether grouping is to be used when formatting numbers. Grouping means whether the thousands, millions, billions, and larger powers of ten should be separated by a grouping separator (a comma in en-US).

For example, if grouping is enabled, 12345 will be printed as "12,345" in en-US. If grouping were disabled, it would instead be printed as simply "12345".

Unit setMathContext(mathContext: MathContext!)

[icu] Rounding and Digit Limits: Sets the java.math.MathContext used to round numbers. A "math context" encodes both a rounding mode and a number of significant digits. Most users should call setRoundingMode and/or setMaximumSignificantDigits instead of this method.

When formatting, since no division is ever performed, the default MathContext is unlimited significant digits. However, when division occurs during parsing to correct for percentages and multipliers, a MathContext of 34 digits, the IEEE 754R Decimal128 standard, is used by default. If you require more than 34 digits when parsing, you can set a custom MathContext using this method.

Unit setMathContextICU(mathContextICU: MathContext!)

[icu] Rounding and Digit Limits: Overload of setMathContext for android.icu.math.MathContext.

Unit setMaximumFractionDigits(value: Int)

Rounding and Digit Limits: Sets the maximum number of digits to display after the decimal separator. If the number has more than this many digits, the number is rounded according to the rounding mode.

For example, if maximum fraction digits is 2, the number 123.456 will be printed as "123.46".

Minimum integer and minimum and maximum fraction digits can be specified via the pattern string. For example, "#,#00.00#" has 2 minimum integer digits, 2 minimum fraction digits, and 3 maximum fraction digits. Note that it is not possible to specify maximum integer digits in the pattern except in scientific notation.

If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.

Unit setMaximumIntegerDigits(value: Int)

Rounding and Digit Limits: Sets the maximum number of digits to display before the decimal separator. If the number has more than this many digits, the number is truncated.

For example, if maximum integer digits is 3, the number 12345 will be printed as "345".

Minimum integer and minimum and maximum fraction digits can be specified via the pattern string. For example, "#,#00.00#" has 2 minimum integer digits, 2 minimum fraction digits, and 3 maximum fraction digits. Note that it is not possible to specify maximum integer digits in the pattern except in scientific notation.

If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.

Unit setMaximumSignificantDigits(value: Int)

[icu] Rounding and Digit Limits: Sets the maximum number of significant digits to be displayed. If the number of significant digits in the number exceeds this value, the number will be rounded according to the current rounding mode.

For example, if maximum significant digits is 3 and the number is 12345, the number will be printed as "12300".

If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.

See #setRoundingIncrement and setMaximumFractionDigits for two other ways of specifying rounding strategies.

Unit setMinimumExponentDigits(minExpDig: Byte)

[icu] Scientific Notation: Sets the minimum number of digits to be printed in the exponent. For example, if minimum exponent digits is 3, the number 123000 will be printed as "1.23E005".

This setting corresponds to the number of zeros after the 'E' in a pattern string such as "0.00E000".

Unit setMinimumFractionDigits(value: Int)

Rounding and Digit Limits: Sets the minimum number of digits to display after the decimal separator. If the number has fewer than this many digits, the number is padded with zeros.

For example, if minimum fraction digits is 2, the number 123.4 will be printed as "123.40".

Minimum integer and minimum and maximum fraction digits can be specified via the pattern string. For example, "#,#00.00#" has 2 minimum integer digits, 2 minimum fraction digits, and 3 maximum fraction digits. Note that it is not possible to specify maximum integer digits in the pattern except in scientific notation.

If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.

See #setRoundingIncrement and setMaximumSignificantDigits for two other ways of specifying rounding strategies.

Unit setMinimumGroupingDigits(number: Int)

[icu] Sets the minimum number of digits that must be before the first grouping separator in order for the grouping separator to be printed. For example, if minimum grouping digits is set to 2, in en-US, 1234 will be printed as "1234" and 12345 will be printed as "12,345". Set the value to:

  • 1 to turn off minimum grouping digits.
  • MINIMUM_GROUPING_DIGITS_AUTO to display grouping using the default strategy for all locales.
  • MINIMUM_GROUPING_DIGITS_MIN2 to display grouping using locale defaults, except do not show grouping on values smaller than 10000 (such that there is a minimum of two digits before the first separator).

Unit setMinimumIntegerDigits(value: Int)

Rounding and Digit Limits: Sets the minimum number of digits to display before the decimal separator. If the number has fewer than this many digits, the number is padded with zeros.

For example, if minimum integer digits is 3, the number 12.3 will be printed as "001.23".

Minimum integer and minimum and maximum fraction digits can be specified via the pattern string. For example, "#,#00.00#" has 2 minimum integer digits, 2 minimum fraction digits, and 3 maximum fraction digits. Note that it is not possible to specify maximum integer digits in the pattern except in scientific notation.

If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.

Unit setMinimumSignificantDigits(value: Int)

[icu] Rounding and Digit Limits: Sets the minimum number of significant digits to be displayed. If the number of significant digits is less than this value, the number will be padded with zeros as necessary.

For example, if minimum significant digits is 3 and the number is 1.2, the number will be printed as "1.20".

If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.

Unit setMultiplier(multiplier: Int)

Sets a number that will be used to multiply all numbers prior to formatting. For example, when formatting percents, a multiplier of 100 can be used.

If a percent or permille sign is specified in the pattern, the multiplier is automatically set to 100 or 1000, respectively.

If the number specified here is a power of 10, a more efficient code path will be used.

Unit setNegativePrefix(prefix: String!)

Affixes: Sets the string to prepend to negative numbers. For example, if you set the value "#", then the number -123 will be formatted as "#123" in the locale en-US (overriding the implicit default '-' in the pattern).

Using this method overrides the affix specified via the pattern, and unlike the pattern, the string given to this method will be interpreted literally WITHOUT locale symbol substitutions.

Unit setNegativeSuffix(suffix: String!)

Affixes: Sets the string to append to negative numbers. For example, if you set the value "#", then the number 123 will be formatted as "123#" in the locale en-US.

Using this method overrides the affix specified via the pattern, and unlike the pattern, the string given to this method will be interpreted literally WITHOUT locale symbol substitutions.

Unit setPadCharacter(padChar: Char)

[icu] Padding: Sets the character used to pad numbers that are narrower than the width specified in setFormatWidth.

In the pattern string, the padding character is the token that follows '*' before or after the prefix or suffix.

Unit setPadPosition(padPos: Int)

[icu] Padding: Sets the position where to insert the pad character when narrower than the width specified in setFormatWidth. For example, consider the pattern "P123S" with padding width 8 and padding char "*". The four positions are:

Unit setParseBigDecimal(value: Boolean)

Whether to make #parse prefer returning a android.icu.math.BigDecimal when possible. For strings corresponding to return values of Infinity, -Infinity, NaN, and -0.0, a Double will be returned even if ParseBigDecimal is enabled.

Unit setParseCaseSensitive(value: Boolean)

[icu] Specifies whether parsing should require cases to match in affixes, exponent separators, and currency codes. Case mapping is performed for each code point using android.icu.lang.UCharacter#foldCase.

Unit setParseIntegerOnly(parseIntegerOnly: Boolean)

Parsing: Sets whether to ignore the fraction part of a number when parsing (defaults to false). If a string contains a decimal point, parsing will stop before the decimal point. Note that determining whether a character is a decimal point depends on the locale.

For example, in en-US, parsing the string "123.45" will return the number 123 and parse position 3.

This is functionally equivalent to calling setDecimalPatternMatchRequired and a pattern without a decimal point.

Unit setParseMaxDigits(maxDigits: Int)

Unit setParseNoExponent(value: Boolean)

[icu] Specifies whether to stop parsing when an exponent separator is encountered. For example, parses "123E4" to 123 (with parse position 3) instead of 1230000 (with parse position 5).

Unit setParseStrict(parseStrict: Boolean)

[icu] Sets whether strict parsing is in effect. When this is true, the string is required to be a stronger match to the pattern than when lenient parsing is in effect. More specifically, the following conditions cause a parse failure relative to lenient mode (examples use the pattern "#,##0.#"):

  • The presence and position of special symbols, including currency, must match the pattern.
    '+123' fails (there is no plus sign in the pattern)
  • Leading or doubled grouping separators
    ',123' and '1,,234" fail
  • Groups of incorrect length when grouping is used
    '1,23' and '1234,567' fail, but '1234' passes
  • Grouping separators used in numbers followed by exponents
    '1,234E5' fails, but '1234E5' and '1,234E' pass ('E' is not an exponent when not followed by a number)
When strict parsing is off, all grouping separators are ignored. This is the default behavior.

Unit setPositivePrefix(prefix: String!)

Affixes: Sets the string to prepend to positive numbers. For example, if you set the value "#", then the number 123 will be formatted as "#123" in the locale en-US.

Using this method overrides the affix specified via the pattern, and unlike the pattern, the string given to this method will be interpreted literally WITHOUT locale symbol substitutions.

Unit setPositiveSuffix(suffix: String!)

Affixes: Sets the string to append to positive numbers. For example, if you set the value "#", then the number 123 will be formatted as "123#" in the locale en-US.

Using this method overrides the affix specified via the pattern, and unlike the pattern, the string given to this method will be interpreted literally WITHOUT locale symbol substitutions.

Unit setRoundingIncrement(increment: BigDecimal!)

[icu] Rounding and Digit Limits: Overload of setRoundingIncrement(java.math.BigDecimal).

Unit setRoundingIncrement(increment: Double)

[icu] Rounding and Digit Limits: Overload of setRoundingIncrement(java.math.BigDecimal).

Unit setRoundingIncrement(increment: BigDecimal!)

[icu] Rounding and Digit Limits: Sets an increment, or interval, to which numbers are rounded. For example, a rounding increment of 0.05 will cause the number 1.23 to be rounded to 1.25 in the default rounding mode.

The rounding increment can be specified via the pattern string: for example, the pattern "#,##0.05" encodes a rounding increment of 0.05.

The rounding increment is applied after any multipliers might take effect; for example, in scientific notation or when setMultiplier is used.

See setMaximumFractionDigits and setMaximumSignificantDigits for two other ways of specifying rounding strategies.

Unit setRoundingMode(roundingMode: Int)

Rounding and Digit Limits: Sets the RoundingMode used to round numbers. The default rounding mode is HALF_EVEN, which rounds decimals to their closest whole number, and rounds to the closest even number if at the midpoint.

For more detail on rounding modes, see the ICU User Guide.

For backwards compatibility, the rounding mode is specified as an int argument, which can be from either the constants in BigDecimal or the ordinal value of RoundingMode. The following two calls are functionally equivalent.

df.setRoundingMode(BigDecimal.ROUND_CEILING);
  df.setRoundingMode(RoundingMode.CEILING.ordinal());
  

Unit setScientificNotation(useScientific: Boolean)

[icu] Scientific Notation: Sets whether this formatter should print in scientific (exponential) notation. For example, if scientific notation is enabled, the number 123000 will be printed as "1.23E5" in locale en-US. A locale-specific symbol is used as the exponent separator.

Calling df.setScientificNotation(true) is functionally equivalent to calling df.setMinimumExponentDigits(1).

Unit setSecondaryGroupingSize(width: Int)

[icu] Grouping: Sets the secondary grouping size (distance between grouping separators after the first separator) used when formatting large numbers. In many south Asian locales, this is set to 2.

For example, with primary grouping size 3 and secondary grouping size 2, the number 1234567 will be formatted as "12,34,567".

Grouping size can also be specified in the pattern: for example, "#,##,##0" corresponds to a primary grouping size of 3 and a secondary grouping size of 2.

Unit setSignAlwaysShown(value: Boolean)

Sets whether to always shown the plus sign ('+' in en) on positive numbers. The rules in UTS #35 section 3.2.1 will be followed to ensure a locale-aware placement of the sign.

More specifically, the following strategy will be used to place the plus sign:

  1. Patterns without a negative subpattern: The locale's plus sign will be prepended to the positive prefix.
  2. Patterns with a negative subpattern without a '-' sign (e.g., accounting): The locale's plus sign will be prepended to the positive prefix, as in case 1.
  3. Patterns with a negative subpattern that has a '-' sign: The locale's plus sign will substitute the '-' in the negative subpattern. The positive subpattern will be unused.
This method is designed to be used instead of applying a pattern containing an explicit plus sign, such as "+0;-0". The behavior when combining this method with explicit plus signs in the pattern is undefined.

Unit setSignificantDigitsUsed(useSignificantDigits: Boolean)

[icu] Rounding and Digit Limits: Sets whether significant digits are to be used in rounding.

Calling df.setSignificantDigitsUsed(true) is functionally equivalent to:

df.setMinimumSignificantDigits(1);
  df.setMaximumSignificantDigits(6);
  

String! toLocalizedPattern()

Calls toPattern and converts the string to localized notation. For more information on localized notation, see applyLocalizedPattern. This method is provided for backwards compatibility and should not be used in new projects.

String! toPattern()

Serializes this formatter object to a decimal format pattern string. The result of this method is guaranteed to be functionally equivalent to the pattern string used to create this instance after incorporating values from the setter methods.

For more information on decimal format pattern strings, see UTS #35.

Important: Not all properties are capable of being encoded in a pattern string. See a list of properties in applyPattern.

String toString()

Returns the default value of toString() with extra DecimalFormat-specific information appended to the end of the string. This extra information is intended for debugging purposes, and the format is not guaranteed to be stable.

String! format(number: BigDecimal!)

[icu] Convenience method to format an ICU BigDecimal.

String! format(currAmt: CurrencyAmount!)

[icu] Convenience method to format a CurrencyAmount.

String! format(number: Double)

Specialization of format.

StringBuffer! format(number: Any!, toAppendTo: StringBuffer!, pos: FieldPosition!)

Formats a number and appends the resulting text to the given string buffer. [icu] Note: recognizes BigInteger and BigDecimal objects.

String! format(number: BigDecimal!)

Convenience method to format a BigDecimal.

String! format(number: BigInteger!)

[icu] Convenience method to format a BigInteger.

String! format(number: Long)

Specialization of format.

Array<Locale!>! getAvailableLocales()

Returns the list of Locales for which NumberFormats are available.

DisplayContext! getContext(type: DisplayContext.Type!)

[icu] Get the formatter's DisplayContext value for the specified DisplayContext.Type, such as CAPITALIZATION.

NumberFormat! getCurrencyInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns a currency format for the current default FORMAT locale.

NumberFormat! getCurrencyInstance(inLocale: ULocale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. [icu] Returns a currency format for the specified locale.

NumberFormat! getCurrencyInstance(inLocale: Locale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns a currency format for the specified locale.

NumberFormat! getInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns the default number format for the current default FORMAT locale. The default format is one of the styles provided by the other factory methods: getNumberInstance, getIntegerInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale-dependent.

NumberFormat! getInstance(inLocale: ULocale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. [icu] Returns the default number format for the specified locale. The default format is one of the styles provided by the other factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale-dependent.

NumberFormat! getInstance(desiredLocale: ULocale!, choice: Int)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns a specific style number format for a specific locale.

NumberFormat! getInstance(style: Int)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. [icu] Returns a specific style number format for default FORMAT locale.

NumberFormat! getInstance(inLocale: Locale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns the default number format for the specified locale. The default format is one of the styles provided by the other factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale-dependent.

NumberFormat! getInstance(inLocale: Locale!, style: Int)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. [icu] Returns a specific style number format for a specific locale.

NumberFormat! getIntegerInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns an integer number format for the current default FORMAT locale. The returned number format is configured to round floating point numbers to the nearest integer using IEEE half-even rounding (see ROUND_HALF_EVEN) for formatting, and to parse only the integer part of an input string (see isParseIntegerOnly).

NumberFormat! getIntegerInstance(inLocale: ULocale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. [icu] Returns an integer number format for the specified locale. The returned number format is configured to round floating point numbers to the nearest integer using IEEE half-even rounding (see ROUND_HALF_EVEN) for formatting, and to parse only the integer part of an input string (see isParseIntegerOnly).

NumberFormat! getIntegerInstance(inLocale: Locale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns an integer number format for the specified locale. The returned number format is configured to round floating point numbers to the nearest integer using IEEE half-even rounding (see ROUND_HALF_EVEN) for formatting, and to parse only the integer part of an input string (see isParseIntegerOnly).

NumberFormat! getNumberInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns a general-purpose number format for the current default FORMAT locale.

NumberFormat! getNumberInstance(inLocale: ULocale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. [icu] Returns a general-purpose number format for the specified locale.

NumberFormat! getNumberInstance(inLocale: Locale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns a general-purpose number format for the specified locale.

String! getPattern(forLocale: ULocale!, choice: Int)

Returns the pattern for the provided locale and choice.

NumberFormat! getPercentInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns a percentage format for the current default FORMAT locale.

NumberFormat! getPercentInstance(inLocale: ULocale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. [icu] Returns a percentage format for the specified locale.

NumberFormat! getPercentInstance(inLocale: Locale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Returns a percentage format for the specified locale.

NumberFormat! getScientificInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. [icu] Returns a scientific format for the current default FORMAT locale.

NumberFormat! getScientificInstance(inLocale: ULocale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. [icu] Returns a scientific format for the specified locale.

NumberFormat! getScientificInstance(inLocale: Locale!)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. [icu] Returns a scientific format for the specified locale.

Number! parse(text: String!)

Parses text from the beginning of the given string to produce a number. The method might not use the entire text of the given string.

Any! parseObject(source: String!, parsePosition: ParsePosition!)

Parses text from a string to produce a number.

Unit setContext(context: DisplayContext!)

[icu] Set a particular DisplayContext value in the formatter, such as CAPITALIZATION_FOR_STANDALONE.

Public methods

getInstance

Added in API level 24
open static fun getInstance(
    locale: ULocale!,
    style: CompactDecimalFormat.CompactStyle!
): CompactDecimalFormat!

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Creates a CompactDecimalFormat appropriate for a locale. The result may be affected by the number system in the locale, such as ar-u-nu-latn.

Parameters
locale ULocale!: the desired locale
style CompactDecimalFormat.CompactStyle!: the compact style

getInstance

Added in API level 24
open static fun getInstance(
    locale: Locale!,
    style: CompactDecimalFormat.CompactStyle!
): CompactDecimalFormat!

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat. Creates a CompactDecimalFormat appropriate for a locale. The result may be affected by the number system in the locale, such as ar-u-nu-latn.

Parameters
locale Locale!: the desired locale
style CompactDecimalFormat.CompactStyle!: the compact style

parse

Added in API level 24
open fun parse(
    text: String!,
    parsePosition: ParsePosition!
): Number!

Parsing is currently unsupported, and throws an UnsupportedOperationException.

parseCurrency

Added in API level 24
open fun parseCurrency(
    text: CharSequence!,
    parsePosition: ParsePosition!
): CurrencyAmount!

Parsing is currently unsupported, and throws an UnsupportedOperationException.

Parameters
text CharSequence!: the text to parse
pos input-output position; on input, the position within text to match; must have 0 <= pos.getIndex() < text.length(); on output, the position after the last matched character. If the parse fails, the position in unchanged upon output.
Return
CurrencyAmount! a CurrencyAmount, or null upon failure