java.lang.Object

java.util.Formatter

所有已实现的接口：: Closeable , Flushable , AutoCloseable

public final class Formatter extends Object implements Closeable , Flushable

printf 样式格式字符串的解释器。此类提供对布局对齐和对齐、数字、字符串和日期/时间数据的通用格式以及特定于区域设置的输出的支持。支持 byte 、 BigDecimal 和 Calendar 等常见 Java 类型。通过 Formattable 接口为任意用户类型提供有限的格式自定义。

格式化程序对于多线程访问不一定是安全的。线程安全是可选的，是此类中方法的用户的责任。

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 进行格式化：

  // 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$tb %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);

此格式字符串是 format 方法的第一个参数。它包含三个格式说明符“%1$tm”、“%1$te”和“%1$tY”，指示应如何处理参数以及应将它们插入文本中的位置。格式字符串的其余部分是固定文本，包括 "Dukes Birthday: " 和任何其他空格或标点符号。参数列表包含在格式字符串之后传递给方法的所有参数。在上面的示例中，参数列表的大小为 1，由 Calendar 对象 c 组成。

一般、字符和数字类型的格式说明符具有以下语法：
```
  %[argument_index$][flags][width][.precision]conversion
 
```
可选的参数索引是一个十进制整数，指示参数在参数列表中的位置。第一个参数由“1$”引用，第二个由“2$”引用，依此类推。
可选的flags是一组修改输出格式的字符。有效标志集取决于转换。
可选的宽度是一个十进制正整数，表示要写入输出的最少字符数。
可选的精确是一个非负十进制整数，通常用于限制字符数。具体行为取决于转换。
所需转换是一个字符，指示应如何格式化参数。给定参数的有效转换集取决于参数的数据类型。
用于表示日期和时间的类型的格式说明符具有以下语法：
```
  %[argument_index$][flags][width]conversion
 
```
可选的参数索引, flags和宽度定义如上。
所需转换是两个字符序列。第一个字符是 't' 或 'T' 。第二个字符表示要使用的格式。这些字符与 GNU date 和 POSIX strftime(3c) 定义的字符相似但不完全相同。
与参数不对应的格式说明符具有以下语法：
```
  %[flags][width]conversion
 
```
可选的flags和宽度定义如上。
所需转换是一个字符，指示要在输出中插入的内容。

转换

转换分为以下几类：

一般的- 可以应用于任何参数类型
Character- 可应用于表示 Unicode 字符的基本类型：char、Character 、byte、Byte 、short 和 Short 。当 Character.isValidCodePoint(int) 返回 true 时，此转换也可应用于类型 int 和 Integer
数字
1. 不可缺少的- 可应用于 Java 整数类型：byte、Byte 、short、Short 、int 和 Integer 、long、Long 和 BigInteger （但不适用于 char 或 Character )
2. 浮点- 可应用于 Java 浮点类型：float、Float 、double、Double 和 BigDecimal
约会时间- 可应用于能够编码日期或时间的 Java 类型：long、Long 、Calendar 、Date 和 TemporalAccessor
百分- 产生文字 '%' ('\u0025' )
行分隔符- 生成特定于平台的行分隔符

对于类别一般的, Character, 数字, 不可缺少的和约会时间转换，除非另有说明，如果参数参数是 null ，则结果是“null”。

下表总结了支持的转换。由大写字符表示的转换（即 'B' 、 'H' 、 'S' 、 'C' 、 'X' 、 'E' 、 'G' 、 'A' 和 'T' ）与对应的小写字符相同-case 转换字符除了将结果转换为大写案例根据通行的Locale 规则。如果没有明确指定locale，无论是在构造实例时还是作为其方法调用的参数，都会使用 default locale 。

genConv
转换	参数类别	Description
`'b'` , `'B'`	一般的	如果参数参数是`null`，则结果是“`false`”。如果参数是 `boolean` 或 `Boolean` ，那么结果就是 `String.valueOf(arg)` 返回的字符串。否则，结果为“真”。
`'h'` , `'H'`	一般的	结果是通过调用 `Integer.toHexString(arg.hashCode())` 获得的。
`'s'` , `'S'`	一般的	如果参数实现 `Formattable` ，然后调用 `arg.formatTo` 。否则，通过调用 `arg.toString()` 获得结果。
`'c'` , `'C'`	character	结果是一个 Unicode 字符
`'d'`	不可缺少的	结果被格式化为十进制整数
`'o'`	不可缺少的	结果被格式化为八进制整数
`'x'` , `'X'`	不可缺少的	结果被格式化为十六进制整数
`'e'` , `'E'`	浮点	结果被格式化为计算机科学记数法中的十进制数
`'f'`	浮点	结果被格式化为十进制数
`'g'` , `'G'`	浮点	根据四舍五入后的精度和值，使用计算机化的科学记数法或十进制格式对结果进行格式化。
`'a'` , `'A'`	浮点	结果被格式化为带有尾数和指数的十六进制浮点数。这种转换是not支持 `BigDecimal` 类型，尽管后者在浮点参数类别。
`'t'` , `'T'`	date/time	日期和时间转换字符的前缀。参见日期/时间转换。
`'%'`	百分	结果是文字 `'%'` (`'\u0025'` )
`'n'`	行分隔符	结果是特定于平台的行分隔符

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

日期/时间转换

以下日期和时间转换后缀字符是为 't' 和 'T' 转换定义的。这些类型与 GNU date 和 POSIX strftime(3c) 定义的类型相似但不完全相同。提供了额外的转换类型来访问特定于 Java 的功能（例如，'L' 表示秒内的毫秒数）。

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

time
转换	Description
`'H'`	24 小时制的一天中的小时，根据需要格式化为带有前导零的两位数，即 `00 - 23` 。
`'I'`	12 小时制的小时，根据需要格式化为带前导零的两位数，即 `01 - 12` 。
`'k'`	24 小时制的一天中的小时，即 `0 - 23` 。
`'l'`	12 小时制的小时，即 `1 - 12` 。
`'M'`	小时内的分钟，根据需要格式化为带前导零的两位数，即 `00 - 59` 。
`'S'`	分钟内的秒数，根据需要格式化为带前导零的两位数，即 `00 - 60`（“`60`”是支持闰秒所需的特殊值）。
`'L'`	秒内的毫秒数，根据需要格式化为带前导零的三位数字，即 `000 - 999` 。
`'N'`	秒内的纳秒，格式为九位数字，必要时带前导零，即 `000000000 - 999999999` 。
`'p'`	小写的区域特定上午或下午标记，例如“`am`”或“`pm`”。使用转换前缀 `'T'` 将此输出强制为大写。
`'z'`	RFC 822 样式数字时区与 GMT 的偏移量，例如 `-0800` 。该值将根据夏令时的需要进行调整。对于 `long` 、 `Long` 和 `Date` 使用的时区是 Java 虚拟机的这个实例的默认时区。
`'Z'`	表示时区缩写的字符串。该值将根据夏令时的需要进行调整。对于 `long` 、 `Long` 和 `Date` 使用的时区是 Java 虚拟机的这个实例的默认时区。 Formatter 的locale将取代参数的locale（如果有的话）。
`'s'`	自 1970 年 1 月 1 日开始的纪元以来的秒数 `00:00:00` UTC，即 `Long.MIN_VALUE/1000` 到 `Long.MAX_VALUE/1000` 。
`'Q'`	自 1970 年 1 月 1 日开始的纪元以来的毫秒数 `00:00:00` UTC，即 `Long.MIN_VALUE` 到 `Long.MAX_VALUE` 。

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

