Module java.base
Package java.text

Class CompactNumberFormat

java.lang.Object
java.text.Format
java.text.NumberFormat
java.text.CompactNumberFormat
所有已实现的接口:
Serializable, Cloneable
public final class CompactNumberFormat extends NumberFormat

CompactNumberFormat是NumberFormat的一个具体子类，用于以紧凑形式格式化十进制数。紧凑数字格式设计用于空间有限的环境，并且格式化的字符串可以在该有限空间中显示。它由LDML的规范定义，用于紧凑数字格式。紧凑数字格式指的是根据给定区域设置提供的模式以较短形式表示数字。

例如：
在US区域中，1000可以格式化为"1K"，1000000可以格式化为"1M"，具体取决于所使用的样式。
在"hi_IN"区域中，1000可以格式化为"1 हज़ार"，50000000可以格式化为"5 क."，具体取决于所使用的样式。

要获取特定区域设置的CompactNumberFormat，请使用NumberFormat提供的紧凑数字格式工厂方法之一。例如，NumberFormat.getCompactNumberInstance(Locale, Style)。

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

样式

数字可以使用两种不同样式的紧凑形式进行格式化，SHORT和LONG。使用NumberFormat.getCompactNumberInstance(Locale, Style)来格式化和解析SHORT或LONG紧凑形式的数字，其中给定的Style参数请求所需的格式。在US区域中，SHORT样式的紧凑数字实例将10000格式化为"10K"。然而，同一区域中的LONG样式实例将10000格式化为"10 thousand"。

紧凑数字模式

紧凑数字模式由一系列模式表示，其中每个模式用于格式化一系列数字。以SHORT样式的紧凑数字模式为例，US区域的模式为{"", "", "", "0K", "00K", "000K", "0M", "00M", "000M", "0B", "00B", "000B", "0T", "00T", "000T"}，范围从100到1014。模式可以有任意数量，并且严格基于从100开始的索引。例如，在上述模式中，索引为3的模式（"0K"）用于格式化number >= 1000 and number < 10000，索引为4的模式（"00K"）用于格式化number >= 10000 and number < 100000等等。在大多数区域中，范围为100-102的模式为空字符串，隐含表示特殊模式"0"。特殊模式"0"用于不包含紧凑模式的任何范围。此特殊模式可以显式出现在任何特定范围，或被视为空字符串的默认模式。

紧凑模式包含由子模式边界字符';' (U+003B)分隔的正数和负数子模式，例如，"0K;-0K"。每个子模式都有前缀、最小整数位数和后缀。负数子模式是可选的，如果不存在，则正数子模式前缀带有减号（'-' U+002D HYPHEN-MINUS）作为负数子模式。也就是说，单独的"0K"等同于"0K;-0K"。如果存在显式负数子模式，则仅用于指定负数前缀和后缀。最小整数位数和其他特征与正数模式完全相同。这意味着"0K;-00K"产生的行为与"0K;-0K"完全相同。

紧凑模式中的许多字符都是按字面意义匹配的，在解析期间匹配并在格式化期间不改变输出。另一方面，特殊字符代表其他字符、字符串或字符类。如果这些特殊字符要出现在前缀或后缀中，则必须用单引号' (U+0027)引起来引用，除非另有说明。例如，0क'.'。

复数形式

如果某些本地化要求紧凑数字模式对复数形式有所不同，则每个单数和复数模式可以在一对大括号'{' (U+007B)和'}' (U+007D)之间枚举，用空格' ' (U+0020)分隔。如果使用此格式，每个模式都需要以其count开头，后跟一个冒号':' (U+003A)。如果模式包含空格，则必须用引号引起来。

例如，德语区域中表示百万的紧凑数字模式可以指定为"{one:0' 'Million other:0' 'Millionen}"。count遵循LDML的语言复数规则。

紧凑模式具有以下语法：

 模式:
         简单模式
         '{' 复数模式 [' ' 复数模式]可选 '}'
 简单模式:
         正数模式
         正数模式 [; 负数模式]可选
 复数模式:
         计数:简单模式
 计数:
         "zero" / "one" / "two" / "few" / "many" / "other"
 正数模式:
         前缀可选 最小整数 后缀可选
 负数模式:
        前缀可选 最小整数 后缀可选
 前缀:
      除U+FFFE、U+FFFF和
      特殊字符外的任何Unicode字符。
 后缀:
      除U+FFFE、U+FFFF和
      特殊字符外的任何Unicode字符。
 最小整数:
      0
      0 最小整数

