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。

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

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

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

宽度和精度的规范与为 Float 和 Double 定义的规范相同。

日期/时间

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

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

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

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

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

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

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

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

百分比

该转换不对应于任何参数。

行分隔符

该转换不对应于任何参数。

标志、宽度和精度都不可用。如果提供这三者，则会分别抛出 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")
     // -> "b a a 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 Machine Specification 定义的 Java 数组 的最大维数的限制。如果参数索引与可用参数不对应，则抛出 MissingFormatArgumentException。

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

除非另行指定，否则向此类中的任何方法或构造方法传递 null 参数都将抛出 NullPointerException。

从以下版本开始：

1.5

Formatter

public Formatter()

构造一个新 formatter。

格式化输出的目标文件是 StringBuilder，可以通过调用 out() 来获取它，还可以调用 toString() 将其当前内容转换为一个字符串。对于 Java 虚拟机的此实例，所使用的语言环境是默认语言环境。

Formatter

public Formatter(Appendable a)

构造一个带指定目标文件的新 formatter。

对于 Java 虚拟机的此实例，所使用的语言环境是默认语言环境。

参数：

a - 格式化输出的 Destination。如果 a 为 null，则创建一个 StringBuilder。

Formatter

public Formatter(Locale l)

构造一个带指定语言环境的新 formatter。

格式化输出的目标文件是 StringBuilder，可以通过调用 out() 来获取它，还可以调用 toString() 将其内容转换为一个字符串。

参数：

l - 格式化期间应用的语言环境。如果 l 为 null，则不应用本地化。

Formatter

public Formatter(Appendable a,
                 Locale l)

构造一个带指定目标文件和语言环境的新 formatter。

参数：

a - 格式化输出的 Destination。如果 a 为 null，则创建一个 StringBuilder。

l - 格式化期间应用的语言环境。如果 l 为 null，则不应用本地化。

Formatter

public Formatter(String fileName)
          throws FileNotFoundException

构造一个带指定文件名的新 formatter。

对于 Java 虚拟机的此实例，所使用的字符集是默认字符集。

对于 Java 虚拟机的此实例，所使用的语言环境是默认语言环境。

参数：

fileName - 用作此 formatter 的目标文件的文件名称。如果存在该文件，则将其大小截取为零；否则创建一个新文件。将输出写入文件中，并对其进行缓冲处理。

抛出：

SecurityException - 如果存在安全管理器，并且 checkWrite(fileName) 拒绝对文件进行写入访问。

FileNotFoundException - 如果给定的文件名称不表示现有的可写常规文件，并且无法创建该名称的新常规文件，或者在打开或创建文件时发生其他一些错误

Formatter

public Formatter(String fileName,
                 String csn)
          throws FileNotFoundException,
                 UnsupportedEncodingException

构造一个带指定文件名和字符集的新 formatter。

对于 Java 虚拟机的此实例，所使用的语言环境是默认语言环境。

参数：

fileName - 用作此 formatter 的目标文件的文件名称。如果存在该文件，则将其大小截取为零；否则创建一个新文件。将输出写入文件中，并对其进行缓冲处理。

csn - 受支持的字符集的名称

抛出：

FileNotFoundException - 如果给定的文件名称不表示现有的可写常规文件，并且无法创建该名称的新常规文件，或者在打开或创建文件时发生其他一些错误

SecurityException - 如果存在安全管理器，并且 checkWrite(fileName) 拒绝对文件进行写入访问

UnsupportedEncodingException - 如果不支持指定字符集

Formatter

public Formatter(String fileName,
                 String csn,
                 Locale l)
          throws FileNotFoundException,
                 UnsupportedEncodingException

构造一个带指定文件名、字符集和语言环境的新 formatter。

参数：

fileName - 用作此 formatter 的目标文件的文件名称。如果存在该文件，则将其大小截取为零；否则，创建一个新文件。将输出写入文件中，并对其进行缓冲处理。

csn - 受支持的字符集的名称

l - 格式化过程中应用的语言环境。如果 l 为 null，则不应用本地化。

抛出：