date
转换	Description
`'B'`	特定于locale的完整的月份名称，例如 `"January"` 、 `"February"` 。
`'b'`	特定于locale的缩写月份名称，例如 `"Jan"` 、 `"Feb"` 。
`'h'`	与 `'b'` 相同。
`'A'`	一周中的天的区域特定全名，例如 `"Sunday"` 、 `"Monday"`
`'a'`	一周中的天的特定于区域设置的短名称，例如 `"Sun"` 、 `"Mon"`
`'C'`	四位数年份除以 `100` ，格式为两位数，必要时带前导零，即 `00 - 99`
`'Y'`	年份，格式为至少四位数字，必要时带前导零，例如，对于公历，`0092` 等于 `92` CE。
`'y'`	年份的最后两位数字，根据需要使用前导零进行格式化，即 `00 - 99` 。
`'j'`	一年中的第几天，根据需要格式化为带前导零的三位数字，例如 `001 - 366` 用于公历。
`'m'`	月份，根据需要格式化为带有前导零的两位数，即 `01 - 13` 。
`'d'`	一个月中的第几天，根据需要格式化为带有前导零的两位数，即 `01 - 31`
`'e'`	日期，格式为两位数，即 `1 - 31` 。

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

复合材料
转换	Description
`'R'`	24 小时制的时间格式为 `"%tH:%tM"`
`'T'`	24 小时制的时间格式为 `"%tH:%tM:%tS"` 。
`'r'`	12 小时制的时间格式为 `"%tI:%tM:%tS %Tp"` 。上午或下午标记 (`'%Tp'`) 的位置可能取决于locale。
`'D'`	日期格式为 `"%tm/%td/%ty"` 。
`'F'`	ISO 8601 完整日期格式为 `"%tY-%tm-%td"`。
`'c'`	日期和时间格式为 `"%ta %tb %td %tT %tZ %tY"` ，例如 `"Sun Jul 20 16:17:00 EDT 1969"` 。

任何未明确定义为日期/时间转换后缀的字符都是非法的，并为将来的扩展保留。

旗帜

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

genConv
旗帜	一般的	Character	不可缺少的	浮点	约会时间	Description
'-'	y	y	y	y	y	结果将左对齐。
'#'	y¹	-	y³	y	-	结果应使用依赖于转换的替代形式
'+'	-	-	y⁴	y	-	结果将始终包含一个符号
' '	-	-	y⁴	y	-	结果将包含正值的前导空格
'0'	-	-	y	y	-	结果将被零填充
','	-	-	y²	y⁵	-	结果将包括特定于locale的分组分隔符
'('	-	-	y⁴	y⁵	-	结果将负数括在括号中

¹取决于 Formattable 的定义。

²仅用于 'd' 转换。

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

⁴对于'd'、'o'、'x'和'X'转换应用于BigInteger 或'd'应用于byte、Byte 、short、Short 、int和_ n86891_、long 和 Long 。

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

任何未明确定义为标志的字符都是非法的，并为将来的扩展保留。

宽度

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

精确

对于一般参数类型，精度是要写入输出的最大字符数。

对于浮点转换 'a'、'A'、'e'、'E' 和 'f'，精度是小数点后的位数。如果转换为 'g' 或 'G' ，则精度为四舍五入后所得幅度的总位数。

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

参数索引

参数索引是一个十进制整数，指示参数在参数列表中的位置。第一个参数由“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 。同样，参数索引的零值将导致 IllegalFormatException 。

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

值精确必须在零到 Integer.MAX_VALUE 的范围内，包括在内，否则将抛出 IllegalFormatPrecisionException 。

值宽度必须在 Integer.MAX_VALUE 的范围内，包括在内，否则将抛出 IllegalFormatWidthException 请注意，宽度可能显示为负值，但负号是旗帜.例如在格式字符串 "%-20s" 中宽度是20和旗帜是 ”-”。

值指数必须在 Integer.MAX_VALUE 的范围内，包括 Integer.MAX_VALUE ，否则将抛出 IllegalFormatException 。

Formatter 的任何 format 方法以及任何 format 便利方法（例如 String.format 和 PrintStream.printf ）都可能抛出所有指定的异常。

对于类别一般的, Character, 数字, 不可缺少的和约会时间转换，除非另有说明，如果参数参数是 null ，则结果是“null”。

由大写字符表示的转换（即 'B' 、 'H' 、 'S' 、 'C' 、 'X' 、 'E' 、 'G' 、 'A' 和 'T' ）与对应的小写字符相同-case 转换字符除了将结果转换为大写案例根据通行的Locale 规则。如果没有明确指定locale，无论是在构造实例时还是作为其方法调用的参数，都会使用 default locale 。

一般的

以下一般转换可应用于任何参数类型：

dgConv
转换	Unicode	Description
`'b'`	`'\u0062'`	生成由 `Boolean.toString(boolean)` 返回的“`true`”或“`false`”。如果参数是 `null`，那么结果是“`false`”。如果参数是 `boolean` 或 `Boolean` ，则结果是 `String.valueOf()` 返回的字符串。否则，结果为“`true`”。如果给出 `'#'` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'B'`	`'\u0042'`	`'b'` 的大写变体。
`'h'`	`'\u0068'`	生成表示对象的哈希码值的字符串。结果是通过调用 `Integer.toHexString(arg.hashCode())` 获得的。如果给出 `'#'` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'H'`	`'\u0048'`	`'h'` 的大写变体。
`'s'`	`'\u0073'`	产生一个字符串。如果参数实现 `Formattable` ，则调用其 `formatTo` 方法。否则，通过调用参数的 `toString()` 方法获得结果。如果给出了 `'#'` 标志并且参数不是 `Formattable` ，那么将抛出 `FormatFlagsConversionMismatchException` 。
`'S'`	`'\u0053'`	`'s'` 的大写变体。

以下 flags 适用于一般转换：

dFlags
旗帜	Unicode	Description
`'-'`	`'\u002d'`	左对齐输出。将根据需要在转换后的值末尾添加空格 (`'\u0020'`) 以填充字段的最小宽度。如果未提供宽度，则会抛出 `MissingFormatWidthException` 。如果未给出此标志，则输出将右对齐。
`'#'`	`'\u0023'`	要求输出使用替代形式。形式的定义由转换指定。

width 是要写入输出的最少字符数。如果转换值的长度小于宽度，则输出将被 ' ' ('\u0020' ) 填充，直到字符总数等于宽度。默认情况下，填充位于左侧。如果给出 '-' 标志，则填充将在右侧。如果未指定宽度，则没有最小值。

