java.util
类 Formatter

java.lang.Object
  java.util.Formatter

所有已实现的接口：

Closeable, Flushable

public final class Formatter
     

      extends 
      Object
     
     

      implements 
      Closeable, 
      Flushable
     

printf 风格的格式字符串的解释程序。此类提供了对布局对齐和排列的支持，以及对数值、字符串和日期/时间数据的常规格式和特定于语言环境的输出的支持。支持诸如 byte、BigDecimal 和 Calendar 等常见 Java 类型。任意用户类型的受限格式化定制都是通过 Formattable 接口提供的。

Formatter 对于多线程访问而言没必要是安全的。线程安全是可选的，它对此类中的方法用户负责。

Java 语言的格式化输出在很大程度上受到 C 语言 printf 的启发。虽然一些格式字符串与 C 类似，但已进行了某些定制，以适应 Java 语言，并且利用了其中一些特性。此外，Java 的格式比 C 的格式更严格；例如，如果转换与标志不兼容，则会抛出异常。在 C 中，不适用的标志会被忽略。这样，便于 C 程序员识别这些格式字符串，而又不必与 C 中的那些标志完全兼容。

所期望用法的示例：

   StringBuilder sb = new StringBuilder();
   // Send all output to the Appendable object sb
   Formatter formatter = new Formatter(sb, Locale.US);

   // Explicit argument indices may be used to re-order output.
   formatter.format("%4$2s %3$2s %2$2s %1$2s", "a", "b", "c", "d")
   // -> " d  c  b  a"

   // Optional locale as the first argument can be used to get
   // locale-specific formatting of numbers.  The precision and width can be
   // given to round and align the value.
   formatter.format(Locale.FRANCE, "e = %+10.4f", Math.E);
   // -> "e =    +2,7183"

   // The '(' numeric flag may be used to format negative numbers with
   // parentheses rather than a minus sign.  Group separators are
   // automatically inserted.
   formatter.format("Amount gained or lost since last statement: $ %(,.2f",
                    balanceDelta);
   // -> "Amount gained or lost since last statement: $ (6,217.58)"
 

常见格式化请求的便捷方法是按照如下调用格式来阐明的：

   // Writes a formatted string to System.out.
   System.out.format("Local time: %tT", Calendar.getInstance());
   // -> "Local time: 13:34:18"

   // Writes formatted output to System.err.
   System.err.printf("Unable to open file '%1$s': %2$s",
                     fileName, exception.getMessage());
   // -> "Unable to open file 'food': No such file or directory"
 

与 C 语言的 sprintf(3) 类似，可以使用静态方法 String#format(String,Object...)String.format 来格式化 Strings：

   // Format a string containing a date.
   import java.util.Calendar;
   import java.util.GregorianCalendar;
   import static java.util.Calendar.*;

   Calendar c = new GregorianCalendar(1995, MAY, 23);
   String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
   // -> s == "Duke's Birthday: May 23, 1995"
 

结构

此规范分为两部分。第一部分是摘要，包括基本的格式概念。这一部分是为那些想要快速入门并熟悉其他编程语言的格式化输出的用户准备的。第二部分是详细信息，包括具体的实现细节。它是为那些需要更精确格式化行为规范的用户准备的。

摘要

这一部分将提供对格式概念的简单概述。有关精确的行为细节，请参阅详细信息部分。

格式字符串语法

产生格式化输出的每个方法都需要格式字符串 和参数列表。格式字符串是一个 String，它可以包含固定文本以及一个或多个嵌入的格式说明符。请考虑以下示例：

   Calendar c = ...;
   String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
 

• 常规类型、字符类型和数值类型的格式说明符的语法如下：

     %[argument_index$][flags][width][.precision]conversion
   

  可选的 argument_index 是一个十进制整数，用于表明参数在参数列表中的位置。第一个参数由 "1$" 引用，第二个参数由 "2$" 引用，依此类推。

  可选 flags 是修改输出格式的字符集。有效标志集取决于转换类型。

  可选 width 是一个非负十进制整数，表明要向输出中写入的最少字符数。

  可选 precision 是一个非负十进制整数，通常用来限制字符数。特定行为取决于转换类型。

  所需 conversion 是一个表明应该如何格式化参数的字符。给定参数的有效转换集取决于参数的数据类型。

