[ Web Proxy ]
URL:
Viewing: https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/text/CompactNumberFormat.html [Back]  [Original]
CompactNumberFormat (Java SE 24 & JDK 24)
  1. java.base
  2. java.text
  3. CompactNumberFormat
Contents 
Hide sidebar ❮❯ Show sidebar
  1. Description
    1. Getting a CompactNumberFormat
    2. Style
    3. Using CompactNumberFormat
    4. Formatting
    5. Parsing
    6. Compact Number Patterns
  2. Nested Class Summary
  3. Field Summary
  4. Constructor Summary
  5. Method Summary
  6. Constructor Details
    1. CompactNumberFormat(String, DecimalFormatSymbols, String[])
    2. CompactNumberFormat(String, DecimalFormatSymbols, String[], String)
  7. Method Details
    1. format(Object, StringBuffer, FieldPosition)
    2. format(double, StringBuffer, FieldPosition)
    3. format(long, StringBuffer, FieldPosition)
    4. formatToCharacterIterator(Object)
    5. parse(String, ParsePosition)
    6. setMaximumIntegerDigits(int)
    7. setMinimumIntegerDigits(int)
    8. setMinimumFractionDigits(int)
    9. setMaximumFractionDigits(int)
    10. getRoundingMode()
    11. setRoundingMode(RoundingMode)
    12. getGroupingSize()
    13. setGroupingSize(int)
    14. isGroupingUsed()
    15. setGroupingUsed(boolean)
    16. isParseIntegerOnly()
    17. setParseIntegerOnly(boolean)
    18. isStrict()
    19. setStrict(boolean)
    20. isParseBigDecimal()
    21. setParseBigDecimal(boolean)
    22. equals(Object)
    23. hashCode()
    24. toString()
    25. clone()

Class CompactNumberFormat

java.lang.Object
java.text.Format
java.text.NumberFormat
java.text.CompactNumberFormat
All Implemented Interfaces:
Serializable, Cloneable
public final class CompactNumberFormat extends NumberFormat

CompactNumberFormat is a concrete subclass of NumberFormat that formats a decimal number in a localized compact form. Compact number formatting is designed for an environment with limited space. For example, displaying the formatted number 7M instead of 7,000,000.00 in the US locale. The CompactNumberFormat class is defined by LDML's specification for Compact Number Formats.

Getting a CompactNumberFormat

To get a compact number format, use one of the ways listed below.

If a standard compact format for a given locale and style is desired, it is recommended to use one of the NumberFormat factory methods listed above. To use an instance method defined by CompactNumberFormat, the NumberFormat returned by these factory methods should be type checked before converted to CompactNumberFormat. If the installed locale-sensitive service implementation does not support the given Locale, the parent locale chain will be looked up, and a Locale used that is supported.

Style

When using NumberFormat.getCompactNumberInstance(Locale, Style), a compact form can be retrieved with either a SHORT or LONG style. For example, a SHORT style compact number instance in the US locale formats 10000 as "10K". However, a LONG style instance in the same locale formats 10000 as "10 thousand".

Using CompactNumberFormat

The following is an example of formatting and parsing in a localized manner,
CopyCopy snippet [Copy snippet] 
NumberFormat compactFormat = NumberFormat.getCompactNumberInstance(Locale.US, NumberFormat.Style.SHORT);
compactFormat.format(1000); // returns "1K"
compactFormat.parse("1K"); // returns 1000

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.

Rounding

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

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.

Compact Number Patterns

The compactPatterns in CompactNumberFormat(decimalPattern, symbols, compactPatterns) are represented as a series of strings, where each string is a pattern that is used to format a range of numbers.

An example of the 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, the pattern at index 3 ("0K") is used for formatting a number in the range: 1000 <= number < 10000, index 4 ("00K") for formatting a number the range: 10000 <= number < 100000, and so forth.

In most 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.

Negative Subpatterns

A compact pattern contains a positive and negative subpattern separated by a subpattern boundary character ';', 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".

Escaping Special Characters

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. These characters must be quoted using single quotes ' (U+0027) unless noted otherwise, if they are to appear in the prefix or suffix as literals. For example, 0'.'.

Plurals

CompactNumberFormat support patterns for both singular and plural compact forms. For the plural form, the Pattern should consist of PluralPattern(s) separated by a space ' ' (U+0020) that are enumerated within a pair of curly brackets '{' (U+007B) and '}' (U+007D). In this format, each PluralPattern consists of its count, followed by a single colon ':' (U+003A) and a SimplePattern. As a space is reserved for separating subsequent PluralPatterns, it must be quoted to be used literally in either the prefix or suffix.

For example, while the pattern representing millions (106 ) in the US locale can be specified as the SimplePattern: "0 Million", for the German locale it can be specified as the PluralPattern: "{one:0' 'Million other:0' 'Millionen}".

A compact pattern has the following syntax, with count following LDML's Language Plural Rules: 

 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 characters except the special pattern characters
 Suffix:
      Any characters except the special pattern characters
 MinimumInteger:
      0
      0 MinimumInteger

Since:
12
External Specifications
See Also:

Report a bug or suggest an enhancement
For further API reference and developer documentation see the Java SE Documentation, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples. Other versions.
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 1993, 2025, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
All rights reserved. Use is subject to license terms and the documentation redistribution policy.

Web Proxy Viewer  |  New URL  |  Original Page