精度是要写入输出的最大字符数。精度在宽度之前应用，因此即使宽度大于精度，输出也会被截断为 precision 个字符。如果未指定精度，则对字符数没有明确限制。

Character

此转换可应用于 char 和 Character 。当 Character.isValidCodePoint(int) 返回 true 时，它也可以应用于类型 byte、Byte 、short 和 Short 、int 和 Integer 。如果它返回 false 那么将抛出一个 IllegalFormatCodePointException 。

字符转换
转换	Unicode	Description
`'c'`	`'\u0063'`	将参数格式化为 Unicode 字符表示中所述的 Unicode 字符。在参数表示增补字符的情况下，这可能不止一个 16 位`char`。如果给出 `'#'` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'C'`	`'\u0043'`	`'c'` 的大写变体。

为一般转换定义的 '-' 标志适用。如果给出 '#' 标志，则将抛出 FormatFlagsConversionMismatchException 。

宽度定义为一般转换。

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

数字

数值转换分为以下几类：

字节、短整型、整数和长整型
BigInteger
浮动和双
BigDecimal

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

号码本地化算法

在为整数部分、小数部分和指数（根据数据类型而定）获得数字后，将应用以下转换：

每个数字字符d字符串中的替换为相对于当前locale的零位计算的特定于locale的数字z;那是- '0' + z.
如果存在小数分隔符，则替换特定于区域设置的小数分隔符。
如果给出了 ',' ('\u002c' ) 旗帜，则通过从最低有效位到最高有效位扫描字符串的整数部分并以区域设置的分组大小定义的间隔插入分隔符来插入特定于区域设置的分组分隔符。
如果给出了 '0' 标志，则在符号字符（如果有）之后和第一个非零数字之前插入特定于区域设置的零位，直到字符串的长度等于请求的字段宽度。
如果该值为负且给出了 '(' 标志，则会在前面添加 '(' ('\u0028') 并附加 ')' ('\u0029')。
如果该值为负数（或浮点负零）且未给出 '(' 标志，则在前面加上 '-' ('\u002d' )。
如果给出了 '+' 标志并且值为正数或零（或浮点正零），则将添加一个 '+' ('\u002b' )。

如果值为 NaN 或正无穷大，将分别输出文字字符串“NaN”或“Infinity”。如果值为负无穷大，则如果给出 '(' 标志，则输出将为“(Infinity)”，否则输出将为“-Infinity”。这些值未本地化。

字节、短整型、整数和长整型

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

IntConv
转换	Unicode	Description
`'d'`	`'\u0064'`	将参数格式化为十进制整数。应用了定位算法。如果给出 `'0'` 标志且值为负，则零填充将出现在符号之后。如果给出 `'#'` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'o'`	`'\u006f'`	将参数格式化为以八为基数的整数。不应用本地化。如果x为负则结果将是通过添加 2 生成的无符号值ⁿ到值，其中 `n` 是 Byte、Short、Integer 或 Long 类中的静态 `SIZE` 字段返回的类型中的位数，视情况而定。如果给出 `'#'` 标志，则输出将始终以基数指示符 `'0'` 开头。如果给出了 `'0'` 标志，则输出将用前导零填充到任何符号指示后的字段宽度。如果给出 `'('` 、 `'+'` 、 ' ' 或 `','` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'x'`	`'\u0078'`	将参数格式化为十六进制整数。不应用本地化。如果x为负则结果将是通过添加 2 生成的无符号值ⁿ到值，其中 `n` 是 Byte、Short、Integer 或 Long 类中的静态 `SIZE` 字段返回的类型中的位数，视情况而定。如果给出 `'#'` 标志，则输出将始终以基数指示符 `"0x"` 开头。如果给出 `'0'` 标志，则输出将在基数指示符或符号（如果存在）之后用前导零填充到字段宽度。如果给出 `'('` 、 `' '` 、 `'+'` 或 `','` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'X'`	`'\u0058'`	`'x'` 的大写变体。表示数字的整个字符串将转换为大写，包括 `'x'`（如果有）和所有十六进制数字 `'a'` - `'f'` (`'\u0061'` - `'\u0066'`)。

If the conversion is 'o' , 'x' , or 'X' and both the '#' and the '0' flags are given, then result will contain the radix indicator ('0' for octal and "0x" or "0X" for hexadecimal), some number of zeros (based on the width) , 和值。

如果未给出 '-' 标志，则空格填充将出现在符号之前。

以下 flags 适用于数字整数转换：

intFlags
转换	Unicode	Description
`'+'`	`'\u002b'`	要求输出包含所有正数的正号。如果未给出此标志，则只有负值将包含符号。如果同时给出 `'+'` 和 `' '` 标志，则将抛出 `IllegalFormatFlagsException` 。
`' '`	`'\u0020'`	要求输出包含一个用于非负值的额外空格 (`'\u0020'`)。如果同时给出 `'+'` 和 `' '` 标志，则将抛出 `IllegalFormatFlagsException` 。
`'0'`	`'\u0030'`	要求输出用前导零点填充到任何符号或基数指示符后的最小字段宽度，除非转换 NaN 或无穷大。如果未提供宽度，则会抛出 `MissingFormatWidthException` 。如果同时给出 `'-'` 和 `'0'` 标志，则将抛出 `IllegalFormatFlagsException` 。
`','`	`'\u002c'`	要求输出包含特定于区域设置的组分隔符，如本地化算法的 “组”部分中所述。
`'('`	`'\u0028'`	要求输出在负值前加上 `'('` (`'\u0028'`) 并附加 `')'` (`'\u0029'`)。

如果没有给出 flags，则默认格式如下：

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

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

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

BigInteger

以下转换可应用于 BigInteger 。

bIntConv
转换	Unicode	Description
`'d'`	`'\u0064'`	要求将输出格式化为十进制整数。应用了定位算法。如果给出 `'#'` 标志，将抛出 `FormatFlagsConversionMismatchException` 。
`'o'`	`'\u006f'`	要求将输出格式化为以八为底的整数。不应用本地化。如果x为负，则结果将是一个以 `'-'` (`'\u002d'`) 开头的有符号值。这种类型允许带符号的输出，因为与原始类型不同，如果不假定明确的数据类型大小，就不可能创建无符号的等价物。如果x为正数或零且给出 `'+'` 标志，则结果将以 `'+'` (`'\u002b'`) 开头。如果给出 `'#'` 标志，则输出将始终以 `'0'` 前缀开头。如果给出了 `'0'` 标志，则输出将用前导零填充到任何符号指示后的字段宽度。如果给出 `','` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'x'`	`'\u0078'`	要求将输出格式化为以 16 为底的整数。不应用本地化。如果x为负，则结果将是一个以 `'-'` (`'\u002d'`) 开头的有符号值。这种类型允许带符号的输出，因为与原始类型不同，如果不假定明确的数据类型大小，就不可能创建无符号的等价物。如果x为正数或零且给出 `'+'` 标志，则结果将以 `'+'` (`'\u002b'`) 开头。如果给出 `'#'` 标志，则输出将始终以基数指示符 `"0x"` 开头。如果给出 `'0'` 标志，则输出将在基数指示符或符号（如果存在）之后用前导零填充到字段宽度。如果给出 `','` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'X'`	`'\u0058'`	`'x'` 的大写变体。表示数字的整个字符串将转换为大写，包括 `'x'`（如果有）和所有十六进制数字 `'a'` - `'f'` (`'\u0061'` - `'\u0066'`)。

