Module java.base
Package java.text

Class NumberFormat

java.lang.Object
java.text.Format
java.text.NumberFormat
所有已实现的接口:
Serializable, Cloneable
直接已知的子类:
ChoiceFormat, CompactNumberFormat, DecimalFormat
public abstract class NumberFormat extends Format
NumberFormat是所有数字格式的抽象基类。该类提供了格式化和解析数字的接口。NumberFormat还提供了确定哪些区域设置具有数字格式以及它们的名称的方法。

NumberFormat帮助您为任何区域设置格式化和解析数字。您的代码可以完全独立于小数点、千位分隔符的区域约定，甚至使用的特定小数位数，或者数字格式是否为十进制。

要为当前区域设置格式化数字，请使用工厂类方法之一:

myString = NumberFormat.getInstance().format(myNumber);
如果要格式化多个数字，最好获取格式并多次使用，以便系统不必多次获取有关本地语言和国家约定的信息。 
NumberFormat nf = NumberFormat.getInstance();
for (int i = 0; i < myNumber.length; ++i) {
    output.println(nf.format(myNumber[i]) + "; ");
}
要为不同的区域设置格式化数字，请在调用getInstance时指定它。 
NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);

如果区域设置包含"nu"（数字）和/或"rg"（区域覆盖）Unicode扩展，则用于格式化的小数位数和/或国家将被覆盖。如果同时指定了"nu"和"rg"，则来自"nu"扩展的小数位数将取代"rg"扩展的隐式小数位数。

您还可以使用NumberFormat来解析数字:

myNumber = nf.parse(myString);
使用getInstance或getNumberInstance来获取普通数字格式。使用getIntegerInstance来获取整数数字格式。使用getCurrencyInstance来获取货币数字格式。使用getCompactNumberInstance来获取紧凑数字格式，以便以更短的形式格式化数字。例如，2000可以在US区域设置中格式化为"2K"。使用getPercentInstance来获取用于显示百分比的格式。使用这种格式，类似0.53的分数将显示为53%。

您还可以使用诸如setMinimumFractionDigits之类的方法来控制数字的显示。如果您希望对格式或解析有更多控制，或者希望为用户提供更多控制，请尝试将从工厂方法获取的NumberFormat转换为DecimalFormat或CompactNumberFormat，具体取决于所使用的工厂方法。这将适用于绝大多数区域设置；只需记得将其放在try块中，以防遇到异常的区域设置。

NumberFormat和DecimalFormat设计得使一些控件用于格式化，另一些用于解析。以下是每个这些控件方法的详细描述:

setParseIntegerOnly：仅影响解析，例如，如果为true，则"3456.78" → 3456（并将解析位置留在索引6之后）如果为false，则"3456.78" → 3456.78（并将解析位置留在索引8之后）这与格式化无关。如果希望在可能没有小数点后没有数字的情况下不显示小数点，请使用setDecimalSeparatorAlwaysShown。

setDecimalSeparatorAlwaysShown：仅影响格式化，在可能没有小数点后没有数字的情况下，例如，使用类似"#,##0.##"的模式，例如，如果为true，则3456.00 → "3,456."如果为false，则3456.00 → "3456"这与解析无关。如果希望解析在小数点处停止，请使用setParseIntegerOnly。

您还可以使用带有ParsePosition和FieldPosition的parse和format方法的形式，以允许您:

  • 逐步解析字符串的各部分
  • 对齐小数点和其他区域
例如，您可以以两种方式对齐数字:
  1. 如果使用具有用于对齐的间距的等宽字体，则可以在格式调用中传递FieldPosition，其中field = INTEGER_FIELD。在输出中，getEndIndex将设置为整数的最后一个字符和小数点之间的偏移量。在字符串的前面添加（desiredSpaceCount - getEndIndex）个空格。
  2. 如果使用比例字体，而不是用空格填充，可以测量从开始到getEndIndex的字符串的像素宽度。然后在绘制文本之前将笔移动（desiredPixelWidth - widthToAlignmentPoint）。它还适用于没有小数点，但可能在末尾有其他字符的情况，例如，在负数中带有括号的情况："(12)"表示-12。

同步

数字格式通常不是同步的。建议为每个线程创建单独的格式实例。如果多个线程同时访问格式，则必须在外部进行同步。