格式化

默认的格式化行为返回一个没有小数位的格式化字符串，但用户可以使用setMinimumFractionDigits(int)方法来包含小数部分。数字1000.0或1000在US区域中被格式化为"1K"而不是"1.00K"。因此，用于格式化数字的模式仅包含最小整数位、前缀和/或后缀，但不包含小数部分。例如，使用的模式为{"", "", "", 0K, 00K, ...}。如果用于格式化数字的模式为"0"（特殊模式），无论是显式指定还是默认的，都将使用DecimalFormat为指定区域设置提供的一般数字格式。

解析

默认的解析行为不允许使用分组分隔符，直到通过使用setGroupingUsed(boolean)将分组设置为true。小数部分的解析取决于isParseIntegerOnly()。例如，如果仅解析整数设置为true，则小数部分将被跳过。

四舍五入

CompactNumberFormat提供了在格式化中使用的RoundingMode定义的四舍五入模式。默认情况下，它使用RoundingMode.HALF_EVEN。
自:
12
外部规范
参见:

  • Constructor Details

  • Method Details

    • format

      public final StringBuffer format(Object number, StringBuffer toAppendTo, FieldPosition fieldPosition)
      格式化数字以生成表示其紧凑形式的字符串。该数字可以是Number的任何子类。
      覆盖：
      format 在类 NumberFormat中
      参数：
      number - 要格式化的数字
      toAppendTo - 要附加格式化文本的StringBuffer
      fieldPosition - 跟踪返回字符串中字段的位置。例如，在US locale中格式化数字123456789，如果给定的fieldPosition是NumberFormat.INTEGER_FIELD，则fieldPosition的开始索引和结束索引将分别设置为0和3，用于输出字符串123M。类似地，可以使用NumberFormat.Field.PREFIX和NumberFormat.Field.SUFFIX获取前缀和后缀字段的位置。
      返回：
      作为toAppendTo传递的StringBuffer
      抛出：
      IllegalArgumentException - 如果number为null或不是Number的实例
      NullPointerException - 如果toAppendTo或fieldPosition为null
      ArithmeticException - 如果需要舍入且舍入模式设置为RoundingMode.UNNECESSARY
      参见：

    • format

      public StringBuffer format(double number, StringBuffer result, FieldPosition fieldPosition)
      格式化双精度数以生成表示其紧凑形式的字符串。
      指定者：
      format 在类 NumberFormat中
      参数：
      number - 要格式化的双精度数
      result - 要附加文本的位置
      fieldPosition - 跟踪返回字符串中字段的位置。例如，在US locale中格式化数字1234567.89，如果给定的fieldPosition是NumberFormat.INTEGER_FIELD，则fieldPosition的开始索引和结束索引将分别设置为0和1，用于输出字符串1M。类似地，可以使用NumberFormat.Field.PREFIX和NumberFormat.Field.SUFFIX获取前缀和后缀字段的位置。
      返回：
      作为result传递的StringBuffer
      抛出：
      NullPointerException - 如果result或fieldPosition为null
      ArithmeticException - 如果需要舍入且舍入模式设置为RoundingMode.UNNECESSARY
      参见：

    • format

      public StringBuffer format(long number, StringBuffer result, FieldPosition fieldPosition)
      格式化长整型数以生成表示其紧凑形式的字符串。
      指定者:
      format 在类 NumberFormat中
      参数:
      number - 要格式化的长整型数字
      result - 要附加文本的位置
      fieldPosition - 跟踪返回字符串中字段的位置。例如，要在US locale中格式化数字123456789，如果给定的fieldPosition是NumberFormat.INTEGER_FIELD，则fieldPosition的开始索引和结束索引将分别设置为0和3，输出字符串为123M。类似地，可以使用NumberFormat.Field.PREFIX和NumberFormat.Field.SUFFIX获取前缀和后缀字段的位置。
      返回:
      作为result传入的StringBuffer
      抛出:
      NullPointerException - 如果result或fieldPosition为null
      ArithmeticException - 如果需要四舍五入且四舍五入模式设置为RoundingMode.UNNECESSARY
      参见:

    • formatToCharacterIterator

      public AttributedCharacterIterator formatToCharacterIterator(Object obj)
      格式化一个对象，生成一个AttributedCharacterIterator。返回的AttributedCharacterIterator可用于构建结果字符串，以及确定有关结果字符串的信息。

      AttributedCharacterIterator的每个属性键将是NumberFormat.Field类型，属性值与属性键相同。返回的迭代器的前缀和后缀部分（如果存在）由属性NumberFormat.Field.PREFIX和NumberFormat.Field.SUFFIX表示。

      覆盖:
      formatToCharacterIterator 在类 Format中
      参数:
      obj - 要格式化的对象
      返回:
      描述格式化值的AttributedCharacterIterator
      抛出:
      NullPointerException - 如果obj为null
      IllegalArgumentException - 当格式无法格式化给定对象时
      ArithmeticException - 如果需要四舍五入且四舍五入模式设置为RoundingMode.UNNECESSARY

    • parse

      public Number parse(String text, ParsePosition pos)
      从字符串中解析紧凑数字以生成Number。

      该方法尝试解析从pos给定的索引开始的文本。如果解析成功，则pos的索引将更新为使用的最后一个字符之后的索引（解析不一定使用直到字符串末尾的所有字符），并返回解析的数字。更新后的pos可用于指示下一次调用此方法的起始点。如果发生错误，则pos的索引不会更改，pos的错误索引设置为发生错误的字符的索引，并返回null。

      值是给定文本中的数字部分乘以附加的数字等效部分（例如，在US locale中，"K" = 1000）。返回的子类取决于isParseBigDecimal()的值。

      • 如果isParseBigDecimal()为false（默认值），大多数整数值都作为Long对象返回，无论它们如何编写："17K"和"17.000K"都解析为Long.valueOf(17000)。如果值无法适应Long，则结果将作为Double返回。这包括具有小数部分的值、无限值、NaN和值-0.0。

        调用者可以使用Number方法doubleValue、longValue等来获取他们想要的类型。

      • 如果isParseBigDecimal()为true，则值将作为BigDecimal对象返回。特殊情况负无穷大和正无穷大以及NaN将作为包含相应Double常量值的Double实例返回。

      CompactNumberFormat解析所有表示十进制数字的Unicode字符，如Character.digit()定义。此外，CompactNumberFormat还将以DecimalFormatSymbols对象中定义的本地化零位数字开始的十个连续字符识别为数字。

      CompactNumberFormat解析不允许解析科学记数法。例如，在US locale中解析字符串"1.05E4K"在字符'E'处中断并返回1.05。

      指定者:
      parse 在类 NumberFormat中
      参数:
      text - 要解析的字符串
      pos - 一个带有索引和错误索引信息的ParsePosition对象，如上所述
      返回:
      解析的值，如果解析失败则返回null
      抛出:
      NullPointerException - 如果text或pos为null
      参见:

    • setMaximumIntegerDigits

      public void setMaximumIntegerDigits(int newValue)
      设置数字整数部分中允许的最大位数。如果newValue > 309，则最大允许的整数范围为309。负输入值将替换为0。
      覆盖:
      setMaximumIntegerDigits 在类 NumberFormat中
      参数:
      newValue - 要显示的整数位数的最大数目
      参见:

    • setMinimumIntegerDigits

      public void setMinimumIntegerDigits(int newValue)
      设置数字整数部分中允许的最小位数。如果newValue > 309，则最小允许的整数范围为309。负输入值将替换为0。
      覆盖:
      setMinimumIntegerDigits 在类 NumberFormat中
      参数:
      newValue - 要显示的整数位数的最小数目
      参见:

    • setMinimumFractionDigits

      public void setMinimumFractionDigits(int newValue)
      设置数字小数部分中允许的最小位数。如果newValue > 340，则最小允许的小数范围为340。负输入值将替换为0。
      覆盖:
      setMinimumFractionDigits 在类 NumberFormat中
      参数:
      newValue - 要显示的小数位数的最小数目
      参见:

    • setMaximumFractionDigits

      public void setMaximumFractionDigits(int newValue)
      设置数字小数部分中允许的最大位数。如果newValue > 340，则最大允许的小数范围为340。负输入值将替换为0。
      覆盖:
      setMaximumFractionDigits 在类 NumberFormat中
      参数:
      newValue - 要显示的小数位数的最大数目
      参见:

    • getRoundingMode

      public RoundingMode getRoundingMode()
      获取此CompactNumberFormat中使用的RoundingMode。
      覆盖:
      getRoundingMode 在类 NumberFormat中
      返回:
      用于此CompactNumberFormat的RoundingMode
      参见:

    • setRoundingMode

      public void setRoundingMode(RoundingMode roundingMode)
      设置此CompactNumberFormat中使用的RoundingMode。
      覆盖：
      setRoundingMode 在类 NumberFormat
      参数：
      roundingMode - 要使用的RoundingMode
      抛出：
      NullPointerException - 如果roundingMode为null
      参见：

    • getGroupingSize

      public int getGroupingSize()
      返回分组大小。分组大小是数字整数部分中分组分隔符之间的数字位数。例如，在紧凑数字"12,347万"中，对于US locale，分组大小为3。
      返回：
      分组大小
      参见：

    • setGroupingSize

      public void setGroupingSize(int newValue)
      设置分组大小。分组大小是数字整数部分中分组分隔符之间的数字位数。例如，在紧凑数字"12,347万"中，对于US locale，分组大小为3。分组大小必须大于或等于零且小于或等于127。
      参数：
      newValue - 新的分组大小
      抛出：
      IllegalArgumentException - 如果newValue为负数或大于127
      参见：

    • isGroupingUsed

      public boolean isGroupingUsed()
      如果此格式中使用分组，则返回true。例如，启用分组并将分组大小设置为3，则数字12346567890987654可以格式化为US locale中的"12,347万"。分组分隔符取决于区域设置。
      覆盖：
      isGroupingUsed 在类 NumberFormat
      返回：
      如果使用分组，则返回true; 否则返回false
      参见：

    • setGroupingUsed

      public void setGroupingUsed(boolean newValue)
      设置此格式中是否使用分组。
      覆盖：
      setGroupingUsed 在类 NumberFormat
      参数：
      newValue - 如果使用分组，则为true; 否则为false
      参见：

    • isParseIntegerOnly

      public boolean isParseIntegerOnly()
      如果此格式仅从紧凑数字的数字部分解析整数，则返回true。解析整数意味着仅从数字部分考虑整数部分，前缀/后缀仍然被考虑以计算结果输出。例如，在US locale中，如果此方法返回true，则字符串"1234.78千"将被解析为值1234000（1234（整数部分）* 1000（千）），并且小数部分将被跳过。解析操作接受的确切格式取决于区域设置。
      覆盖：
      isParseIntegerOnly 在类 NumberFormat
      返回：
      如果应将紧凑数字解析为仅整数，则返回true; 否则返回false

    • setParseIntegerOnly

      public void setParseIntegerOnly(boolean value)
      设置此格式是否仅从紧凑数字的数字部分解析整数。
      覆盖：
      setParseIntegerOnly 在类 NumberFormat
      参数：
      value - 如果应将紧凑数字解析为仅整数，则为true; 否则为false
      参见：

    • isParseBigDecimal

      public boolean isParseBigDecimal()
      返回parse(String, ParsePosition)方法是否返回BigDecimal。默认值为false。
      返回：
      如果解析方法返回BigDecimal，则返回true; 否则返回false
      参见：

    • setParseBigDecimal

      public void setParseBigDecimal(boolean newValue)
      设置parse(String, ParsePosition)方法是否返回BigDecimal。
      参数：
      newValue - 如果解析方法应返回BigDecimal，则为true; 否则为false
      参见：

    • equals

      public boolean equals(Object obj)
      检查此CompactNumberFormat是否等于指定的obj。将CompactNumberFormat类型的对象进行比较，其他类型返回false；遵守Object.equals的一般约定。
      覆盖：
      equals 在类 NumberFormat
      参数：
      obj - 要比较的对象
      返回：
      如果等于另一个CompactNumberFormat，则返回true
      参见：

    • hashCode

      public int hashCode()
      返回此CompactNumberFormat实例的哈希码。
      覆盖：
      hashCode 在类 NumberFormat
      返回：
      此CompactNumberFormat的哈希码
      参见：

    • clone

      public CompactNumberFormat clone()
      创建并返回此CompactNumberFormat实例的副本。
      覆盖：
      clone 在类 NumberFormat
      返回：
      此实例的克隆
      参见：