• 用来表示日期和时间类型的格式说明符的语法如下：

     %[argument_index$][flags][width]conversion
   

  可选的 argument_index、flags 和 width 的定义同上。

  所需的 conversion 是一个由两字符组成的序列。第一个字符是 't' 或 'T'。第二个字符表明所使用的格式。这些字符类似于但不完全等同于那些由 GNU date 和 POSIX strftime(3c) 定义的字符。

• 与参数不对应的格式说明符的语法如下：

     %[flags][width]conversion
   

  可选 flags 和 width 的定义同上。

  所需的 conversion 是一个表明要在输出中所插内容的字符。

转换

转换可分为以下几类：

1. 常规 - 可应用于任何参数类型
2. 字符 - 可应用于表示 Unicode 字符的基本类型：char、Character、byte、Byte、short 和 Short。当 Character.isValidCodePoint(int) 返回 true 时，可将此转换应用于 int 和 Integer 类型
3. 数值
   1. 整数 - 可应用于 Java 的整数类型：byte、Byte、short、Short、int、Integer、long、Long 和 BigInteger
   2. 浮点 - 可用于 Java 的浮点类型：float、Float、double、Double 和 BigDecimal
4. 日期/时间 - 可应用于 Java 的、能够对日期或时间进行编码的类型：long、Long、Calendar 和 Date。
5. 百分比 - 产生字面值 '%' ('\u0025')
6. 行分隔符 - 产生特定于平台的行分隔符

下表总结了受支持的转换。由大写字符（如 'B'、'H'、'S'、'C'、'X'、'E'、'G'、'A' 和 'T'）表示的转换与由相应的小写字符的转换等同，根据流行的 Locale 规则将结果转换为大写形式除外。后者等同于 String.toUpperCase() 的以下调用

    out.toUpperCase() 

任何未明确定义为转换的字符都是非法字符，并且都被保留，以供将来扩展使用。

日期/时间转换

以下日期和时间转换的后缀字符是为 't' 和 'T' 转换定义的。这些类型相似于但不完全等同于那些由 GNU date 和 POSIX strftime(3c) 定义的类型。提供其他转换类型是为了访问特定于 Java 的功能（如将 'L' 用作秒中的毫秒）。

以下转换字符用来格式化时间：

以下转换字符用来格式化日期：

以下转换字符用于格式化常见的日期/时间组合。

任何未明确定义为转换的字符都是非法字符，并且都被保留，以供将来扩展使用。

标志

下表总结了受支持的标志。y 表示该标志受指示参数类型支持。

¹ 取决于 Formattable 的定义。

² 只适用于 'd' 转换。

³ 只适用于 'o'、'x' 和 'X' 转换。

⁴ 对 BigInteger 应用 'd'、'o'、'x' 和 'X' 转换时，或者对 byte 及 Byte、short 及 Short、int 及 Integer、long 及 Long 分别应用 'd' 转换时适用。

⁵ 只适用于 'e'、'E'、'f'、'g' 和 'G' 转换。

任何未显式定义为标志的字符都是非法字符，并且都被保留，以供扩展使用。

宽度

宽度是将向输出中写入的最少字符数。对于行分隔符转换，不适用宽度，如果提供宽度，则会抛出异常。

精度

对于常规参数类型，精度是将向输出中写入的最多字符数。

对于浮点转换 'e'、'E' 和 'f'，精度是小数点分隔符后的位数。如果转换是 'g' 或 'G'，那么精度是舍入计算后所得数值的所有位数。如果转换是 'a' 或 'A'，则不必指定精度。

对于字符、整数和日期/时间参数类型转换，以及百分比和行分隔符转换，精度是不适用的；如果提供精度，则会抛出异常。

