模块 java.base
包 java.text

类 NumberFormat

java.lang.Object
java.text.Format
java.text.NumberFormat
所有已实现的接口：
Serializable , Cloneable
已知子类：
ChoiceFormat , CompactNumberFormat , DecimalFormat
public abstract class NumberFormat extends Format
NumberFormat 是所有数字格式的抽象基类。此类提供用于格式化和解析数字的接口。 NumberFormat 还提供了确定哪些locale具有数字格式及其名称的方法。

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 locale 中的 "2K"。使用 getPercentInstance 获取显示百分比的格式。使用这种格式，0.53 之类的分数显示为 53%。

您还可以使用 setMinimumFractionDigits 等方法控制数字的显示。如果您想要更多地控制格式或解析，或者想要给您的用户更多的控制权，您可以尝试将从工厂方法获得的 NumberFormat 转换为 DecimalFormat 或 CompactNumberFormat，具体取决于所使用的工厂方法。这适用于绝大多数地区；请记住将它放在 try 块中，以防遇到不寻常的情况。

NumberFormat 和 DecimalFormat 的设计使得一些控件用于格式化，而其他控件用于解析。下面分别对这些控制方法进行详细说明，

setParseIntegerOnly ：仅影响解析，例如，如果为真，则“3456.78”→ 3456（并在索引 6 之后离开解析位置）如果为假，“3456.78”→ 3456.78（并在索引 8 之后离开解析位置）这与格式无关.如果您不想在小数点后可能没有数字的地方显示小数点，请使用 setDecimalSeparatorAlwaysShown。

setDecimalSeparatorAlwaysShown ：只影响格式，并且只影响小数点后可能没有数字的地方，例如像“#,##0.##”这样的模式，例如，如果为真，则 3456.00 → “3,456”。如果为假，则 3456.00 → "3456" 这与解析无关。如果希望解析在小数点处停止，请使用 setParseIntegerOnly。

您还可以将 parse 和 format 方法的形式与 ParsePosition 和 FieldPosition 结合使用，以允许您：

  • 逐步解析字符串的各个部分
  • 对齐小数点和其他区域
例如，您可以通过两种方式对齐数字：
  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 的实现和规范。

默认实现提供 RoundingMode 中定义的舍入模式来格式化数字。它使用 圆半偶数算法 。要更改舍入模式，请使用 setRoundingMode 。静态工厂方法返回的 NumberFormat 配置为使用半偶数舍入（请参阅 RoundingMode.HALF_EVEN ）对浮点数进行格式化。

