java.lang.Object

java.util.Formatter

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

public final class Formatter extends Object implements Closeable, Flushable

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

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

Java语言的格式化打印受到C的printf的启发。尽管格式字符串类似于C，但已经进行了一些定制以适应Java语言并利用其一些特性。此外，Java格式化比C更严格；例如，如果转换与标志不兼容，则会抛出异常。在C中，不适用的标志会被静默忽略。因此，格式字符串旨在让C程序员识别，但不一定完全兼容C中的格式字符串。

预期用法示例：

   StringBuilder sb = new StringBuilder();
   // 将所有输出发送到Appendable对象sb
   Formatter formatter = new Formatter(sb, Locale.US);

   // 可以使用显式参数索引重新排序输出。
   formatter.format("%4$2s %3$2s %2$2s %1$2s", "a", "b", "c", "d")
   // -> " d  c  b  a"

   // 可选的区域设置作为第一个参数可用于获取数字的区域设置格式。可以给出精度和宽度以四舍五入和对齐值。
   formatter.format(Locale.FRANCE, "e = %+10.4f", Math.E);
   // -> "e =    +2,7183"

   // 可以使用'('数字标志来使用括号而不是减号格式化负数。自动插入组分隔符。
   formatter.format("自上次报表以来获得或损失的金额：$ %(,.2f",
                    balanceDelta);
   // -> "自上次报表以来获得或损失的金额：$ (6,217.58)"

存在用于常见格式请求的便利方法，如以下调用所示：

   // 将格式化的字符串写入System.out。
   System.out.format("本地时间：%tT", Calendar.getInstance());
   // -> "本地时间：13:34:18"

   // 将格式化的输出写入System.err。
   System.err.printf("无法打开文件'%1$s'：%2$s",
                     fileName, exception.getMessage());
   // -> "无法打开文件'food'：没有这样的文件或目录"

与C的sprintf(3)类似，可以使用静态方法String.format格式化字符串：

   // 格式化包含日期的字符串。
   import java.util.Calendar;
   import java.util.GregorianCalendar;
   import static java.util.Calendar.*;

   Calendar c = new GregorianCalendar(1995, MAY, 23);
   String s = String.format("杜克的生日：%1$tb %1$te, %1$tY", c);
   // -> s == "杜克的生日：May 23, 1995"

组织

此规范分为两个部分。第一部分，概要，涵盖了基本的格式化概念。此部分适用于希望快速入门并熟悉其他编程语言中格式化打印的用户。第二部分，详细信息，涵盖了具体的实现细节。适用于希望更精确规范格式化行为的用户。

概要

此部分旨在提供格式化概念的简要概述。有关精确行为细节，请参阅详细信息部分。

格式字符串语法

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

   Calendar c = ...;
   String s = String.format("杜克的生日：%1$tm %1$te,%1$tY", c);

此格式字符串是format方法的第一个参数。它包含三个格式说明符"%1$tm", "%1$te"和"%1$tY"，指示如何处理参数以及将它们插入文本中的位置。格式字符串的其余部分是固定文本，包括"Dukes Birthday: "和任何其他空格或标点符号。参数列表包括在格式字符串之后传递给方法的所有参数。在上面的示例中，参数列表大小为一，包含Calendar对象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是一个字符，指示要插入输出中的内容。

转换

转换分为以下几类：

一般 - 可应用于任何参数类型
字符 - 可应用于表示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'）
行分隔符 - 生成特定于平台的行分隔符

对于一般、字符、数字、整数和日期/时间转换，除非另有说明，如果参数arg为null，则结果为"null"。

以下表总结了支持的转换。由大写字符（即'B'、'H'、'S'、'C'、'X'、'E'、'G'、'A'和'T'）表示的转换与相应的小写转换字符相同，但根据当前Locale的规则转换为大写。如果没有明确指定区域设置，无论是在实例构造时还是作为其方法调用的参数，都将使用默认区域设置。