如果转换为 'o' 、 'x' 或 'X' 并且同时给出了 '#' 和 '0' 标志，则结果将包含基本指示符（'0' 用于八进制和 "0x" 或 "0X" 用于十六进制），一些零（基于宽度） , 和值。

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

如果未给出 '-' 标志，则空格填充将出现在符号之前。

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

width 的规范与为字节、短整型、整数和长整型定义的相同。

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

浮动和双

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

浮动转换
转换	Unicode	Description
`'e'`	`'\u0065'`	需要使用计算机科学记数法格式化输出。应用了定位算法。量级的格式m取决于它的值。如果m是 NaN 或无穷大，将分别输出文字字符串“NaN”或“Infinity”。这些值未本地化。如果m是正零或负零，则指数将为 `"+00"` 。否则，结果是表示参数的符号和大小（绝对值）的字符串。定位算法中描述了标志的格式。量级的格式m取决于它的值。让n是满足 10 的唯一整数ⁿ <= m < 10ⁿ⁺¹;然后让a是数学上精确的商m和 10ⁿ所以 1 <=a< 10. 然后将幅度表示为的整数部分a, 作为单个十进制数字，后跟小数点分隔符，然后是表示小数部分的十进制数字a，后跟指数符号 `'e'` (`'\u0065'` )，后跟指数符号，再后跟表示n作为十进制整数，由方法 `Long.toString(long, int)` 生成，并用零填充以包含至少两个数字。结果中小数部分的位数m或者a等于精度。如果未指定精度，则默认值为 `6` 。如果精度小于分别由 `Float.toString(float)` 或 `Double.toString(double)` 返回的字符串中小数点后出现的位数，则该值将使用四舍五入算法四舍五入。否则，可能会附加零以达到精度。对于值的规范表示，请根据需要使用 `Float.toString(float)` 或 `Double.toString(double)` 。如果给出 `','` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'E'`	`'\u0045'`	`'e'` 的大写变体。指数符号将为 `'E'` (`'\u0045'` )。
`'g'`	`'\u0067'`	要求输出以如下所述的一般科学记数法进行格式化。应用了定位算法。在精度四舍五入后，结果幅度的格式m取决于它的值。如果m大于或等于 10^-4但少于 10^精确然后它表示在decimal 格式 . 如果m小于 10^-4或大于或等于 10^精确, 那么它表示在计算机科学记数法 . 中的有效数字总数m等于精度。如果未指定精度，则默认值为 `6` 。如果精度为 `0` ，则将其视为 `1` 。如果给出 `'#'` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'G'`	`'\u0047'`	`'g'` 的大写变体。
`'f'`	`'\u0066'`	需要使用 decimal 格式格式化输出。应用了定位算法。结果是一个字符串，表示参数的符号和大小（绝对值）。定位算法中描述了标志的格式。量级的格式m取决于它的值。如果mNaN 或无限，将分别输出文字字符串“NaN”或“Infinity”。这些值未本地化。幅度被格式化为的整数部分m，没有前导零，后跟小数点分隔符，再后跟一个或多个表示小数部分的小数位m. 结果中小数部分的位数m或者a等于精度。如果未指定精度，则默认值为 `6` 。如果精度小于分别由 `Float.toString(float)` 或 `Double.toString(double)` 返回的字符串中小数点后出现的位数，则该值将使用四舍五入算法四舍五入。否则，可能会附加零以达到精度。对于值的规范表示，请根据需要使用 `Float.toString(float)` 或 `Double.toString(double)` 。
`'a'`	`'\u0061'`	要求输出格式化为十六进制指数形式。不应用本地化。结果是一个字符串，表示参数的符号和大小（绝对值）x. 如果x为负数或负零值，则结果将以 `'-'` (`'\u002d'` ) 开头。如果x为正值或正零值且给出 `'+'` 标志，则结果将以 `'+'` (`'\u002b'`) 开头。量级的格式m取决于它的值。如果值为 NaN 或无穷大，将分别输出文字字符串“NaN”或“Infinity”。如果m为零则由字符串 `"0x0.0p0"` 表示。如果m是具有规范化表示的 `double` 值，然后子字符串用于表示有效数字和指数字段。有效数由字符 `"0x1."` 表示，后跟剩余有效数的十六进制表示形式的小数。指数由 `'p'` (`'\u0070'` ) 表示，后跟无偏指数的十进制字符串，就好像通过对指数值调用 `Integer.toString` 产生的一样。如果指定了精度，则将值四舍五入为给定的十六进制位数。如果m是一个具有次正规表示的 `double` 值，除非精度被指定在 1 到 12 的范围内，包括 1 到 12，否则有效数由字符 `'0x0.'` 后跟有效数的其余部分的十六进制表示形式表示为分数，并且`'p-1022'` 表示的指数。如果精度在区间 [1, 12] 内，则对次正规值进行归一化，使其以字符 `'0x1.'` 开头，四舍五入为精度的十六进制位数，并相应地调整指数。请注意，次正规尾数中必须至少有一个非零数字。如果给出 `'('` 或 `','` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'A'`	`'\u0041'`	`'a'` 的大写变体。表示数字的整个字符串将转换为大写，包括`'x'` (`'\u0078'`) 和`'p'` (`'\u0070'` 以及所有十六进制数字`'a'` - `'f'` (`'\u0061'` - `'\u0066'`)。

为 Byte、Short、Integer 和 Long 定义的所有 flags 都适用。

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

如果没有给出 flags，则默认格式如下：

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

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

如果转换为 'e' 、 'E' 或 'f' ，则精度为小数点后的位数。如果未指定精度，则假定为 6 。

如果转换为 'g' 或 'G' ，则精度为四舍五入后所得量值中有效数字的总数。如果未指定精度，则默认值为 6 。如果精度为 0 ，则将其视为 1 。

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

BigDecimal

可以应用以下转换 BigDecimal 。

浮动转换
转换	Unicode	Description
`'e'`	`'\u0065'`	需要使用计算机科学记数法格式化输出。应用了定位算法。量级的格式m取决于它的值。如果m是正零或负零，则指数将为 `"+00"` 。否则，结果是表示参数的符号和大小（绝对值）的字符串。定位算法中描述了标志的格式。量级的格式m取决于它的值。让n是满足 10 的唯一整数ⁿ <= m < 10ⁿ⁺¹;然后让a是数学上精确的商m和 10ⁿ所以 1 <=a< 10. 然后将幅度表示为的整数部分a, 作为单个十进制数字，后跟小数点分隔符，然后是表示小数部分的十进制数字a，后跟指数符号 `'e'` (`'\u0065'` )，后跟指数符号，再后跟表示n作为十进制整数，由方法 `Long.toString(long, int)` 生成，并用零填充以包含至少两个数字。结果中小数部分的位数m或者a等于精度。如果未指定精度，则默认值为 `6` 。如果精度小于小数点右侧的位数，则该值将使用四舍五入算法四舍五入。否则，可能会附加零以达到精度。对于值的规范表示，请使用 `BigDecimal.toString()` 。如果给出 `','` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'E'`	`'\u0045'`	`'e'` 的大写变体。指数符号将为 `'E'` (`'\u0045'` )。
`'g'`	`'\u0067'`	要求输出以如下所述的一般科学记数法进行格式化。应用了定位算法。在精度四舍五入后，结果幅度的格式m取决于它的值。如果m大于或等于 10^-4但少于 10^精确然后它表示在decimal 格式 . 如果m小于 10^-4或大于或等于 10^精确, 那么它表示在计算机科学记数法 . 中的有效数字总数m等于精度。如果未指定精度，则默认值为 `6` 。如果精度为 `0` ，则将其视为 `1` 。如果给出 `'#'` 标志，则将抛出 `FormatFlagsConversionMismatchException` 。
`'G'`	`'\u0047'`	`'g'` 的大写变体。
`'f'`	`'\u0066'`	需要使用 decimal 格式格式化输出。应用了定位算法。结果是一个字符串，表示参数的符号和大小（绝对值）。定位算法中描述了标志的格式。量级的格式m取决于它的值。幅度被格式化为的整数部分m，没有前导零，后跟小数点分隔符，再后跟一个或多个表示小数部分的小数位m. 结果中小数部分的位数m或者a等于精度。如果未指定精度，则默认值为 `6` 。如果精度小于小数点右侧的位数，则该值将使用四舍五入算法四舍五入。否则，可能会附加零以达到精度。对于值的规范表示，请使用 `BigDecimal.toString()` 。