参数索引

参数索引是一个十进制整数，用于表明参数在参数列表中的位置。第一个参数由 "1$" 引用，第二个参数由 "2$" 引用，依此类推。

根据位置引用参数的另一种方法是使用 '<' ('\u003c') 标志，这将会重用以前格式说明符的参数。例如，以下两条语句产生的字符相同：

   Calendar c = ...;
   String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);

   String s2 = String.format("Duke's Birthday: %1$tm %<te,%<tY", c);
 

详细信息

这一部分将提供格式化行为规范方面的细节，其中包括条件和异常、受支持的数据类型、本地化以及标志、转换和数据类型之间的交互。有关格式化概念的概述，请参阅摘要。

任何未明确定义为转换、日期/时间转换前缀或标志的字符都是非法字符，并且这些字符都被保留，以供未来扩展使用。在格式字符串中使用这样的字符会导致抛出 UnknownFormatConversionException 或 UnknownFormatFlagsException。

如果格式说明符包含带有无效值或不受支持的其他值的宽度或精度，则将分别抛出 IllegalFormatWidthException 或 IllegalFormatPrecisionException。

如果格式说明符包含不适用于对应参数的转换字符，则将抛出 IllegalFormatConversionException。

所有指定异常都可能被 Formatter 的任何 format 方法以及任何 format 的便捷方法抛出，比如 String#format(String,Object...)String.format 和 java.io.PrintStream#printf(String,Object...)PrintStream.printf。 String.format} and PrintStream.printf.

由大写字符（如 'B'、'H'、'S'、'C'、'X'、'E'、'G'、'A' 和 'T'）表示的转换与那些相应的小写字符表示的转换相同，根据流行的 Locale 规则将结果转换成大写形式除外。结果等同于 String.toUpperCase() 的以下调用

    out.toUpperCase() 

常规

以下常规转换可应用于任何参数类型：

以下 标志 应用于常规转换：