genConv
转换	参数类别	描述
`'b'`, `'B'`	通用	如果参数 arg 是 `null`，则结果为 "`false`"。如果 arg 是 `boolean` 或 `Boolean`，则结果为 `String.valueOf(arg)` 返回的字符串。否则，结果为 "true"。
`'h'`, `'H'`	通用	结果通过调用 `Integer.toHexString(arg.hashCode())` 获得。
`'s'`, `'S'`	通用	如果 arg 实现了 `Formattable`，则调用 `arg.formatTo`。否则，结果通过调用 `arg.toString()` 获得。
`'c'`, `'C'`	字符	结果是一个 Unicode 字符
`'d'`	整数	结果格式化为十进制整数
`'o'`	整数	结果格式化为八进制整数
`'x'`, `'X'`	整数	结果格式化为十六进制整数
`'e'`, `'E'`	浮点数	结果格式化为计算机科学记数法中的十进制数
`'f'`	浮点数	结果格式化为十进制数
`'g'`, `'G'`	浮点数	结果使用计算机科学记数法或十进制格式进行格式化，取决于精度和四舍五入后的值。
`'a'`, `'A'`	浮点数	结果格式化为带有效数字和指数的十六进制浮点数。尽管后者属于浮点数参数类别，但不支持此转换类型的`BigDecimal`类型。
`'t'`, `'T'`	日期/时间	日期和时间转换字符的前缀。参见日期/时间转换。
`'%'`	百分比	结果是一个字面值 `'%'` (`'\u0025'`)
`'n'`	行分隔符	结果是特定于平台的行分隔符

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

日期/时间转换

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

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

time
转换	描述
`'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 风格的数字时区偏移量，例如 `-0800`。此值将根据需要调整夏令时。对于 `long`、`Long` 和 `Date`，使用的时区是此 Java 虚拟机实例的默认时区。
`'Z'`	表示时区缩写的字符串。此值将根据需要调整夏令时。对于 `long`、`Long` 和 `Date`，使用的时区是此 Java 虚拟机实例的默认时区。格式化程序的区域设置将取代参数的区域设置（如果有）。
`'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
转换	描述
`'B'`	区域性的完整月份名称，例如 `"January"`、`"February"`。
`'b'`	区域性的缩写月份名称，例如 `"Jan"`、`"Feb"`。
`'h'`	同 `'b'`。
`'A'`	区域性的星期几的完整名称，例如 `"Sunday"`、`"Monday"`
`'a'`	区域性的星期几的缩写名称，例如 `"Sun"`、`"Mon"`
`'C'`	四位数年份除以 `100`，格式化为两位数，必要时带有前导零，即 `00 - 99`
`'Y'`	年份，格式化为至少四位数，必要时带有前导零，例如 `0092` 等于公元 92 年（格里高利历）。
`'y'`	年份的最后两位数，格式化为必要时带有前导零，即 `00 - 99`。
`'j'`	一年中的天数，格式化为三位数，必要时带有前导零，例如公元纪年法中的 `001 - 366`。
`'m'`	月份，格式化为两位数，必要时带有前导零，即 `01 - 13`。
`'d'`	月份中的日期，格式化为两位数，必要时带有前导零，即 `01 - 31`
`'e'`	月份中的日期，格式化为两位数，即 `1 - 31`。

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