为 Byte、Short、Integer 和 Long 定义的所有 flags 都适用。

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

没有给出标志时的默认行为与 Float 和 Double 相同。

width 和 precision 的规范与为 Float 和 Double 定义的相同。

约会时间

此转换可应用于 long、Long 、Calendar 、Date 和 TemporalAccessor

DTConv
转换	Unicode	Description
`'t'`	`'\u0074'`	日期和时间转换字符的前缀。
`'T'`	`'\u0054'`	`'t'` 的大写变体。

为 't' 和 'T' 转换定义了以下日期和时间转换字符后缀。这些类型与 GNU date 和 POSIX strftime(3c) 定义的类型相似但不完全相同。提供了额外的转换类型来访问特定于 Java 的功能（例如，'L' 表示秒内的毫秒数）。

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

time
转换	Unicode	Description
`'H'`	`'\u0048'`	24 小时制的一天中的小时，根据需要格式化为带有前导零的两位数，即 `00 - 23` 。 `00` 对应午夜。
`'I'`	`'\u0049'`	12 小时制的小时，根据需要格式化为带前导零的两位数，即 `01 - 12` 。 `01` 对应于一点钟（上午或下午）。
`'k'`	`'\u006b'`	24 小时制的一天中的小时，即 `0 - 23` 。 `0` 对应午夜。
`'l'`	`'\u006c'`	12 小时制的小时，即 `1 - 12` 。 `1` 对应于一点钟（上午或下午）。
`'M'`	`'\u004d'`	小时内的分钟，根据需要格式化为带前导零的两位数，即 `00 - 59` 。
`'S'`	`'\u0053'`	分钟内的秒数，根据需要格式化为带前导零的两位数，即 `00 - 60`（“`60`”是支持闰秒所需的特殊值）。
`'L'`	`'\u004c'`	秒内的毫秒数，根据需要格式化为带前导零的三位数字，即 `000 - 999` 。
`'N'`	`'\u004e'`	秒内的纳秒，格式为九位数字，必要时带前导零，即 `000000000 - 999999999` 。该值的精度受底层操作系统或硬件分辨率的限制。
`'p'`	`'\u0070'`	小写的区域特定上午或下午标记，例如“`am`”或“`pm`”。使用转换前缀 `'T'` 将此输出强制为大写。（注意 `'p'` 产生小写输出。这不同于产生大写输出的 GNU `date` 和 POSIX `strftime(3c)`。）
`'z'`	`'\u007a'`	RFC 822 样式数字时区与 GMT 的偏移量，例如 `-0800` 。该值将根据夏令时的需要进行调整。对于 `long` 、 `Long` 和 `Date` 使用的时区是 Java 虚拟机的这个实例的默认时区。
`'Z'`	`'\u005a'`	表示时区缩写的字符串。该值将根据夏令时的需要进行调整。对于 `long` 、 `Long` 和 `Date` 使用的时区是 Java 虚拟机的这个实例的默认时区。 Formatter 的locale将取代参数的locale（如果有的话）。
`'s'`	`'\u0073'`	自 1970 年 1 月 1 日开始的纪元以来的秒数 `00:00:00` UTC，即 `Long.MIN_VALUE/1000` 到 `Long.MAX_VALUE/1000` 。
`'Q'`	`'\u004f'`	自 1970 年 1 月 1 日开始的纪元以来的毫秒数 `00:00:00` UTC，即 `Long.MIN_VALUE` 到 `Long.MAX_VALUE` 。该值的精度受底层操作系统或硬件分辨率的限制。

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

date
转换	Unicode	Description
`'B'`	`'\u0042'`	特定于locale的完整的月份名称，例如 `"January"` 、 `"February"` 。
`'b'`	`'\u0062'`	特定于locale的缩写月份名称，例如 `"Jan"` 、 `"Feb"` 。
`'h'`	`'\u0068'`	与 `'b'` 相同。
`'A'`	`'\u0041'`	一周中的天的区域特定全名，例如 `"Sunday"` 、 `"Monday"`
`'a'`	`'\u0061'`	一周中的天的特定于区域设置的短名称，例如 `"Sun"` 、 `"Mon"`
`'C'`	`'\u0043'`	四位数年份除以 `100` ，格式为两位数，必要时带前导零，即 `00 - 99`
`'Y'`	`'\u0059'`	年份，根据需要格式化为至少四位带前导零的数字，例如，对于公历，`0092` 等于 `92` CE。
`'y'`	`'\u0079'`	年份的最后两位数字，根据需要使用前导零进行格式化，即 `00 - 99` 。
`'j'`	`'\u006a'`	一年中的第几天，根据需要格式化为带前导零的三位数字，例如 `001 - 366` 用于公历。 `001` 对应于一年的第一天。
`'m'`	`'\u006d'`	月份，根据需要格式化为带有前导零的两位数字，即 `01 - 13` ，其中“`01`”是一年中的第一个月，（“`13`”是支持农历所需的特殊值）。
`'d'`	`'\u0064'`	月中的第几天，根据需要格式化为带前导零的两位数，即 `01 - 31` ，其中“`01`”是该月的第一天。
`'e'`	`'\u0065'`	日期，格式为两位数，即 `1 - 31`，其中“`1`”是该月的第一天。

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