自从：
1.1
参见：

  • 字段详细信息

    • INTEGER_FIELD

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

    • FRACTION_FIELD

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

  • 构造方法详细信息

    • NumberFormat

      protected NumberFormat()
      唯一的构造方法。 （对于子类构造方法的调用，通常是隐式的。）

  • 方法详情

    • format

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

      此实现使用 Number.longValue() 提取数字值，用于可以转换为 long 而不会丢失信息的所有整数类型值，包括 bit length 小于 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 为空或不是 Number 的实例。
      NullPointerException - 如果 toAppendTo 或 pos 为空
      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 - A String ，其中的一部分应该被解析。
      pos - 具有如上所述的索引和错误索引信息的 ParsePosition 对象。
      返回：
      从字符串中解析出的 Number。如果出现错误，则返回 null。
      抛出：
      NullPointerException - 如果 source 或 pos 为空。

    • format

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

    • format

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

    • format

      public abstract StringBuffer  format(double number, StringBuffer  toAppendTo, FieldPosition  pos)
      格式专业化。
      参数：
      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)
      格式专业化。
      参数：
      number - 要格式化的长数字
      toAppendTo - 要附加格式化文本的 StringBuffer
      pos - 跟踪字段在返回字符串中的位置。例如，要在 Locale.US locale中格式化数字 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 - 一个 String 的开头应该被解析。
      返回：
      从字符串中解析出的 Number。
      抛出：
      ParseException - 如果无法解析指定字符串的开头。

    • isParseIntegerOnly

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

    • setParseIntegerOnly

      public void setParseIntegerOnly(boolean value)
      设置数字是否应仅解析为整数。
      参数：
      value - true 如果数字应该只被解析为整数； false否则
      参见：

    • getInstance

      public static final NumberFormat  getInstance()
      返回当前默认 FORMAT locale的通用数字格式。这与调用 getNumberInstance() 相同。
      返回：
      用于通用数字格式化的 NumberFormat 实例

    • getInstance

      public static NumberFormat  getInstance(Locale  inLocale)
      返回指定locale的通用数字格式。这与调用 getNumberInstance(inLocale) 相同。
      参数：
      inLocale - 所需的locale
      返回：
      用于通用数字格式化的 NumberFormat 实例

    • getNumberInstance

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

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

      返回：
      用于通用数字格式化的 NumberFormat 实例
      参见：

    • getNumberInstance

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

    • getIntegerInstance

      public static final NumberFormat  getIntegerInstance()
      返回当前默认 FORMAT locale的整数格式。返回的数字格式配置为使用半偶数舍入（请参阅 RoundingMode.HALF_EVEN ）将浮点数舍入到最接近的整数以进行格式化，并仅解析输入字符串的整数部分（请参阅 isParseIntegerOnly ）。

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

      返回：
      整数值的数字格式
      自从：
      1.4
      参见：

    • getIntegerInstance

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

    • getCurrencyInstance

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

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

      返回：
      用于货币格式化的 NumberFormat 实例
      参见：

    • getCurrencyInstance

      public static NumberFormat  getCurrencyInstance(Locale  inLocale)
      返回指定locale的货币格式。

      如果指定的locale包含“cf”(货币格式样式)Unicode 扩展，则返回的货币格式使用可用的样式。否则，样式使用默认的“standard”货币格式。例如，如果样式指定“account”，则负货币金额在某些区域使用一对括号。

      参数：
      inLocale - 所需的locale
      返回：
      用于货币格式化的 NumberFormat 实例

    • getPercentInstance

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

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

      返回：
      百分比格式的 NumberFormat 实例
      参见：

    • getPercentInstance

      public static NumberFormat  getPercentInstance(Locale  inLocale)
      返回指定locale的百分比格式。
      参数：
      inLocale - 所需的locale
      返回：
      百分比格式的 NumberFormat 实例

    • getCompactNumberInstance

      public static NumberFormat  getCompactNumberInstance()
      返回默认 FORMAT locale的紧凑数字格式，格式样式为 "SHORT" 。
      返回：
      用于紧凑数字格式的 NumberFormat 实例
      自从：
      12
      参见：

    • getCompactNumberInstance

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

    • getAvailableLocales

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

    • hashCode

      public int hashCode()
      重写哈希代码。
      重写：
      hashCode 在类 Object 中
      返回：
      此对象的哈希码值。
      参见：

    • equals

      public boolean equals(Object  obj)
      重写等于。
      重写：
      equals 在类 Object 中
      参数：
      obj - 要比较的参考对象。
      返回：
      true 如果此对象与 obj 参数相同； false否则。
      参见：

    • clone

      public Object  clone()
      重写可克隆。
      重写：
      clone 在类 Format 中
      返回：
      此实例的克隆。
      参见：

    • isGroupingUsed

      public boolean isGroupingUsed()
      如果以这种格式使用分组，则返回 true。例如，在英语locale中，启用分组后，数字 1234567 可能会被格式化为“1,234,567”。分组分隔符以及每个组的大小取决于locale，并由 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()
      获取格式化货币值时此数字格式使用的货币。初始值以依赖于locale的方式导出。如果无法确定有效货币并且未使用 setCurrency 设置货币，则返回值可能为 null。

      默认实现抛出 UnsupportedOperationException 。

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

    • setCurrency

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

      默认实现抛出 UnsupportedOperationException 。

      参数：
      currency - 此数字格式要使用的新货币
      抛出：
      UnsupportedOperationException - 如果数字格式类没有实现货币格式
      NullPointerException - 如果 currency 为空
      自从：
      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 为空
      自从：
      1.6
      参见：