组合
转换	描述
`'R'`	24小时制时间格式为`"%tH:%tM"`
`'T'`	24小时制时间格式为`"%tH:%tM:%tS"`。
`'r'`	12小时制时间格式为`"%tI:%tM:%tS %Tp"`。上午或下午标记（`'%Tp'`）的位置可能取决于区域设置。
`'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
标志	通用	字符	整数	浮点数	日期/时间	描述
'-'	y	y	y	y	y	结果将左对齐。
'#'	y¹	-	y³	y	-	结果应使用与转换相关的备用形式
'+'	-	-	y⁴	y	-	结果将始终包含符号
' '	-	-	y⁴	y	-	结果将包含正值的前导空格
'0'	-	-	y	y	-	结果将用零填充
','	-	-	y²	y⁵	-	结果将包含特定于区域设置的分组分隔符
'('	-	-	y⁴	y⁵	-	结果将用括号括起负数

¹ 取决于Formattable的定义。

² 仅适用于'd'转换。

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

⁴ 适用于'd'、'o'、'x'和'X'转换，应用于BigInteger或应用于byte、Byte、short、Short、int和Integer、long和Long的'd'。

⁵ 仅适用于'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（包括）范围内，否则将抛出IllegalFormatException。

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

对于类别通用、字符、数值、整数和日期/时间转换，除非另有说明，如果参数arg为null，则结果为"null"。

大写字符表示的转换（即'B'、'H'、'S'、'C'、'X'、'E'、'G'、'A'和'T'）与相应小写转换字符的转换相同，只是根据当前Locale的规则将结果转换为大写。如果没有明确指定区域设置，无论是在实例构造时还是作为其方法调用的参数，都将使用默认区域设置。

通用

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

dgConv
转换	Unicode	描述
`'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'`的大写变体。

以下标志适用于通用转换：

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

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

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

字符

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

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

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

宽度的定义与通用转换相同。

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

数字

数字转换分为以下类别：

Byte、Short、Integer和Long
BigInteger
Float和Double
BigDecimal

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

数字本地化算法

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

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

如果值为NaN或正无穷大，则分别输出文本字符串"NaN"或"Infinity"。如果值为负无穷大，则输出将是"(Infinity)"（如果给定了'('标志）否则输出将是"-Infinity"。这些值不是本地化的。

Byte、Short、Integer和Long

可以应用以下转换到 byte, Byte, short, Short, int 和 Integer, long, 以及 Long。

IntConv
转换	Unicode	描述
`'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'`）。

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

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

以下标志适用于数字整数转换：

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

如果未给出标志，则默认格式如下：

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

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

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

BigInteger

可以应用以下转换到 BigInteger。

bIntConv
转换	Unicode	描述
`'d'`	`'\u0064'`	要求输出格式为十进制整数。应用本地化算法。如果给定了`'#'`标志，将抛出`FormatFlagsConversionMismatchException`异常。
`'o'`	`'\u006f'`	要求输出格式为八进制整数。不应用本地化。如果x为负数，则结果将是以`'-'`（`'\u002d'`）开头的有符号值。对于此类型，允许有符号输出，因为与原始类型不同，无法创建无符号等效值而不假定显式数据类型大小。如果x为正数或零，并且给定了`'+'`标志，则结果将以`'+'`（`'\u002b'`）开头。如果给定了`'#'`标志，则输出将始终以`'0'`前缀开头。如果给定了`'0'`标志，则输出将在任何符号指示后用前导零填充到字段宽度。如果给定了`','`标志，则将抛出`FormatFlagsConversionMismatchException`异常。
`'x'`	`'\u0078'`	要求输出格式为十六进制整数。不应用本地化。如果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的标志也适用于此。当未给定任何标志时，默认行为与Byte、Short、Integer和Long相同。

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

精度不适用。如果指定了精度，则将抛出一个IllegalFormatPrecisionException异常。

浮点数和双精度浮点数

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

floatConv
转换	Unicode	描述
`'e'`	`'\u0065'`	要求输出使用计算机科学记数法进行格式化。应用本地化算法。首先将`float`或`Float`参数转换为`double`或`Double`，不会丢失精度。幅度m的格式取决于其值。如果m为NaN或无穷大，则分别输出文本字符串"NaN"或"Infinity"。这些值不会本地化。如果m为正零或负零，则指数将为`"+00"`。否则，结果是一个表示参数的符号和幅度（绝对值）的字符串。符号的格式描述在本地化算法中。幅度m的格式取决于其值。设n是唯一的整数，使得10ⁿ <= m < 10ⁿ⁺¹；然后让a成为m和10ⁿ的数学精确商，使得1 <= a < 10。幅度然后表示为a的整数部分，作为一个十进制数字，后跟小数分隔符，后跟表示小数部分的十进制数字，后跟指数符号`'e'`（`'\u0065'`），后跟指数的符号，后跟由方法`Long.toString(long, int)`生成的n的十进制整数表示，并用至少两位零填充。对于m或a的小数部分的结果中的数字个数等于精度。如果未指定精度，则默认值为`6`。如果精度小于由`Double.toString(double)`返回的字符串中小数点后出现的数字个数，则将使用四舍五入算法进行舍入。否则，可能会附加零以达到精度。为了值的规范表示，请使用适当的`Float.toString(float)`或`Double.toString(double)`。如果给出了`','`标志，则将抛出一个`FormatFlagsConversionMismatchException`。
`'E'`	`'\u0045'`	`'e'`的大写变体。指数符号将为`'E'`（`'\u0045'`）。
`'g'`	`'\u0067'`	要求输出以一般科学记数法格式化，如下所述。应用本地化算法。在精度四舍五入后，结果幅度m的格式取决于其值。如果m大于或等于10^-4但小于10^精度，则以十进制格式表示。如果m小于10^-4或大于或等于10^精度，则以计算机科学记数法表示。幅度m中的有效数字总数等于精度。如果未指定精度，则默认值为`6`。如果精度为`0`，则视为`1`。如果给出了`'#'`标志，则将抛出一个`FormatFlagsConversionMismatchException`。
`'G'`	`'\u0047'`	`'g'`的大写变体。
`'f'`	`'\u0066'`	要求输出使用十进制格式进行格式化。应用本地化算法。首先将`float`或`Float`参数转换为`double`或`Double`，不会丢失精度。结果是一个表示参数的符号和幅度（绝对值）的字符串。符号的格式描述在本地化算法中。幅度m的格式取决于其值。如果m为NaN或无穷大，则分别输出文本字符串"NaN"或"Infinity"。这些值不会本地化。幅度被格式化为m的整数部分，没有前导零，后跟小数分隔符，后跟一个或多个表示m的小数部分的十进制数字。对于m或a的小数部分的结果中的数字个数等于精度。如果未指定精度，则默认值为`6`。如果精度小于由`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的标志。

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

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

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

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

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