实现要求:
format(double, StringBuffer, FieldPosition)，format(long, StringBuffer, FieldPosition)和parse(String, ParsePosition)方法可能会抛出NullPointerException，如果它们的任何参数为null。子类可以提供关于NullPointerException的自己的实现和规范。

默认实现提供了在格式化数字时使用的java.math.RoundingMode中定义的舍入模式。它使用round half-even算法。要更改舍入模式，请使用setRoundingMode。由静态工厂方法返回的NumberFormat被配置为使用半偶数舍入（参见java.math.RoundingMode.HALF_EVEN）来格式化浮点数。

自1.1版本起:
1.1
参见:

  • Field Details

    • INTEGER_FIELD

      public static final int INTEGER_FIELD
      用于构造 FieldPosition 对象的字段常量。表示应返回格式化数字的整数部分的位置。
      参见:

    • FRACTION_FIELD

      public static final int FRACTION_FIELD
      用于构造 FieldPosition 对象的字段常量。表示应返回格式化数字的小数部分的位置。
      参见:

  • Constructor Details

    • NumberFormat

      protected NumberFormat()
      唯一构造函数。（通常由子类构造函数隐式调用。）

  • Method Details

    • format

      public StringBuffer format(Object number, StringBuffer toAppendTo, FieldPosition pos)
      格式化数字并将结果文本附加到给定的字符串缓冲区。该数字可以是 Number 的任何子类。

      此实现使用 Number.longValue() 提取所有可以转换为 long 而不会丢失信息的整数类型值的值，包括具有比 64 小的 位长度 的 BigInteger 值，以及对于所有其他类型使用 Number.doubleValue()。然后调用 format(long,java.lang.StringBuffer,java.text.FieldPosition) 或 format(double,java.lang.StringBuffer,java.text.FieldPosition)。这可能导致对于 BigInteger 和 BigDecimal 值的幅度信息和精度的丢失。

      指定者:
      format 在类 Format 中
      参数:
      number - 要格式化的数字
      toAppendTo - 要附加格式化文本的 StringBuffer
      pos - 用于跟踪返回字符串中字段的位置。例如，在 Locale.US 区域设置中格式化数字 1234567.89 时，如果给定的 fieldPosition 是 INTEGER_FIELD，则 fieldPosition 的开始索引和结束索引将分别设置为 0 和 9，用于输出字符串 1,234,567.89。
      返回:
      作为 toAppendTo 传递的值
      抛出:
      IllegalArgumentException - 如果 number 为 null 或不是 Number 的实例。
      NullPointerException - 如果 toAppendTo 或 pos 为 null
      ArithmeticException - 如果需要舍入且舍入模式设置为 RoundingMode.UNNECESSARY
      参见:

    • parseObject

      public final Object parseObject(String source, ParsePosition pos)
      从字符串中解析文本以生成一个 Number。

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

      有关数字解析的更多信息，请参阅 parse(String, ParsePosition) 方法。

      指定者:
      parseObject 在类 Format 中
      参数:
      source - 应解析其中一部分的 String。
      pos - 一个 ParsePosition 对象，具有如上所述的索引和错误索引信息。
      返回:
      从字符串解析的 Number。在出现错误时返回 null。
      抛出:
      NullPointerException - 如果 source 或 pos 为 null。

    • format

      public final String format(double number)
      format 的特化。
      参数:
      number - 要格式化的双精度数
      返回:
      格式化后的字符串
      抛出:
      ArithmeticException - 如果需要舍入且舍入模式设置为 RoundingMode.UNNECESSARY
      参见:

    • format

      public final String format(long number)
      format 的特化。
      参数:
      number - 要格式化的长整型数
      返回:
      格式化后的字符串
      抛出:
      ArithmeticException - 如果需要舍入且舍入模式设置为 RoundingMode.UNNECESSARY
      参见:

    • format

      public abstract StringBuffer format(double number, StringBuffer toAppendTo, FieldPosition pos)
      format 的特化。
      参数:
      number - 要格式化的双精度数
      toAppendTo - 要附加格式化文本的 StringBuffer
      pos - 用于跟踪返回字符串中字段的位置。例如，在 Locale.US 区域设置中格式化数字 1234567.89 时，如果给定的 fieldPosition 是 INTEGER_FIELD，则 fieldPosition 的开始索引和结束索引将分别设置为 0 和 9，用于输出字符串 1,234,567.89。
      返回:
      格式化后的 StringBuffer
      抛出:
      ArithmeticException - 如果需要舍入且舍入模式设置为 RoundingMode.UNNECESSARY
      参见:

    • format

      public abstract StringBuffer format(long number, StringBuffer toAppendTo, FieldPosition pos)
      format 的特化。
      参数:
      number - 要格式化的长整型数
      toAppendTo - 要附加格式化文本的 StringBuffer
      pos - 用于跟踪返回字符串中字段的位置。例如，在 Locale.US 区域设置中格式化数字 123456789 时，如果给定的 fieldPosition 是 INTEGER_FIELD，则 fieldPosition 的开始索引和结束索引将分别设置为 0 和 11，用于输出字符串 123,456,789。
      返回:
      格式化后的 StringBuffer
      抛出:
      ArithmeticException - 如果需要舍入且舍入模式设置为 RoundingMode.UNNECESSARY
      参见:

    • parse

      public abstract Number parse(String source, ParsePosition parsePosition)
      返回一个Long（如果可能的话，例如在范围[Long.MIN_VALUE，Long.MAX_VALUE]内且没有小数），否则返回一个Double。如果设置了IntegerOnly，将在小数点（或等效物）处停止（例如，对于有理数"1 2/3"，将在1后停止）。不会抛出异常；如果无法解析任何对象，则索引保持不变！
      参数：
      source - 要解析的字符串
      parsePosition - 解析位置
      返回：
      解析后的值
      另请参阅：

    • parse

      public Number parse(String source) throws ParseException
      从给定字符串的开头解析文本以生成一个数字。该方法可能不会使用给定字符串的整个文本。

      有关数字解析的更多信息，请参阅parse(String, ParsePosition)方法。

      参数：
      source - 应解析其开头的字符串
      返回：
      从字符串解析的Number
      抛出：
      ParseException - 如果无法解析指定字符串的开头

    • isParseIntegerOnly

      public boolean isParseIntegerOnly()
      如果此格式仅解析数字作为整数，则返回true。例如，在英语区域设置中，如果ParseIntegerOnly为true，则字符串"1234."将被解析为整数值1234，并且解析将在"."字符处停止。当然，解析操作接受的确切格式取决于区域设置，并由NumberFormat的子类确定。
      返回：
      如果应仅解析数字作为整数，则返回true；否则返回false

    • setParseIntegerOnly

      public void setParseIntegerOnly(boolean value)
      设置是否仅应解析数字作为整数。
      参数：
      value - 如果应仅解析数字作为整数，则为true；否则为false
      另请参阅：

    • getInstance

      public static final NumberFormat getInstance()
      返回当前默认FORMAT区域设置的通用数字格式。这等同于调用getNumberInstance()。
      返回：
      用于通用数字格式的NumberFormat实例

    • getInstance

      public static NumberFormat getInstance(Locale inLocale)
      返回指定区域设置的通用数字格式。这等同于调用getNumberInstance(inLocale)。
      参数：
      inLocale - 所需的区域设置
      返回：
      用于通用数字格式的NumberFormat实例

    • getNumberInstance

      public static final NumberFormat getNumberInstance()
      返回当前默认FORMAT区域设置的通用数字格式。

      这相当于调用getNumberInstance(Locale.getDefault(Locale.Category.FORMAT))。

      返回：
      用于通用数字格式的NumberFormat实例
      另请参阅：

    • getNumberInstance

      public static NumberFormat getNumberInstance(Locale inLocale)
      返回指定区域设置的通用数字格式。
      参数：
      inLocale - 所需的区域设置
      返回：
      用于通用数字格式的NumberFormat实例

    • getIntegerInstance

      public static final NumberFormat getIntegerInstance()
      返回当前默认FORMAT区域设置的整数数字格式。返回的数字格式配置为使用半偶数舍入（参见RoundingMode.HALF_EVEN）将浮点数四舍五入到最接近的整数，用于格式化，并且仅解析输入字符串的整数部分（参见isParseIntegerOnly）。

      这相当于调用getIntegerInstance(Locale.getDefault(Locale.Category.FORMAT))。

      返回：
      用于整数值的数字格式
      自：
      1.4
      另请参阅：

    • getIntegerInstance

      public static NumberFormat getIntegerInstance(Locale inLocale)
      返回指定区域设置的整数数字格式。返回的数字格式配置为使用半偶数舍入（参见RoundingMode.HALF_EVEN）将浮点数四舍五入到最接近的整数，用于格式化，并且仅解析输入字符串的整数部分（参见isParseIntegerOnly）。
      参数：
      inLocale - 所需的区域设置
      返回：
      用于整数值的数字格式
      自：
      1.4
      另请参阅：

    • getCurrencyInstance

      public static final NumberFormat getCurrencyInstance()
      返回当前默认FORMAT区域设置的货币格式。

      这相当于调用getCurrencyInstance(Locale.getDefault(Locale.Category.FORMAT))。

      返回：
      用于货币格式的NumberFormat实例
      另请参阅：

    • getCurrencyInstance

      public static NumberFormat getCurrencyInstance(Locale inLocale)
      返回指定区域设置的货币格式。

      如果指定的区域设置包含"cf"（货币格式样式）Unicode扩展，则返回的货币格式将使用该样式（如果可用）。否则，该样式使用默认的"standard"货币格式。例如，如果样式指定为"account"，则在某些区域设置中，负货币金额使用一对括号。

      参数：
      inLocale - 所需的区域设置
      返回：
      用于货币格式的NumberFormat实例
      外部规范

    • getPercentInstance

      public static final NumberFormat getPercentInstance()
      返回当前默认FORMAT区域设置的百分比格式。

      这相当于调用getPercentInstance(Locale.getDefault(Locale.Category.FORMAT))。

      返回：
      用于百分比格式的NumberFormat实例
      另请参阅：

    • getPercentInstance

      public static NumberFormat getPercentInstance(Locale inLocale)
      返回指定区域设置的百分比格式。
      参数：
      inLocale - 所需的区域设置
      返回：
      用于百分比格式的NumberFormat实例

    • getCompactNumberInstance

      public static NumberFormat getCompactNumberInstance()
      返回默认FORMAT区域设置的紧凑数字格式，使用"SHORT"格式样式。
      返回：
      用于紧凑数字格式的NumberFormat实例
      自：
      12
      另请参阅：

    • getCompactNumberInstance

      public static NumberFormat getCompactNumberInstance(Locale locale, NumberFormat.Style formatStyle)
      返回指定locale和formatStyle的紧凑数字格式。
      参数：
      locale - 所需的区域设置
      formatStyle - 格式化数字的样式
      返回：
      用于紧凑数字格式的NumberFormat实例
      抛出：
      NullPointerException - 如果locale或formatStyle为null
      自：
      12
      另请参阅：

    • getAvailableLocales

      public static Locale[] getAvailableLocales()
      返回此类的get*Instance方法可以返回本地化实例的所有区域设置数组。返回的数组表示Java运行时支持的区域设置和已安装的NumberFormatProvider实现的联合。返回的数组至少必须包含等于Locale.ROOT和等于Locale.US的Locale实例。
      返回：
      可用于本地化NumberFormat实例的区域设置数组。

    • hashCode

      public int hashCode()
      覆盖hashCode。
      覆盖：
      hashCode 在类 Object
      返回：
      此对象的哈希码值。
      另请参见：

    • equals

      public boolean equals(Object obj)
      覆盖equals。
      覆盖：
      equals 在类 Object
      参数：
      obj - 用于比较的引用对象。
      返回：
      如果此对象与obj参数相同，则返回true; 否则返回false。
      另请参见：

    • clone

      public Object clone()
      覆盖Cloneable。
      覆盖：
      clone 在类 Format
      返回：
      此实例的克隆。
      另请参见：

    • isGroupingUsed

      public boolean isGroupingUsed()
      返回此格式中是否使用分组。例如，在英文区域设置中，启用分组后，数字1234567可能被格式化为"1,234,567"。分组分隔符以及每个组的大小是与区域设置相关的，并由NumberFormat的子类确定。
      返回：
      如果使用分组，则返回true; 否则返回false
      另请参见：

    • setGroupingUsed

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

    • getMaximumIntegerDigits

      public int getMaximumIntegerDigits()
      返回数字整数部分中允许的最大数字位数。
      返回：
      最大数字位数
      另请参见：

    • setMaximumIntegerDigits

      public void setMaximumIntegerDigits(int newValue)
      设置数字整数部分中允许的最大数字位数。maximumIntegerDigits必须≥minimumIntegerDigits。如果maximumIntegerDigits的新值小于当前的minimumIntegerDigits值，则minimumIntegerDigits也将设置为新值。
      参数：
      newValue - 要显示的整数位数的最大数字; 如果小于零，则使用零。具体的子类可以强制执行适合被格式化的数字类型的此值的上限。
      另请参见：

    • getMinimumIntegerDigits

      public int getMinimumIntegerDigits()
      返回数字整数部分中允许的最小数字位数。
      返回：
      最小数字位数
      另请参见：

    • setMinimumIntegerDigits

      public void setMinimumIntegerDigits(int newValue)
      设置数字整数部分中允许的最小数字位数。minimumIntegerDigits必须≤maximumIntegerDigits。如果minimumIntegerDigits的新值超过当前的maximumIntegerDigits值，则maximumIntegerDigits也将设置为新值。
      参数：
      newValue - 要显示的整数位数的最小数字; 如果小于零，则使用零。具体的子类可以强制执行适合被格式化的数字类型的此值的上限。
      另请参见：

    • getMaximumFractionDigits

      public int getMaximumFractionDigits()
      返回数字小数部分中允许的最大数字位数。
      返回：
      最大数字位数。
      另请参见：

    • setMaximumFractionDigits

      public void setMaximumFractionDigits(int newValue)
      设置数字小数部分中允许的最大数字位数。maximumFractionDigits必须≥minimumFractionDigits。如果maximumFractionDigits的新值小于当前的minimumFractionDigits值，则minimumFractionDigits也将设置为新值。
      参数：
      newValue - 要显示的小数位数的最大数字; 如果小于零，则使用零。具体的子类可以强制执行适合被格式化的数字类型的此值的上限。
      另请参见：

    • getMinimumFractionDigits

      public int getMinimumFractionDigits()
      返回数字小数部分中允许的最小数字位数。
      返回：
      最小数字位数
      另请参见：

    • setMinimumFractionDigits

      public void setMinimumFractionDigits(int newValue)
      设置数字小数部分中允许的最小数字位数。minimumFractionDigits必须≤maximumFractionDigits。如果minimumFractionDigits的新值超过当前的maximumFractionDigits值，则maximumFractionDigits也将设置为新值。
      参数：
      newValue - 要显示的小数位数的最小数字; 如果小于零，则使用零。具体的子类可以强制执行适合被格式化的数字类型的此值的上限。
      另请参见：

    • getCurrency

      public Currency getCurrency()
      获取此数字格式在格式化货币值时使用的货币。初始值以区域设置相关的方式派生。如果无法确定有效货币并且未使用setCurrency设置货币，则返回值可能为null。

      默认实现会抛出UnsupportedOperationException。

      返回：
      此数字格式使用的货币，或null
      抛出：
      UnsupportedOperationException - 如果数字格式类不实现货币格式化
      自：
      1.4

    • setCurrency

      public void setCurrency(Currency currency)
      设置此数字格式在格式化货币值时使用的货币。这不会更新数字格式使用的最小或最大小数位数。

      默认实现会抛出UnsupportedOperationException。

      参数：
      currency - 要由此数字格式使用的新货币
      抛出：
      UnsupportedOperationException - 如果数字格式类不实现货币格式化
      NullPointerException - 如果currency为null
      自：
      1.4

    • getRoundingMode

      public RoundingMode getRoundingMode()
      获取此NumberFormat中使用的RoundingMode。NumberFormat中此方法的默认实现始终会抛出UnsupportedOperationException。处理不同舍入模式的子类应该重写此方法。
      返回：
      用于此NumberFormat的RoundingMode。
      抛出：
      UnsupportedOperationException - 默认实现始终会抛出此异常
      自：
      1.6
      另请参见：

    • setRoundingMode

      public void setRoundingMode(RoundingMode roundingMode)
      设置此NumberFormat中使用的RoundingMode。NumberFormat中此方法的默认实现始终会抛出UnsupportedOperationException。处理不同舍入模式的子类应该重写此方法。
      参数:
      roundingMode - 要使用的RoundingMode
      抛出:
      UnsupportedOperationException - 默认实现始终抛出此异常
      NullPointerException - 如果roundingMode为null
      自从:
      1.6
      参见: