Class CompactNumberFormat

public final class CompactNumberFormat extends NumberFormat

CompactNumberFormat is a concrete subclass of NumberFormat that formats a decimal number in its compact form. The compact number formatting is designed for the environment where the space is limited, and the formatted string can be displayed in that limited space. It is defined by LDML's specification for Compact Number Formats. A compact number formatting refers to the representation of a number in a shorter form, based on the patterns provided for a given locale.

For example:
In the US locale, 1000 can be formatted as "1K", and 1000000 as "1M", depending upon the style used.
In the "hi_IN" locale, 1000 can be formatted as "1 हज़ार", and 50000000 as "5 क.", depending upon the style used.

To obtain a CompactNumberFormat for a locale, use one of the factory methods given by NumberFormat for compact number formatting. For example, NumberFormat.getCompactNumberInstance(Locale, Style).

 NumberFormat fmt = NumberFormat.getCompactNumberInstance(
                             new Locale("hi", "IN"), NumberFormat.Style.SHORT);
 String result = fmt.format(1000);
 

Style

A number can be formatted in the compact forms with two different styles, SHORT and LONG. Use NumberFormat.getCompactNumberInstance(Locale, Style) for formatting and parsing a number in SHORT or LONG compact form, where the given Style parameter requests the desired format. A SHORT style compact number instance in the US locale formats 10000 as "10K". However, a LONG style instance in same locale formats 10000 as "10 thousand".

Compact Number Patterns

The compact number patterns are represented in a series of patterns where each pattern is used to format a range of numbers. An example of SHORT styled compact number patterns for the US locale is {"", "", "", "0K", "00K", "000K", "0M", "00M", "000M", "0B", "00B", "000B", "0T", "00T", "000T"}, ranging from 100 to 1014. There can be any number of patterns and they are strictly index based starting from the range 100. For example, in the above patterns, pattern at index 3 ("0K") is used for formatting number >= 1000 and number < 10000, pattern at index 4 ("00K") is used for formatting number >= 10000 and number < 100000 and so on. In most of the locales, patterns with the range 100-102 are empty strings, which implicitly means a special pattern "0". A special pattern "0" is used for any range which does not contain a compact pattern. This special pattern can appear explicitly for any specific range, or considered as a default pattern for an empty string.

A compact pattern contains a positive and negative subpattern separated by a subpattern boundary character ';' (U+003B), for example, "0K;-0K". Each subpattern has a prefix, minimum integer digits, and suffix. The negative subpattern is optional, if absent, then the positive subpattern prefixed with the minus sign ('-' U+002D HYPHEN-MINUS) is used as the negative subpattern. That is, "0K" alone is equivalent to "0K;-0K". If there is an explicit negative subpattern, it serves only to specify the negative prefix and suffix. The number of minimum integer digits, and other characteristics are all the same as the positive pattern. That means that "0K;-00K" produces precisely the same behavior as "0K;-0K".

Many characters in a compact pattern are taken literally, they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. They must be quoted, using single quote ' (U+0027) unless noted otherwise, if they are to appear in the prefix or suffix as literals. For example, 0क'.'.

Plurals

In case some localization requires compact number patterns to be different for plurals, each singular and plural pattern can be enumerated within a pair of curly brackets '{' (U+007B) and '}' (U+007D), separated by a space ' ' (U+0020). If this format is used, each pattern needs to be prepended by its count, followed by a single colon ':' (U+003A). If the pattern includes spaces literally, they must be quoted.

For example, the compact number pattern representing millions in German locale can be specified as "{one:0' 'Million other:0' 'Millionen}". The count follows LDML's Language Plural Rules.

A compact pattern has the following syntax:

 Pattern:
         SimplePattern
         '{' PluralPattern [' ' PluralPattern]optional '}'
 SimplePattern:
         PositivePattern
         PositivePattern [; NegativePattern]optional
 PluralPattern:
         Count:SimplePattern
 Count:
         "zero" / "one" / "two" / "few" / "many" / "other"
 PositivePattern:
         Prefixoptional MinimumInteger Suffixoptional
 NegativePattern:
        Prefixoptional MinimumInteger Suffixoptional
 Prefix:
      Any Unicode characters except \uFFFE, \uFFFF, and
      special characters.
 Suffix:
      Any Unicode characters except \uFFFE, \uFFFF, and
      special characters.
 MinimumInteger:
      0
      0 MinimumInteger
 

Formatting

The default formatting behavior returns a formatted string with no fractional digits, however users can use the setMinimumFractionDigits(int) method to include the fractional part. The number 1000.0 or 1000 is formatted as "1K" not "1.00K" (in the US locale). For this reason, the patterns provided for formatting contain only the minimum integer digits, prefix and/or suffix, but no fractional part. For example, patterns used are {"", "", "", 0K, 00K, ...}. If the pattern selected for formatting a number is "0" (special pattern), either explicit or defaulted, then the general number formatting provided by DecimalFormat for the specified locale is used.

Parsing

The default parsing behavior does not allow a grouping separator until grouping used is set to true by using setGroupingUsed(boolean). The parsing of the fractional part depends on the isParseIntegerOnly(). For example, if the parse integer only is set to true, then the fractional part is skipped.

Rounding

CompactNumberFormat provides rounding modes defined in RoundingMode for formatting. By default, it uses RoundingMode.HALF_EVEN.