如果转换为'g'或'G'，则精度是在四舍五入后结果的有效数字总数。如果未指定精度，则默认值为6。如果精度为0，则视为1。

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

BigDecimal

以下转换可应用于BigDecimal。

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

所有定义的Byte、Short、Integer和Long的标志都适用。

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

当未给出标志时，默认行为与Float和Double相同。

对于宽度和精度的指定与Float和Double定义的相同。

日期/时间

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

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

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

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

时间
转换	Unicode	描述
`'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风格的数字时区偏移量，例如`-0800`。此值将根据需要调整以支持夏令时。对于`long`、`Long`和`Date`，使用的时区是Java虚拟机此实例的默认时区。
`'Z'`	`'\u005a'`	表示时区缩写的字符串。此值将根据需要调整以支持夏令时。对于`long`、`Long`和`Date`，使用的时区是Java虚拟机此实例的默认时区。格式化程序的区域设置将覆盖参数的区域设置（如果有）。
`'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`。此值的精度受底层操作系统或硬件的分辨率限制。

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

日期
转换	Unicode	描述
`'B'`	`'\u0042'`	区域特定的完整月份名称，例如`"January"`、`"February"`。
`'b'`	`'\u0062'`	区域特定的缩写月份名称，例如`"Jan"`、`"Feb"`。
`'h'`	`'\u0068'`	同`'b'`。
`'A'`	`'\u0041'`	区域特定的星期几的完整名称，例如`"Sunday"`、`"Monday"`
`'a'`	`'\u0061'`	区域特定的星期几的缩写名称，例如`"Sun"`、`"Mon"`
`'C'`	`'\u0043'`	年份除以`100`得到的四位数，格式化为两位数字，必要时带有前导零，即`00 - 99`
`'Y'`	`'\u0059'`	年份，至少格式化为四位数，必要时带有前导零，例如`0092`表示公元92年（公历）。
`'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	描述
`'R'`	`'\u0052'`	24小时制时间格式为`"%tH:%tM"`
`'T'`	`'\u0054'`	24小时制时间格式为`"%tH:%tM:%tS"`。
`'r'`	`'\u0072'`	12小时制时间格式为`"%tI:%tM:%tS %Tp"`。上午或下午标记（`'%Tp'`）的位置可能取决于区域设置。
`'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。

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

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