复合材料
转换	Unicode	Description
`'R'`	`'\u0052'`	24 小时制的时间格式为 `"%tH:%tM"`
`'T'`	`'\u0054'`	24 小时制的时间格式为 `"%tH:%tM:%tS"` 。
`'r'`	`'\u0072'`	12 小时制的时间格式为 `"%tI:%tM:%tS %Tp"` 。上午或下午标记 (`'%Tp'`) 的位置可能取决于locale。
`'D'`	`'\u0044'`	日期格式为 `"%tm/%td/%ty"` 。
`'F'`	`'\u0046'`	ISO 8601 完整日期格式为 `"%tY-%tm-%td"`。
`'c'`	`'\u0063'`	日期和时间格式为 `"%ta %tb %td %tT %tZ %tY"` ，例如 `"Sun Jul 20 16:17:00 EDT 1969"` 。

为一般转换定义的 '-' 标志适用。如果给出 '#' 标志，则将抛出 FormatFlagsConversionMismatchException 。

宽度是要写入输出的最小字符数。如果转换值的长度小于 width，则输出将用空格 ('\u0020') 填充，直到字符总数等于宽度。默认情况下，填充位于左侧。如果给出 '-' 标志，则填充将在右侧。如果未指定宽度，则没有最小值。

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

百分

转换不对应于任何参数。

DTConv
转换	Description
`'%'`	结果是文字 `'%'` (`'\u0025'` ) 宽度是要写入输出的最小字符数，包括 `'%'` 。如果转换值的长度小于 `width`，则输出将用空格 (`'\u0020'`) 填充，直到字符总数等于宽度。填充在左边。如果未指定宽度，则仅输出 `'%'`。为一般转换定义的 `'-'` 标志适用。如果提供任何其他标志，则会抛出 `IllegalFormatFlagsException` 。精度不适用。如果指定了精度，将抛出 `IllegalFormatPrecisionException` 。

行分隔符

转换不对应于任何参数。

DTConv
转换	Description
`'n'`	`System.lineSeparator()` 返回的特定于平台的行分隔符。

标志、宽度和精度不适用。如果提供了 IllegalFormatFlagsException 、 IllegalFormatWidthException 和 IllegalFormatPrecisionException ，将分别被抛出。

参数索引

格式说明符可以通过三种方式引用参数：

显式索引当格式说明符包含参数索引时使用。参数索引是一个十进制整数，指示参数在参数列表中的位置。第一个参数由“1$”引用，第二个由“2$”引用，等等。一个参数可以被多次引用。
例如：
```
  formatter.format("%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s",
          "a", "b", "c", "d")
  // -> "d c b a d c b a"
 
```
相对索引当格式说明符包含 '<' ('\u003c' ) 标志时使用，这会导致重新使用前一个格式说明符的参数。如果之前没有参数，则抛出 MissingFormatArgumentException 。
```
  formatter.format("%s %s %<s %<s", "a", "b", "c", "d")
  // -> "a b b b"
  // "c" and "d" are ignored because they are not referenced
 
```
普通索引当格式说明符既不包含参数索引也不包含 '<' 标志时使用。每个使用普通索引的格式说明符都被分配到参数列表中的顺序隐式索引，该索引独立于显式或相对索引使用的索引。
```
  formatter.format("%s %s %s %s", "a", "b", "c", "d")
  // -> "a b c d"
 
```

可以有一个使用所有形式索引的格式字符串，例如：

  formatter.format("%2$s %s %<s %s", "a", "b", "c", "d")
  // -> "b a a b"
  // "c" and "d" are ignored because they are not referenced

参数的最大数量受限于 Java 数组的最大维度，如定义的那样Java 虚拟机规范.如果参数索引不对应于可用参数，则抛出 MissingFormatArgumentException 。

如果参数多于格式说明符，则忽略多余的参数。

除非另有说明，否则将 null 参数传递给此类中的任何方法或构造函数将导致抛出 NullPointerException 。

自从：: 1.5

内部类总结

内部类

修饰符和类型

类

描述

static enum

Formatter.BigDecimalLayoutForm

BigDecimal 格式的枚举。
构造方法总结

构造方法

构造方法

描述

Formatter()

构造一个新的格式化程序。

Formatter(File file)

用指定的文件构造一个新的格式化程序。

Formatter(File file, String csn)

使用指定的文件和字符集构造一个新的格式化程序。

Formatter(File file, String csn, Locale l)

使用指定的文件、字符集和locale构造一个新的格式化程序。

Formatter(File file, Charset charset, Locale l)

使用指定的文件、字符集和locale构造一个新的格式化程序。

Formatter(OutputStream os)

构造具有指定输出流的新格式化程序。

Formatter(OutputStream os, String csn)

构造具有指定输出流和字符集的新格式化程序。

Formatter(OutputStream os, String csn, Locale l)

使用指定的输出流、字符集和locale构造一个新的格式化程序。

Formatter(OutputStream os, Charset charset, Locale l)

使用指定的输出流、字符集和locale构造一个新的格式化程序。

Formatter(PrintStream ps)

使用指定的打印流构造一个新的格式化程序。

Formatter(Appendable a)

构造具有指定目标的新格式化程序。

Formatter(Appendable a, Locale l)

构造具有指定目标和locale的新格式化程序。

Formatter(String fileName)

构造具有指定文件名的新格式化程序。

Formatter(String fileName, String csn)

构造具有指定文件名和字符集的新格式化程序。

Formatter(String fileName, String csn, Locale l)

构造具有指定文件名、字符集和locale的新格式化程序。

Formatter(String fileName, Charset charset, Locale l)

构造具有指定文件名、字符集和locale的新格式化程序。

Formatter(Locale l)

构造具有指定locale的新格式化程序。
方法总结

修饰符和类型

方法

描述

void

close()

关闭此格式化程序。

void

flush()

刷新此格式化程序。

Formatter

format(String format, Object... args)

使用指定的格式字符串和参数将格式化字符串写入此对象的目标。

Formatter

format(Locale l, String format, Object... args)

使用指定的locale、格式字符串和参数将格式化字符串写入此对象的目标。

IOException

ioException()

返回此格式化程序的 Appendable 最后抛出的 IOException。

Locale

locale()

返回由此格式化程序的构造设置的locale。

Appendable

out()

返回输出的目的地。

String

toString()

返回在输出目标上调用 toString() 的结果。

在类 java.lang.Object 中声明的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

构造方法详细信息
- Formatter
  
  public Formatter()
  
  构造一个新的格式化程序。
  格式化输出的目标是一个 StringBuilder ，可以通过调用 out() 检索它，并且可以通过调用 toString() 将其当前内容转换为字符串。对于这个 Java 虚拟机实例，使用的locale是默认locale for 格式化。
- Formatter
  
  public Formatter(Appendable a)
  
  构造具有指定目标的新格式化程序。
  对于这个 Java 虚拟机实例，使用的locale是默认locale for 格式化。
  
  参数：
  
  a - 格式化输出的目的地。如果 a 是 null 那么将创建一个 StringBuilder 。