FileNotFoundException - 如果给定的文件名称不表示现有的可写常规文件，并且无法创建该名称的新常规文件，或者在打开或创建文件时发生其他一些错误

SecurityException - 如果存在安全管理器，并且 checkWrite(fileName) 拒绝对文件进行写入访问。

UnsupportedEncodingException - 如果不支持指定字符集

Formatter

public Formatter(File file)
          throws FileNotFoundException

构造一个带指定文件的新 formatter。

对于 Java 虚拟机的此实例，所使用的字符集是默认字符集。

对于 Java 虚拟机的此实例，所使用的语言环境是默认语言环境。

参数：

file - 作为此 formatter 的目标文件使用的文件。如果存在该文件，则将其大小截取为零；否则，创建一个新文件。将输出写入文件中，并对其进行缓冲处理。

抛出：

SecurityException - 如果存在安全管理器，并且 checkWrite(file.getPath()) 拒绝对文件进行写入访问。

FileNotFoundException - 如果给定的文件对象不表示现有的可写常规文件，并且无法创建该名称的新常规文件，或者在打开或创建文件时发生其他一些错误

Formatter

public Formatter(File file,
                 String csn)
          throws FileNotFoundException,
                 UnsupportedEncodingException

构造一个带指定文件和字符集的新 formatter。

对于 Java 虚拟机的此实例，所使用的语言环境是默认语言环境。

参数：

file - 作为此 formatter 的目标文件使用的文件。如果存在该文件，则将其大小截取为零；否则，创建一个新文件。将输出写入文件中，并对其进行缓冲处理。

csn - 受支持的字符集的名称

抛出：

FileNotFoundException - 如果给定的文件对象不表示现有的可写常规文件，并且无法创建该名称的新常规文件，或者在打开或创建文件时发生其他一些错误

SecurityException - 如果存在安全管理器，并且 checkWrite(file.getPath()) 拒绝对文件进行写入访问

UnsupportedEncodingException - 如果不支持指定字符集

Formatter

public Formatter(File file,
                 String csn,
                 Locale l)
          throws FileNotFoundException,
                 UnsupportedEncodingException

构造一个带指定文件、字符集和语言环境的新 formatter。

参数：

file - 作为此 formatter 的目标文件使用的文件。如果存在该文件，则将其大小截取为零；否则，创建一个新文件。将输出写入文件中，并对其进行缓冲处理。

csn - 受支持的字符集的名称

l - 格式化过程中应用的语言环境。如果 l 为 null，则不应用本地化。

抛出：

FileNotFoundException - 如果给定的文件对象不表示现有的可写常规文件，并且无法创建该名称的新常规文件，或者在打开或创建文件时发生其他一些错误

SecurityException - 如果存在安全管理器，并且 checkWrite(file.getPath()) 拒绝对文件进行写入访问。

UnsupportedEncodingException - 如果不支持指定字符集

Formatter

public Formatter(PrintStream ps)

构造一个带指定输出流的新 formatter。

对于 Java 虚拟机的此实例，所使用的语言环境是默认语言环境。

将字符写入给定的 PrintStream 对象，并使用该对象的字符集对其进行编码。

参数：

ps - 作为此 formatter 的目标文件使用的流。

Formatter

public Formatter(OutputStream os)

构造一个带指定输出流的新 formatter。

对于 Java 虚拟机的此实例，所使用的字符集是默认字符集。

对于 Java 虚拟机的此实例，所使用的语言环境是默认语言环境。

参数：

os - 作为此 formatter 的目标文件使用的流。将对输出进行缓冲。

Formatter

public Formatter(OutputStream os,
                 String csn)
          throws UnsupportedEncodingException

构造一个带指定输出流和字符集的新 formatter。

对于 Java 虚拟机的此实例，所使用的语言环境是默认语言环境。

参数：

os - 作为此 formatter 的目标文件使用的流。将对输出进行缓冲。

csn - 受支持的字符集的名称

抛出：

UnsupportedEncodingException - 如果不支持指定字符集

Formatter

public Formatter(OutputStream os,
                 String csn,
                 Locale l)
          throws UnsupportedEncodingException

构造一个带指定输出流、字符集和语言环境的新 formatter。