百分号

此转换不对应任何参数。

DTConv
转换	描述
`'%'`	结果是一个文字`'%'`（`'\u0025'`）宽度是要写入输出的最小字符数，包括`'%'`。如果转换值的长度小于`宽度`，则输出将填充空格（`'\u0020'`），直到字符总数等于宽度。填充在左侧。如果未指定宽度，则只输出`'%'`。适用于通用转换的`'-'`标志。如果提供了其他标志，则将抛出一个`IllegalFormatFlagsException`。精度不适用。如果指定了精度，则将抛出一个`IllegalFormatPrecisionException`。

换行符

此转换不对应任何参数。

DTConv
转换	描述
`'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"和"d"被忽略，因为它们没有被引用
 
```
普通索引用于格式说明符既不包含参数索引也不包含'<'标志的情况。每个使用普通索引的格式说明符都被分配一个独立于显式或相对索引使用的顺序隐式索引。
```
   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"和"d"被忽略，因为它们没有被引用

参数的最大数量受Java数组的最大维度限制，由Java虚拟机规范定义。如果参数索引与可用参数不对应，则会抛出一个MissingFormatArgumentException。

如果参数比格式说明符多，则额外的参数将被忽略。

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

自 JDK 版本:

1.5

外部规范

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static enum

Formatter.BigDecimalLayoutForm

BigDecimal 格式化的枚举。
Constructor Summary

Constructors

Constructor

Description

Formatter()

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

Formatter(File file)

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

Formatter(File file, String csn)

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

Formatter(File file, String csn, Locale l)

构造一个带有指定文件、字符集和区域设置的新格式化程序。

Formatter(File file, Charset charset, Locale l)

构造一个带有指定文件、字符集和区域设置的新格式化程序。

Formatter(OutputStream os)

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

Formatter(OutputStream os, String csn)

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

Formatter(OutputStream os, String csn, Locale l)

构造一个带有指定输出流、字符集和区域设置的新格式化程序。

Formatter(OutputStream os, Charset charset, Locale l)

构造一个带有指定输出流、字符集和区域设置的新格式化程序。

Formatter(PrintStream ps)

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

Formatter(Appendable a)

构造一个带有指定目的地的新格式化程序。

Formatter(Appendable a, Locale l)

构造一个带有指定目的地和区域设置的新格式化程序。

Formatter(String fileName)

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

Formatter(String fileName, String csn)

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

Formatter(String fileName, String csn, Locale l)

构造一个带有指定文件名、字符集和区域设置的新格式化程序。

Formatter(String fileName, Charset charset, Locale l)

构造一个带有指定文件名、字符集和区域设置的新格式化程序。

Formatter(Locale l)

构造一个带有指定区域设置的新格式化程序。
Method Summary

Modifier and Type

Method

Description

void

close()

关闭此格式化程序。

void

flush()

刷新此格式化程序。

Formatter

format(String format, Object... args)

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

Formatter

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

使用指定的区域设置、格式字符串和参数向此对象的目的地写入格式化的字符串。

IOException

ioException()

返回此格式化程序的 Appendable 上次抛出的 IOException。

Locale

locale()

返回此格式化程序构造时设置的区域设置。

Appendable

out()

返回输出的目的地。

String

toString()

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

Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details
- Formatter
  
  public Formatter()
  
  构造一个新的格式化程序。
  格式化输出的目的地是一个 StringBuilder，可以通过调用 out() 检索，并且可以通过调用 toString() 将其当前内容转换为字符串。使用的区域设置是此 Java 虚拟机实例的默认区域设置用于格式化。
- Formatter
  
  public Formatter(Appendable a)
  
  构造一个带有指定目的地的新格式化程序。
  使用的区域设置是此 Java 虚拟机实例的默认区域设置用于格式化。
  
  参数:
  
  a - 格式化输出的目的地。如果 a 为 null，则将创建一个 StringBuilder。
- Formatter
  
  public Formatter(Locale l)
  
  构造一个带有指定区域设置的新格式化程序。
  格式化输出的目的地是一个 StringBuilder，可以通过调用 out() 检索，并且可以通过调用 toString() 将其当前内容转换为字符串。
  
  参数:
  
  l - 在格式化期间应用的区域设置。如果 l 为 null，则不应用本地化。
- Formatter
  
  public Formatter(Appendable a, Locale l)
  
  构造一个带有指定目的地和区域设置的新格式化程序。
  
  参数:
  
  a - 格式化输出的目的地。如果 a 为 null，则将创建一个 StringBuilder。
  
  l - 在格式化期间应用的区域设置。如果 l 为 null，则不应用本地化。
- Formatter
  
  public Formatter(String fileName) throws FileNotFoundException
  
  构造一个带有指定文件名的新格式化程序。
  使用的字符集是此 Java 虚拟机实例的默认字符集。
  
  使用的区域设置是此 Java 虚拟机实例的默认区域设置用于格式化。
  
  参数:
  
  fileName - 用作此格式化程序目的地的文件的名称。如果文件存在，则将其截断为零大小；否则，将创建一个新文件。输出将写入文件并进行缓冲。
  
  抛出:
  
  SecurityException - 如果存在安全管理器并且 checkWrite(fileName) 拒绝写入文件的访问权限
  
  FileNotFoundException - 如果给定的文件名不表示现有的可写入常规文件，且无法创建具有该名称的新常规文件，或者在打开或创建文件时发生其他错误
- Formatter
  
  public Formatter(String fileName, String csn) throws FileNotFoundException, UnsupportedEncodingException
  
  构造一个带有指定文件名和字符集的新格式化程序。
  使用的区域设置是此 Java 虚拟机实例的默认区域设置用于格式化。
  
  参数:
  
  fileName - 用作此格式化程序目的地的文件的名称。如果文件存在，则将其截断为零大小；否则，将创建一个新文件。输出将写入文件并进行缓冲。
  
  csn - 支持的字符集的名称
  
  抛出:
  
  FileNotFoundException - 如果给定的文件名不表示现有的可写入常规文件，且无法创建具有该名称的新常规文件，或者在打开或创建文件时发生其他错误
  
  SecurityException - 如果存在安全管理器并且 checkWrite(fileName) 拒绝写入文件的访问权限
  
  UnsupportedEncodingException - 如果不支持命名的字符集
- Formatter
  
  public Formatter(String fileName, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException
  
  构造一个带有指定文件名、字符集和区域设置的新格式化程序。
  
  参数:
  
  fileName - 用作此格式化程序目的地的文件的名称。如果文件存在，则将其截断为零大小；否则，将创建一个新文件。输出将写入文件并进行缓冲。
  
  csn - 支持的字符集的名称
  
  l - 在格式化期间应用的区域设置。如果 l 为 null，则不应用本地化。
  
  抛出:
  
  FileNotFoundException - 如果给定的文件名不表示现有的可写入常规文件，且无法创建具有该名称的新常规文件，或者在打开或创建文件时发生其他错误
  
  SecurityException - 如果存在安全管理器并且 checkWrite(fileName) 拒绝写入文件的访问权限
  
  UnsupportedEncodingException - 如果不支持命名的字符集
- Formatter
  
  public Formatter(String fileName, Charset charset, Locale l) throws IOException
  
  构造一个带有指定文件名、字符集和区域设置的新格式化程序。
  
  参数:
  
  fileName - 用作此格式化程序目的地的文件的名称。如果文件存在，则将其截断为零大小；否则，将创建一个新文件。输出将写入文件并进行缓冲。
  
  charset - 字符集
  
  l - 在格式化期间应用的区域设置。如果 l 为 null，则不应用本地化。
  
  抛出:
  
  IOException - 如果在打开或创建文件时发生 I/O 错误
  
  SecurityException - 如果存在安全管理器并且 checkWrite(fileName) 拒绝写入文件的访问权限
  
  NullPointerException - 如果 fileName 或 charset 为 null
- Formatter
  
  public Formatter(File file) throws FileNotFoundException
  
  构造一个使用指定文件的新格式化程序。
  使用的字符集是Java虚拟机此实例的默认字符集。
  
  使用的区域设置是Java虚拟机此实例的默认区域设置用于格式化。
  
  参数：
  
  file - 用作此格式化程序目的地的文件。如果文件存在，则将被截断为零大小；否则将创建一个新文件。输出将写入文件并进行缓冲。
  
  抛出：
  
  SecurityException - 如果存在安全管理器并且checkWrite(file.getPath())拒绝对文件的写访问
  
  FileNotFoundException - 如果给定的文件对象不表示现有的可写常规文件且无法创建具有该名称的新常规文件，或者在打开或创建文件时发生其他错误
- Formatter
  
  public Formatter(File file, String csn) throws FileNotFoundException, UnsupportedEncodingException
  
  构造一个使用指定文件和字符集的新格式化程序。
  使用的区域设置是Java虚拟机此实例的默认区域设置用于格式化。
  
  参数：
  
  file - 用作此格式化程序目的地的文件。如果文件存在，则将被截断为零大小；否则将创建一个新文件。输出将写入文件并进行缓冲。
  
  csn - 支持的字符集的名称
  
  抛出：
  
  FileNotFoundException - 如果给定的文件对象不表示现有的可写常规文件且无法创建具有该名称的新常规文件，或者在打开或创建文件时发生其他错误
  
  SecurityException - 如果存在安全管理器并且checkWrite(file.getPath())拒绝对文件的写访问
  
  UnsupportedEncodingException - 如果不支持指定的字符集
- Formatter
  
  public Formatter(File file, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException
  
  构造一个使用指定文件、字符集和区域设置的新格式化程序。
  
  参数：
  
  file - 用作此格式化程序目的地的文件。如果文件存在，则将被截断为零大小；否则将创建一个新文件。输出将写入文件并进行缓冲。
  
  csn - 支持的字符集的名称
  
  l - 在格式化期间应用的区域设置。如果l为null，则不应用本地化。
  
  抛出：
  
  FileNotFoundException - 如果给定的文件对象不表示现有的可写常规文件且无法创建具有该名称的新常规文件，或者在打开或创建文件时发生其他错误
  
  SecurityException - 如果存在安全管理器并且checkWrite(file.getPath())拒绝对文件的写访问
  
  UnsupportedEncodingException - 如果不支持指定的字符集
- Formatter
  
  public Formatter(File file, Charset charset, Locale l) throws IOException
  
  构造一个使用指定文件、字符集和区域设置的新格式化程序。
  
  参数：
  
  file - 用作此格式化程序目的地的文件。如果文件存在，则将被截断为零大小；否则将创建一个新文件。输出将写入文件并进行缓冲。
  
  charset - 一个字符集
  
  l - 在格式化期间应用的区域设置。如果l为null，则不应用本地化。
  
  抛出：
  
  IOException - 如果在打开或创建文件时发生I/O错误
  
  SecurityException - 如果存在安全管理器并且checkWrite(file.getPath())拒绝对文件的写访问
  
  NullPointerException - 如果file或charset为null
- Formatter
  
  public Formatter(PrintStream ps)
  
  构造一个使用指定打印流的新格式化程序。
  使用的区域设置是Java虚拟机此实例的默认区域设置用于格式化。
  
  字符被写入给定的PrintStream对象，因此使用该对象的字符集进行编码。
  
  参数：
  
  ps - 用作此格式化程序目的地的流。
- Formatter
  
  public Formatter(OutputStream os)
  
  构造一个使用指定输出流的新格式化程序。
  使用的字符集是Java虚拟机此实例的默认字符集。
  
  使用的区域设置是Java虚拟机此实例的默认区域设置用于格式化。
  
  参数：
  
  os - 用作此格式化程序目的地的输出流。输出将被缓冲。
- Formatter
  
  public Formatter(OutputStream os, String csn) throws UnsupportedEncodingException
  
  构造一个使用指定输出流和字符集的新格式化程序。
  使用的区域设置是Java虚拟机此实例的默认区域设置用于格式化。
  
  参数：
  
  os - 用作此格式化程序目的地的输出流。输出将被缓冲。
  
  csn - 支持的字符集的名称
  
  抛出：
  
  UnsupportedEncodingException - 如果不支持指定的字符集
- Formatter
  
  public Formatter(OutputStream os, String csn, Locale l) throws UnsupportedEncodingException
  
  构造一个使用指定输出流、字符集和区域设置的新格式化程序。
  
  参数：
  
  os - 用作此格式化程序目的地的输出流。输出将被缓冲。
  
  csn - 支持的字符集的名称
  
  l - 在格式化期间应用的区域设置。如果l为null，则不应用本地化。
  
  抛出：
  
  UnsupportedEncodingException - 如果不支持指定的字符集
- Formatter
  
  public Formatter(OutputStream os, Charset charset, Locale l)
  
  构造一个使用指定输出流、字符集和区域设置的新格式化程序。
  
  参数：
  
  os - 用作此格式化程序目的地的输出流。输出将被缓冲。
  
  charset - 一个字符集
  
  l - 在格式化期间应用的区域设置。如果l为null，则不应用本地化。
  
  抛出：
  
  NullPointerException - 如果os或charset为null
Method Details
- locale
  
  public Locale locale()
  
  返回构造此格式化程序时设置的区域设置。
  对于具有区域设置参数的此对象的format方法不会更改此值。
  
  返回：
  
  如果未应用本地化，则为null，否则为区域设置
  
  抛出：
  
  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)
  
  使用指定的格式字符串和参数将格式化的字符串写入此对象的目标。使用的区域设置是在构造此格式化程序时定义的区域设置。
  
  参数：
  
  format - 如格式字符串语法中所述的格式字符串。
  
  args - 格式字符串中的格式说明符引用的参数。如果有更多的参数比格式说明符，则额外的参数将被忽略。参数的最大数量受Java数组的最大维度限制，由Java虚拟机规范定义。
  
  返回：
  
  此格式化程序
  
  抛出：
  
  IllegalFormatException - 如果格式字符串包含非法语法、与给定参数不兼容的格式说明符、给定格式字符串的参数不足或其他非法条件。有关所有可能的格式错误的规范，请参阅格式化程序类规范的详细信息部分。
  
  FormatterClosedException - 如果通过调用其close()方法关闭了此格式化程序
- format
  
  public Formatter format(Locale l, String format, Object... args)
  
  使用指定的区域设置、格式字符串和参数将格式化的字符串写入此对象的目标。
  
  参数：
  
  l - 在格式化期间应用的区域设置。如果l为null，则不应用本地化。这不会更改在构造期间设置的此对象的区域设置。
  
  format - 如格式字符串语法中所述的格式字符串
  
  args - 格式字符串中的格式说明符引用的参数。如果有更多的参数比格式说明符，则额外的参数将被忽略。参数的最大数量受Java数组的最大维度限制，由Java虚拟机规范定义。
  
  返回：
  
  此格式化程序
  
  抛出：
  
  IllegalFormatException - 如果格式字符串包含非法语法、与给定参数不兼容的格式说明符、给定格式字符串的参数不足或其他非法条件。有关所有可能的格式错误的规范，请参阅格式化程序类规范的详细信息部分。
  
  FormatterClosedException - 如果通过调用其close()方法关闭了此格式化程序

Class Formatter

转换

标志

宽度

精度

参数索引

Nested Class Summary

Constructor Summary

Method Summary

Methods declared in class java.lang.Object

Constructor Details

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Formatter

Method Details

locale

out

toString

flush

close

ioException

format

format