宽度 是将向输出中写入的最少字符数。如果转换值的长度小于宽度，则用 '  ' (\u0020') 填充输出，直到字符总数等于宽度为止。默认情况下，是在左边进行填充。如果给出 '-' 标志，则在右边进行填充。如果没有指定宽度，则没有最小宽度。

精度是将向输出中写入的最多字符数。精度的应用要先于宽度，因此，即使宽度大于精度，输出也将被截取为 precision 字符。如果没有指定精度，则对字符数没有明确限制。

字符

'-' 标志是为应用常规转换而定义的。如果给出 '#' 标志，则将抛出 FormatFlagsConversionMismatchException。

宽度是为了实现常规转换而定义的。

精度不适用。如果指定精度，则将抛出 IllegalFormatPrecisionException。

数值

数值转换分为以下几类：

1. Byte、Short、Integer 和 Long
2. BigInteger
3. Float 和 Double
4. BigDecimal

将根据以下算法对数值类型进行格式化：

数字本地化算法

在获得数字的整数部分、小数部分和指数（适用于数据类型）之后，将应用以下转换：

1. 将字符串中的每个数字字符 d 都替换为特定于语言环境的数字，该数字是相对于当前语言环境的零数字 z 来计算的；即 d -  '0'  + z。
2. 如果存在小数点分隔符，则用特定于语言环境的小数点分隔符替换。
3. 如果给出 ',' ('\u002c') flag 标志，则插入特定于语言环境的组分隔符，这是通过从最低位到最高位浏览字符串的整数部分并不时插入该语言环境组大小定义的分隔符来实现的。
4. 如果给出 '0' 标志，则在符号字符（如果有的话）之后、第一个非零数字前插入特定于语言环境的零数字，直到字符串长度等于所要求的字段宽度。
5. 如果该值为负，并且给出了 '(' 标志，那么预先考虑 '(' ('\u0028')，并追加一个 ')' ('\u0029')。
6. 如果该值为负（或者为浮点负零），并且没有给出 '(' 标志，那么预先考虑 '-' ('\u002d')。
7. 如果给出 '+' 标志，并且该值为正或零（或者为浮点正零），那么将预先考虑 '+' ('\u002b')。

如果该值为 NaN 或正无穷大，则分别输出文本字符串 "NaN" 或 "Infinity"。如果该值为负无穷大，那么输出将是 "(Infinity)"；否则如果给出 '(' 标志，那么输出将是 "-Infinity"。这些值都没有被本地化。

Byte、Short、Integer 和 Long

以下转换可应用于 byte、Byte、short、Short、int、Integer、long 和 Long。

如果该转换是 'o'、'x' 或 'X' 转换，并且给出了 '#' 和 '0' 标志，那么结果将包含基数指示符（对于八进制是 '0'，对于十六进制是 '0' 或 "0x"）、一定数量的零（基于宽度）和该值。

如果没有给出 '-' 标志，则在符号前填充空格。

以下 标志 应用于数值整数转换：

如果没有给出 标志 ，则默认格式设置如下：

• width 中的输出是右对齐的
• 负数以 '-' ('\u002d') 开始
• 正数和零不包括符号或额外的前导空格
• 不包括组分隔符

The 宽度 是将向输出中写入的最少字符数。这包括所有符号、数字、组分隔符、基数指示符和圆括号。如果转换值的长度小于宽度，则用空格('\u0020') 填充输出，直到字符总数等于宽度。默认情况下，在左边进行填补。如果给出 '-' 标志，则在右边进行填补。如果没有指定宽度，则没有最小宽度。

精度不适用。如果指定精度，则将抛出 IllegalFormatPrecisionException。

BigInteger

以下转换可应用于 BigInteger。

如果该转换是 'o'、'x' 或 'X'，并且给出了 '#' 和 '0' 标志，那么结果将包含基数指示符（对于八进制是 '0'，对于十六进制是 '0' 或 "0x"）、一定数量的零（基于宽度）和该值。

如果给出 '0' 标志，并且值为负，则在符号后填充零。

如果没有给出 '-' 标志，则在符号前填充空格。

应用为 Byte、Short、Integer 和 Long 定义的所有标志。没有给出标志时的默认行为与 Byte、Short、Integer 和 Long 的行为相同。

宽度的规范与为 Byte、Short、Integer 和 Long 定义的规范相同。

精度不适用。如果指定精度，则将抛出 IllegalFormatPrecisionException。

Float 和 Double

以下转换可应用于 float、Float、double 和 Double。

应用为 Byte、Short、Integer 和 Long 定义的所有标志。

如果给出 '#' 标志，则将始终存在小数点分隔符。

如果没有给出 标志 则默认格式设置如下：

• width 中的输出是右对齐的。
• 负数以 '-' 开头
• 正数和正零不包括符号或额外的前导空格
• 不包括组分隔符
• 小数点分隔符只在后面有数字时才出现

The 宽度 是将向输出中写入的最少字符数。这包括可应用的所有符号、数字、组分隔符、小数点分隔符、指数符号、基数指示符、圆括号和表示无穷大和 NaN 的字符串。如果转换值的长度小于宽度，则用空格('\u0020') 填充输出，直到字符总数等于宽度。默认情况下，在左边进行填充。如果给出 '-' 标志，则在右边进行填充。如果没有指定宽度，则没有最小宽度。

如果 转换 是 'e'、'E' 或 'f'，则精度是小数点分隔符后的位数。如果没有指定精度，则假定精度为 6。

如果转换是 'g' 或 'G' 转换，那么精度就是舍入运算后所得数值的总有效位数。如果没有指定精度，则默认值为 6。如果精度为 0，则该值将为 1。

如果转换是 'a' 或 'A' 转换，则精度是小数点分隔符后十六进制数字的位数。如果没有提供精度，则将输出 Double.toHexString(double) 返回的所有数字。

BigDecimal

以下转换可应用于 BigDecimal。