Formatter

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();
   // 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$tm %1$te,%1$tY", c);
   // -> s == "Duke's Birthday: May 23, 1995"
 

Organization

本规范分为两部分。 第一部分Summary涵盖了基本的格式化概念。 本节适用于希望快速入门并熟悉其他编程语言的格式化打印的用户。 第二部分Details涵盖了具体的实施细节。 它适用于希望更精确地指定格式化行为的用户。

Summary

本节旨在提供格式概念的简要概述。 有关精确的行为细节，请参阅Details部分。

Format String Syntax

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

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

• The format specifiers for general, character, and numeric types have the following syntax:

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

  可选的argument_index是一个十进制整数，指示参数列表中参数的位置。 第一个参数由“ 1$ ”引用，第二个由“ 2$ ”等2$ 。

  可选标志是一组修改输出格式的字符。 有效标志的集合取决于转换。

  可选 宽度是一个非负十进制整数，指示要写入输出的最小字符数。

  可选精度是一个非负十进制整数，通常用于限制字符数。 具体行为取决于转换。

  所需的转换是指示如何格式化参数的字符。 给定参数的一组有效转换取决于参数的数据类型。

• The format specifiers for types which are used to represents dates and times have the following syntax:

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

  可选的 argument_index ， 标志和 宽度如上定义。

  所需的转换是一个双字符序列。 第一个字符是't'或'T' 。 第二个字符表示要使用的格式。 这些字符与GNU date和POSIX strftime(3c)定义的字符相似，但不完全相同。

• The format specifiers which do not correspond to arguments have the following syntax:

     %[flags][width]conversion
   

  可选的 标志和 宽度如上定义。

  所需的 转换是指示要插入输出中的内容的字符。

Conversions

转化分为以下几类：

1. General - may be applied to any argument type
2. Character - may be applied to basic types which represent Unicode characters: char, Character, byte, Byte, short, and Short. This conversion may also be applied to the types int and Integer when isValidCodePoint(int) returns true
3. Numeric
   1. Integral - may be applied to Java integral types: byte, Byte, short, Short, int and Integer, long, Long, and BigInteger
   2. Floating Point - may be applied to Java floating-point types: float, Float, double, Double, and BigDecimal
4. Date/Time - may be applied to Java types which are capable of encoding a date or time: long, Long, Calendar, and Date.
5. Percent - produces a literal '%' ('\u0025')
6. Line Separator - produces the platform-specific line separator

下表总结了支持的转换。 通过一个大写字符标记转换（即'B' ， 'H' ， 'S' ， 'C' ， 'X' ， 'E' ， 'G' ， 'A' ，和'T' ）是相同的那些相应的小写转换字符除了将结果转换成上根据现行的Locale的规则。 结果等同于以下调用toUpperCase()

    out.toUpperCase() 

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

Date/Time Conversions

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

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

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

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

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

Flags

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

¹取决于 Formattable的定义。

²仅适用于 'd'转换。

^3仅适用 'o' 'x'和 'X'转换。

⁴对于 'd' ， 'o' ， 'x'和 'X'施加到转换 BigInteger或 'd'施加到 byte ， Byte ， short ， Short ， int和 Integer ， long ，和 Long 。

⁵对于 'e' ， 'E' ， 'f' ， 'g' ，并 'G'只有转换。

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

Width

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

Precision

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

对于浮点转换'e' ， 'E'和'f'精度的位数小数分隔符后的数目。 如果转换结果为'g'或'G' ，则精度是舍入后得到的幅度中的总位数。 如果转换为'a'或'A' ，则不得指定精度。

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

Argument Index

参数索引是一个十进制整数，指示参数列表中参数的位置。 第一个参数由“ 1$ ”引用，第二个由“ 2$ ”等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);
 

Details

本部分旨在提供格式化的行为细节，包括条件和例外，支持的数据类型，本地化以及标志，转换和数据类型之间的交互。 有关格式化概念的概述，请参阅Summary

任何未明确定义为转换，日期/时间转换后缀或标志的字符都是非法的，并且为未来的扩展而保留。 在格式字符串中使用这样的字符将导致引发UnknownFormatConversionException或UnknownFormatFlagsException 。

如果格式说明符包含带有无效值的宽度或精度，或者其他方式不受支持， IllegalFormatPrecisionException分别引发 IllegalFormatWidthException或 IllegalFormatPrecisionException 。

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

所有指定的异常可通过任何的抛出 format的方法 Formatter以及通过任何 format方便的方法，例如 String.format和 PrintStream.printf 。

通过一个大写字符标记转换（即'B' ， 'H' ， 'S' ， 'C' ， 'X' ， 'E' ， 'G' ， 'A' ，和'T' ）是相同的那些相应的小写转换字符除了将结果转换成上根据现行的Locale的规则。 结果等同于以下toUpperCase()调用

    out.toUpperCase() 

General

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

以下 flags适用于一般转换：

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

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

Character

适用于General conversions的'-'标志适用。 如果给出'#'标志，则会抛出FormatFlagsConversionMismatchException 。

宽度定义为 General conversions 。

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

Numeric

数字转换分为以下几类：

1. Byte, Short, Integer, and Long
2. BigInteger
3. Float and Double
4. BigDecimal

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

Number Localization Algorithm

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

1. Each digit character d in the string is replaced by a locale-specific digit computed relative to the current locale's zero digit z; that is d -  '0'  + z.
2. If a decimal separator is present, a locale-specific decimal separator is substituted.
3. If the ',' ('\u002c') flag is given, then the locale-specific grouping separator is inserted by scanning the integer part of the string from least significant to most significant digits and inserting a separator at intervals defined by the locale's grouping size.
4. If the '0' flag is given, then the locale-specific zero digits are inserted after the sign character, if any, and before the first non-zero digit, until the length of the string is equal to the requested field width.
5. If the value is negative and the '(' flag is given, then a '(' ('\u0028') is prepended and a ')' ('\u0029') is appended.
6. If the value is negative (or floating-point negative zero) and '(' flag is not given, then a '-' ('\u002d') is prepended.
7. If the '+' flag is given and the value is positive or zero (or floating-point positive zero), then a '+' ('\u002b') will be prepended.