参数：

os - 作为此 formatter 的目标文件使用的流。将对输出进行缓冲。

csn - 受支持的字符集的名称

l - 格式化过程中应用的语言环境。如果 l 为 null，则不应用本地化。

抛出：

UnsupportedEncodingException - 如果不支持指定字符集

locale

public Locale locale()

返回构造此 formatter 时设置的语言环境。

此对象的带语言环境参数的格式方法不会更改该值。

返回：

如果没有应用本地化，则返回 null；否则返回一个语言环境

抛出：

FormatterClosedException - 如果已经通过调用 close() 方法关闭此 formatter

out

public Appendable out()

返回输出的目标文件。

返回：

输出的目标文件

抛出：

FormatterClosedException - 如果已经通过调用 close() 方法关闭此 formatter

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() 的方式完全相同。

     out().toString() 

根据针对 Appendable 的 toString 的规范，返回的字符串可能否包含（也可能不包含）写入目标文件的字符。例如，缓冲器通常在 toString() 中返回其内容，而流不能这样做，因为数据已被丢弃。

覆盖：

类 Object 中的 toString

返回：

对输出目标文件调用 toString() 的结果

抛出：

FormatterClosedException - 如果已经通过调用 close() 方法关闭此 formatter

flush

public void flush()

刷新此 formatter。如果目标文件实现 Flushable 接口，则调用其 flush 方法。

刷新 formatter 会使目标文件中的所有缓冲输出都写入底层流中。

指定者：

接口 Flushable 中的 flush

抛出：

FormatterClosedException - 如果已经通过调用 close() 方法关闭此 formatter

close

public void close()

关闭此 formatter。如果目标文件实现 Closeable 接口，则调用其 close 方法。

关闭 formatter 允许释放它可能保持（比如打开文件）的资源。如果已经关闭 formatter，则调用此方法无效。

如果试图在此 formatter 已经关闭之后调用其中除 ioException() 之外的任何方法，那么都将导致 FormatterClosedException。

指定者：

接口 Closeable 中的 close

ioException

public IOException ioException()

返回由此 formatter 的 Appendable 方法上次抛出的 IOException 异常。

如果目标文件的 append() 方法从未抛出 IOException，则此方法将始终返回 null。

返回：

如果不存在这样的异常，则返回由 Appendable 或 null 上次抛出的异常。

format

public Formatter format(String format,
                        Object... args)

使用指定格式字符串和参数将一个格式化字符串写入此对象的目标文件中。使用的语言环境是构造此 formatter 期间定义的语言环境。

参数：

format - 在格式字符串的语法中描述的格式字符串。

args - 格式字符串中的格式说明符引用的参数。如果参数多于格式说明符，则忽略额外的参数。参数的最大数量受到 Java Virtual Machine Specification 定义的 Java 数组的最大维数的限制。

返回：

此 formatter

抛出：

IllegalFormatException - 如果格式字符串包含非法语法、与给定参数不兼容的格式说明符、对给定格式字符串而言不够充足的参数或其他非法条件。有关所有可能的格式错误的规范，请参阅 formatter 类规范的详细信息部分。

FormatterClosedException - 如果已经通过调用 close() 方法关闭此 formatter

format

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

使用指定的语言环境、格式字符串和参数，将一个格式化字符串写入此对象的目标文件中。

参数：

l - 格式化过程中应用的语言环境。如果 l 为 null，则不应用本地化。这不会改变构造期间设置的对象的语言环境。

format - 在格式字符串的语法中描述的格式字符串

args - 格式字符串中的格式说明符引用的参数。如果参数多于格式说明符，则忽略额外的参数。参数的最大数量受到 Java Virtual Machine Specification 定义的 Java 数组的最大维数的限制

返回：

此 formatter

抛出：

IllegalFormatException - 如果格式字符串包含非法语法、与给定参数不兼容的格式说明符、对给定格式字符串而言不够充足的参数或其他非法条件。有关所有可能的格式错误的规范，请参阅 formatter 类规范的详细信息部分。

FormatterClosedException - 如果已经通过调用 close() 方法关闭此 formatter

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。