- Formatter
  
  public Formatter(Locale l)
  
  构造具有指定locale的新格式化程序。
  格式化输出的目标是一个 StringBuilder ，可以通过调用 out() 检索它，并且可以通过调用 toString() 将其当前内容转换为字符串。
  
  参数：
  
  l - 在格式化期间应用的 locale。如果 l 是 null 则不应用本地化。
- Formatter
  
  public Formatter(Appendable a, Locale l)
  
  构造具有指定目标和locale的新格式化程序。
  
  参数：
  
  a - 格式化输出的目的地。如果 a 是 null 那么将创建一个 StringBuilder 。
  
  l - 在格式化期间应用的 locale。如果 l 是 null 则不应用本地化。
- Formatter
  
  public Formatter(String fileName) throws FileNotFoundException
  
  构造具有指定文件名的新格式化程序。
  对于这个 Java 虚拟机实例，使用的字符集是默认字符集。
  
  对于这个 Java 虚拟机实例，使用的locale是默认locale for 格式化。
  
  参数：
  
  fileName - 用作此格式化程序目标的文件的名称。如果文件存在，那么它将被截断为零大小；否则，将创建一个新文件。输出将被写入文件并被缓冲。
  
  抛出：
  
  SecurityException - 如果存在安全管理器并且 checkWrite(fileName) 拒绝对文件的写访问
  
  FileNotFoundException - 如果给定的文件名不表示现有的、可写的常规文件并且无法创建同名的新常规文件，或者在打开或创建文件时出现其他错误
- Formatter
  
  public Formatter(String fileName, String csn) throws FileNotFoundException , UnsupportedEncodingException
  
  构造具有指定文件名和字符集的新格式化程序。
  对于这个 Java 虚拟机实例，使用的locale是默认locale for 格式化。
  
  参数：
  
  fileName - 用作此格式化程序目标的文件的名称。如果文件存在，那么它将被截断为零大小；否则，将创建一个新文件。输出将被写入文件并被缓冲。
  
  csn - 受支持的 charset 的名称
  
  抛出：
  
  FileNotFoundException - 如果给定的文件名不表示现有的、可写的常规文件并且无法创建同名的新常规文件，或者在打开或创建文件时出现其他错误
  
  SecurityException - 如果存在安全管理器并且 checkWrite(fileName) 拒绝对文件的写访问
  
  UnsupportedEncodingException - 如果不支持指定的字符集
- Formatter
  
  public Formatter(String fileName, String csn, Locale l) throws FileNotFoundException , UnsupportedEncodingException
  
  构造具有指定文件名、字符集和locale的新格式化程序。
  
  参数：
  
  fileName - 用作此格式化程序目标的文件的名称。如果文件存在，那么它将被截断为零大小；否则，将创建一个新文件。输出将被写入文件并被缓冲。
  
  csn - 受支持的 charset 的名称
  
  l - 在格式化期间应用的 locale。如果 l 是 null 则不应用本地化。
  
  抛出：
  
  FileNotFoundException - 如果给定的文件名不表示现有的、可写的常规文件并且无法创建同名的新常规文件，或者在打开或创建文件时出现其他错误
  
  SecurityException - 如果存在安全管理器并且 checkWrite(fileName) 拒绝对文件的写访问
  
  UnsupportedEncodingException - 如果不支持指定的字符集
- Formatter
  
  public Formatter(String fileName, Charset charset, Locale l) throws IOException
  
  构造具有指定文件名、字符集和locale的新格式化程序。
  
  参数：
  
  fileName - 用作此格式化程序目标的文件的名称。如果文件存在，那么它将被截断为零大小；否则，将创建一个新文件。输出将被写入文件并被缓冲。
  
  charset - 一个 charset
  
  l - 在格式化期间应用的 locale。如果 l 是 null 则不应用本地化。
  
  抛出：
  
  IOException - 如果在打开或创建文件时发生 I/O 错误
  
  SecurityException - 如果存在安全管理器并且 checkWrite(fileName) 拒绝对文件的写访问
  
  NullPointerException - 如果 fileName 或 charset 是 null。
- Formatter
  
  public Formatter(File file) throws FileNotFoundException
  
  用指定的文件构造一个新的格式化程序。
  对于这个 Java 虚拟机实例，使用的字符集是默认字符集。
  
  对于这个 Java 虚拟机实例，使用的locale是默认locale for 格式化。
  
  参数：
  
  file - 用作此格式化程序目标的文件。如果文件存在，那么它将被截断为零大小；否则，将创建一个新文件。输出将被写入文件并被缓冲。
  
  抛出：
  
  SecurityException - 如果存在安全管理器并且 checkWrite(file.getPath()) 拒绝对文件的写访问
  
  FileNotFoundException - 如果给定的文件对象不表示现有的、可写的常规文件并且无法创建同名的新常规文件，或者在打开或创建文件时出现其他错误
- Formatter
  
  public Formatter(File file, String csn) throws FileNotFoundException , UnsupportedEncodingException
  
  使用指定的文件和字符集构造一个新的格式化程序。
  对于这个 Java 虚拟机实例，使用的locale是默认locale for 格式化。
  
  参数：
  
  file - 用作此格式化程序目标的文件。如果文件存在，那么它将被截断为零大小；否则，将创建一个新文件。输出将被写入文件并被缓冲。
  
  csn - 受支持的 charset 的名称
  
  抛出：
  
  FileNotFoundException - 如果给定的文件对象不表示现有的、可写的常规文件并且无法创建同名的新常规文件，或者在打开或创建文件时出现其他错误
  
  SecurityException - 如果存在安全管理器并且 checkWrite(file.getPath()) 拒绝对文件的写访问
  
  UnsupportedEncodingException - 如果不支持指定的字符集
- Formatter
  
  public Formatter(File file, String csn, Locale l) throws FileNotFoundException , UnsupportedEncodingException
  
  使用指定的文件、字符集和locale构造一个新的格式化程序。
  
  参数：
  
  file - 用作此格式化程序目标的文件。如果文件存在，那么它将被截断为零大小；否则，将创建一个新文件。输出将被写入文件并被缓冲。
  
  csn - 受支持的 charset 的名称
  
  l - 在格式化期间应用的 locale。如果 l 是 null 则不应用本地化。
  
  抛出：
  
  FileNotFoundException - 如果给定的文件对象不表示现有的、可写的常规文件并且无法创建同名的新常规文件，或者在打开或创建文件时出现其他错误
  
  SecurityException - 如果存在安全管理器并且 checkWrite(file.getPath()) 拒绝对文件的写访问
  
  UnsupportedEncodingException - 如果不支持指定的字符集
- Formatter
  
  public Formatter(File file, Charset charset, Locale l) throws IOException
  
  使用指定的文件、字符集和locale构造一个新的格式化程序。
  
  参数：
  
  file - 用作此格式化程序目标的文件。如果文件存在，那么它将被截断为零大小；否则，将创建一个新文件。输出将被写入文件并被缓冲。
  
  charset - 一个 charset
  
  l - 在格式化期间应用的 locale。如果 l 是 null 则不应用本地化。
  
  抛出：
  
  IOException - 如果在打开或创建文件时发生 I/O 错误
  
  SecurityException - 如果存在安全管理器并且 checkWrite(file.getPath()) 拒绝对文件的写访问
  
  NullPointerException - 如果 file 或 charset 是 null。
