模块 java.base
包 java.text

类 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 locale 中，1000 可以格式化为 "1K"，1000000 可以格式化为 "1M"，具体取决于使用的 style。
在 "hi_IN" locale中，1000 可以格式化为“1 हज़ार”，50000000 可以格式化为“5 क.”，具体取决于使用的 style。

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

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

Style

可以将数字格式化为具有两种不同样式的紧凑形式，SHORT 和 LONG 。使用 NumberFormat.getCompactNumberInstance(Locale, Style) 以 SHORT 或 LONG 紧凑形式格式化和解析数字，其中给定的 Style 参数请求所需的格式。 SHORT 样式的紧凑型数字实例，采用 US locale 格式，10000 为 "10K"。但是，相同locale中的 LONG 样式实例会将 10000 格式设置为 "10 thousand"。

紧凑的数字模式

紧凑的数字模式以一系列模式表示，其中每个模式用于格式化一系列数字。 US locale 的 SHORT 样式紧凑数字模式的示例是 {"", "", "", "0K", "00K", "000K", "0M", "00M", "000M", "0B", "00B", "000B", "0T", "00T", "000T"}，范围从 100 到1014 .可以有任意数量的模式，它们严格基于从 10 范围开始的索引0 .例如，在上述模式中，索引 3 处的模式 ("0K") 用于格式化 number >= 1000 and number < 10000，索引 4 处的模式 ("00K") 用于格式化 number >= 10000 and number < 100000，依此类推。在大多数locale中，模式的范围为 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) 。如果模式按字面意思包含空格，则必须将它们加引号。

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

紧凑模式具有以下语法：

 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 U+FFFE , U+FFFF , and
   special characters.
 Suffix:
   Any Unicode characters except U+FFFE , U+FFFF , and
   special characters.
 MinimumInteger:
   0
   0 MinimumInteger

格式化

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

解析

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

四舍五入

CompactNumberFormat 提供在 RoundingMode 中定义的舍入模式用于格式化。默认情况下，它使用 RoundingMode.HALF_EVEN 。
自从：
12
参见：

  • 构造方法详细信息

  • 方法详情

    • 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 ，则对于输出字符串 123M，fieldPosition 的开始索引和结束索引将分别设置为 0 和 3。类似地，可以分别使用NumberFormat.Field.PREFIX 和NumberFormat.Field.SUFFIX 获得前缀和后缀字段的位置。
      返回：
      StringBuffer 作为 toAppendTo 传入
      抛出：
      IllegalArgumentException - 如果 number 是 null 或者不是 Number 的实例
      NullPointerException - 如果 toAppendTo 或 fieldPosition 是 null
      ArithmeticException - 如果需要将舍入模式设置为 RoundingMode.UNNECESSARY 的舍入
      参见：

    • format

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

    • format

      public StringBuffer  format(long number, StringBuffer  result, FieldPosition  fieldPosition)
      格式化 long 以生成表示其紧凑形式的字符串。
      指定者：
      format 在类 NumberFormat 中
      参数：
      number - 要格式化的长数字
      result - 要附加文本的位置
      fieldPosition - 跟踪字段在返回字符串中的位置。例如，要格式化 US locale 中的数字 123456789，如果给定的 fieldPosition 是 NumberFormat.INTEGER_FIELD ，则 fieldPosition 的开始索引和结束索引将分别设置为 0 和 3，用于输出字符串 123M。类似地，可以分别使用NumberFormat.Field.PREFIX 和NumberFormat.Field.SUFFIX 获得前缀和后缀字段的位置。
      返回：
      StringBuffer 作为 result 传入
      抛出：
      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 为空
      IllegalArgumentException - 当 Format 无法格式化给定对象时
      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() 为真，则值作为 BigDecimal 对象返回。负无穷大和正无穷大以及 NaN 的特殊情况作为 Double 实例返回，其中包含相应的 Double 常量的值。

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

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

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

    • setMaximumIntegerDigits

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

    • setMinimumIntegerDigits

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

    • setMinimumFractionDigits

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

    • setMaximumFractionDigits

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

    • getRoundingMode

      public RoundingMode  getRoundingMode()
      获取在此 CompactNumberFormat 中使用的 RoundingMode 。
      重写：
      getRoundingMode 在类 NumberFormat 中
      返回：
      RoundingMode 用于此 CompactNumberFormat
      参见：

    • setRoundingMode

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

    • getGroupingSize

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

    • setGroupingSize

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

    • isGroupingUsed

      public boolean isGroupingUsed()
      如果以这种格式使用分组，则返回 true。例如，将分组依据和分组大小设置为 3，数字 12346567890987654 可以在 US locale 中格式化为 "12,347 trillion"。分组分隔符取决于locale。
      重写：
      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 thousand" 将被解析为值 1234000（1234（整数部分）* 1000（千）），小数部分将被跳过。解析操作接受的确切格式取决于locale。
      重写：
      isParseIntegerOnly 在类 NumberFormat 中
      返回：
      true 紧凑型数字是否应仅解析为整数； false否则

    • setParseIntegerOnly

      public void setParseIntegerOnly(boolean value)
      设置此格式是否仅解析紧凑数字的数字部分中的整数。
      重写：
      setParseIntegerOnly 在类 NumberFormat 中
      参数：
      value - true 紧凑型数字是否应仅解析为整数； false否则
      参见：

    • isParseBigDecimal

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

    • setParseBigDecimal

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

    • equals

      public boolean equals(Object  obj)
      检查此 CompactNumberFormat 是否等于指定的 obj 。比较CompactNumberFormat类型的对象，其他类型返回false；遵守 Object.equals 的总合同。
      重写：
      equals 在类 NumberFormat 中
      参数：
      obj - 要与之比较的对象
      返回：
      如果这等于另一个 CompactNumberFormat 则为真
      参见：

    • hashCode

      public int hashCode()
      返回此 CompactNumberFormat 实例的哈希码。
      重写：
      hashCode 在类 NumberFormat 中
      返回：
      这个 CompactNumberFormat 的哈希码
      参见：

    • clone

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