如果该值为NaN或正无穷大，则分别输出字符串“NaN”或“Infinity”。 如果该值为负无穷大，则输出将为“（Infinity）”，如果'('标志被给出，则输出将为“-Infinity”。 这些值不是本地化的。

Byte, Short, Integer, and Long

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

如果转换是 'o' ， 'x' ，或 'X'并且两个 '#'和 '0'标志，那么结果将包含（基数指示符 '0'为八进制和 "0x"或 "0X"为十六进制）时，一些数量的零（基于宽度）和价值。

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

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

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

• The output is right-justified within the width
• Negative numbers begin with a '-' ('\u002d')
• Positive numbers and zero do not include a sign or extra leading space
• No grouping separators are included

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

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

BigInteger

以下转换可能适用于 BigInteger 。

如果转换是 'o' ， 'x' ，或 'X'并且两个 '#'和 '0'标志，那么结果将包含（基座指示器 '0'为八进制和 "0x"或 "0X"为十六进制）时，一些数量的零（基于宽度）和价值。

如果给出了 '0'标志并且该值为负值，那么零填充将在符号之后发生。

如果没有给出 '-'标志，那么空格填充将发生在符号之前。

所有为Byte，Short，Integer和Long定义的flags都适用。 未给出标志时的default behavior与Byte，Short，Integer和Long相同。

规范 width与为Byte，Short，Integer和Long定义的相同。

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

Float and Double

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

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

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

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

• The output is right-justified within the width
• Negative numbers begin with a '-'
• Positive numbers and positive zero do not include a sign or extra leading space
• No grouping separators are included
• The decimal separator will only appear if a digit follows it

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

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

如果转换是'g'或'G' ，那么精度是四舍五入后得到的幅度中的有效位数的总数。 如果未指定精度，则默认值为6 。 如果精度是0 ，那么它被认为是1 。

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

BigDecimal

以下转换可应用于 BigDecimal 。

对于Byte，Short，Integer和Long定义的所有 flags都适用。

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

没有标志时， default behavior与Float和Double相同。

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

Date/Time

这种转换可以应用于 long ， Long ， Calendar ，和 Date 。

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

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

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

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

适用于General conversions的'-'标志适用。 如果'#'标志被给出，则FormatFlagsConversionMismatchException将被抛出。

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

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

Percent

转换不符合任何参数。

Line Separator

转换不符合任何参数。

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

Argument Index

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

• Explicit indexing is used when the format specifier contains an argument index. The argument index is a decimal integer indicating the position of the argument in the argument list. The first argument is referenced by "1$", the second by "2$", etc. An argument may be referenced more than once.

  例如：

     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"
   

• Relative indexing is used when the format specifier contains a '<' ('\u003c') flag which causes the argument for the previous format specifier to be re-used. If there is no previous argument, then a MissingFormatArgumentException is thrown.

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

• Ordinary indexing is used when the format specifier contains neither an argument index nor a '<' flag. Each format specifier which uses ordinary indexing is assigned a sequential implicit index into argument list which is independent of the indices used by explicit or relative indexing.

     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
 

参数的最大数量由The Java™ Virtual Machine Specification定义的Java数组的最大维数限制。 如果参数索引不符合可用参数，则会引发MissingFormatArgumentException 。

如果有比格式说明符更多的参数，则会忽略额外的参数。

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

Summary

Inherited methods
From class java.lang.Object Object clone() 创建并返回此对象的副本。 boolean equals(Object obj) 指示其他某个对象是否“等于”这一个。 void finalize() 当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。 final Class<?> getClass() 返回此 Object的运行时类。 int hashCode() 返回对象的哈希码值。 final void notify() 唤醒正在等待该对象监视器的单个线程。 final void notifyAll() 唤醒在该对象监视器上等待的所有线程。 String toString() 返回对象的字符串表示形式。 final void wait(long millis, int nanos) 导致当前线程等待，直到另一个线程调用此对象的 notify()方法或 notifyAll()方法，或其他某个线程中断当前线程，或者经过一定的实时时间。 final void wait(long millis) 导致当前线程等待，直到另一个线程调用此对象的 notify()方法或 notifyAll()方法或经过了指定的时间量。 final void wait() 导致当前线程等待，直到另一个线程调用此对象的 notify()方法或 notifyAll()方法。
From interface java.io.Closeable abstract void close() 关闭此流并释放与其关联的所有系统资源。
From interface java.io.Flushable abstract void flush() 通过将任何缓冲输出写入基础流来刷新此流。
From interface java.lang.AutoCloseable abstract void close() 关闭此资源，放弃任何底层资源。

Public constructors

Formatter ()

Formatter (Appendable a)

Formatter (Locale l)

Formatter (Appendable a, 
                Locale l)

Formatter (String fileName)

Formatter (String fileName, 
                String csn)

Formatter (String fileName, 
                String csn, 
                Locale l)

Formatter (File file)

Formatter (File file, 
                String csn)

Formatter (File file, 
                String csn, 
                Locale l)

Formatter (PrintStream ps)

Formatter (OutputStream os)

Formatter (OutputStream os, 
                String csn)

Formatter (OutputStream os, 
                String csn, 
                Locale l)

Public methods

void close ()

void flush ()

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

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

IOException ioException ()

Locale locale ()

Appendable out ()

String toString ()

     out().toString()