- Formatter
  
  public Formatter(PrintStream ps)
  
  使用指定的打印流构造一个新的格式化程序。
  对于这个 Java 虚拟机实例，使用的locale是默认locale for 格式化。
  
  字符被写入给定的 PrintStream 对象，因此使用该对象的字符集进行编码。
  
  参数：
  
  ps - 用作此格式化程序目标的流。
- Formatter
  
  public Formatter(OutputStream os)
  
  构造具有指定输出流的新格式化程序。
  对于这个 Java 虚拟机实例，使用的字符集是默认字符集。
  
  对于这个 Java 虚拟机实例，使用的locale是默认locale for 格式化。
  
  参数：
  
  os - 用作此格式化程序目标的输出流。输出将被缓冲。
- Formatter
  
  public Formatter(OutputStream os, String csn) throws UnsupportedEncodingException
  
  构造具有指定输出流和字符集的新格式化程序。
  对于这个 Java 虚拟机实例，使用的locale是默认locale for 格式化。
  
  参数：
  
  os - 用作此格式化程序目标的输出流。输出将被缓冲。
  
  csn - 受支持的 charset 的名称
  
  抛出：
  
  UnsupportedEncodingException - 如果不支持指定的字符集
- Formatter
  
  public Formatter(OutputStream os, String csn, Locale l) throws UnsupportedEncodingException
  
  使用指定的输出流、字符集和locale构造一个新的格式化程序。
  
  参数：
  
  os - 用作此格式化程序目标的输出流。输出将被缓冲。
  
  csn - 受支持的 charset 的名称
  
  l - 在格式化期间应用的 locale。如果 l 是 null 则不应用本地化。
  
  抛出：
  
  UnsupportedEncodingException - 如果不支持指定的字符集
- Formatter
  
  public Formatter(OutputStream os, Charset charset, Locale l)
  
  使用指定的输出流、字符集和locale构造一个新的格式化程序。
  
  参数：
  
  os - 用作此格式化程序目标的输出流。输出将被缓冲。
  
  charset - 一个 charset
  
  l - 在格式化期间应用的 locale。如果 l 是 null 则不应用本地化。
  
  抛出：
  
  NullPointerException - 如果 os 或 charset 是 null。
方法详情
- locale
  
  public Locale locale()
  
  返回由此格式化程序的构造设置的locale。
  具有locale参数的此对象的 format 方法不会更改此值。
  
  返回：
  
  null 如果未应用本地化，否则为locale
  
  抛出：
  
  FormatterClosedException - 如果此格式化程序已通过调用其 close() 方法关闭
- out
  
  public Appendable out()
  
  返回输出的目的地。
  
  返回：
  
  输出的目的地
  
  抛出：
  
  FormatterClosedException - 如果此格式化程序已通过调用其 close() 方法关闭
- toString
  
  public String toString()
  返回在输出目标上调用 toString() 的结果。例如，以下代码将文本格式化为 StringBuilder ，然后检索结果字符串：
  
  Formatter f = new Formatter(); f.format("Last reboot at %tc", lastRebootDate); String s = f.toString(); // -> s == "Last reboot at Sat Jan 01 00:00:00 PST 2000"
  
  此方法的调用与调用的行为完全相同
  
  out().toString()
  
  根据 Appendable 的 toString 规范，返回的字符串可能包含也可能不包含写入目标的字符。例如，缓冲区通常在 toString() 中返回它们的内容，但流不能，因为数据被丢弃了。
  重写：
  
  toString 在类 Object 中
  
  返回：
  
  在输出目标上调用 toString() 的结果
  
  抛出：
  
  FormatterClosedException - 如果此格式化程序已通过调用其 close() 方法关闭
- flush
  
  public void flush()
  
  刷新此格式化程序。如果目的地实现了Flushable 接口，它的flush方法将被调用。
  刷新格式化程序会将目标中的任何缓冲输出写入基础流。
  
  指定者：
  
  flush 在接口 Flushable 中
  
  抛出：
  
  FormatterClosedException - 如果此格式化程序已通过调用其 close() 方法关闭
- close
  
  public void close()
  
  关闭此格式化程序。如果目的地实现了 Closeable 接口，则将调用其 close 方法。
  关闭格式化程序允许它释放它可能持有的资源（例如打开的文件）。如果格式化程序已经关闭，则调用此方法无效。
  
  在格式化程序关闭后尝试调用除 ioException() 之外的任何方法将导致 FormatterClosedException 。
  
  指定者：
  
  close 在接口 AutoCloseable 中
  
  指定者：
  
  close 在接口 Closeable 中
- ioException
  
  public IOException ioException()
  
  返回此格式化程序的 Appendable 最后抛出的 IOException。
  如果目的地的 append() 方法从不抛出 IOException ，那么此方法将始终返回 null 。
  
  返回：
  
  Appendable 或 null 抛出的最后一个异常（如果不存在此类异常）。
- format
  
  public Formatter format(String format, Object ... args)
  
  使用指定的格式字符串和参数将格式化字符串写入此对象的目标。使用的locale是在构造此格式化程序期间定义的locale。
  
  参数：
  
  format - 格式字符串，如格式化字符串语法中所述。
  
  args - 格式字符串中格式说明符引用的参数。如果参数多于格式说明符，则忽略多余的参数。参数的最大数量受限于 Java 数组的最大维度，如定义的那样Java 虚拟机规范.
  
  返回：
  
  这个格式化程序
  
  抛出：
  
  IllegalFormatException - 如果格式字符串包含非法语法、与给定参数不兼容的格式说明符、给定格式字符串的参数不足或其他非法条件。有关所有可能的格式错误的规范，请参阅格式化程序类规范的细节部分。
  
  FormatterClosedException - 如果此格式化程序已通过调用其 close() 方法关闭
- format
  
  public Formatter format(Locale l, String format, Object ... args)
  
  使用指定的locale、格式字符串和参数将格式化字符串写入此对象的目标。
  
  参数：
  
  l - 在格式化期间应用的 locale。如果 l 是 null 则不应用本地化。这不会更改在构造期间设置的此对象的区域设置。
  
  format - 格式化字符串语法中描述的格式字符串
  
  args - 格式字符串中格式说明符引用的参数。如果参数多于格式说明符，则忽略多余的参数。参数的最大数量受限于 Java 数组的最大维度，如定义的那样Java 虚拟机规范.
  
  返回：
  
  这个格式化程序
  
  抛出：
  
  IllegalFormatException - 如果格式字符串包含非法语法、与给定参数不兼容的格式说明符、给定格式字符串的参数不足或其他非法条件。有关所有可能的格式错误的规范，请参阅格式化程序类规范的细节部分。
  
  FormatterClosedException - 如果此格式化程序已通过调用其 close() 方法关闭

类 Formatter

转换

旗帜

宽度

精确

参数索引

内部类总结

构造方法总结

方法总结

在类 java.lang.Object 中声明的方法

构造方法详细信息

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

方法详情

locale

out

toString

flush

close

ioException

format

format