鸿蒙OS Formatter

Formatter

java.lang.Object

|—java.util.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(String,Object…) 格式化字符串：

   // 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"

组织

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

概括

本节旨在提供格式化概念的简要概述。

格式化字符串语法

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

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

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

• 通用、字符和数字类型的格式说明符具有以下语法：

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

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

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

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

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

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

• 用于表示日期和时间的类型的格式说明符具有以下语法：

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

可选的参数索引、标志和宽度定义如上。

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

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

     %[flags][width]conversion 

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

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

转换

转换分为以下几类：

1. 一般 – 可应用于任何参数类型

1. 字符 – 可应用于表示 Unicode 字符的基本类型：char、Character、byte、Byte、short 和 Short。 当 Character#isValidCodePoint 返回 true 时，这种转换也可以应用于 int 和 Integer 类型

1. 数字

• Integral – 可应用于 Java 整数类型：byte、Byte、short、Short、int 和 Integer、long、Long 和 BigInteger（但不是 char 或 Character）

• 浮点 – 可应用于 Java 浮点类型：float、Float、double、Double 和 BigDecimal

1. 日期/时间 – 可应用于能够编码日期或时间的 Java 类型：long、Long、Calendar、Date 和 TemporalAccessor

1. 百分比 – 产生一个文字 ‘%’ (‘\u0025’)

1. Line Separator – 生成特定于平台的行分隔符

下表总结了支持的转换。 由大写字符表示的转换（即“B”、“H”、“S”、“C”、“X”、“E”、“G”、“A”和“T”）是相同的 与对应的小写转换字符相同，只是根据当前 Locale 的规则将结果转换为大写。 结果等效于以下对 String#toUpperCase() 的调用

    out.toUpperCase() 

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

日期/时间转换

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

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

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

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

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

标志

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

1. 取决于 Formattable 的定义。
2. 仅用于“d”转换。

1. 仅适用于“o”、“x”和“X”转换。

1. 对于应用于 BigInteger 的 ‘d’、’o’、’x’ 和 ‘X’ 转换或应用于 byte、Byte、short、Short、int 和 Integer、long 和 Long 的 ‘d’。

1. 仅适用于“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。

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

Formatter 的任何格式方法以及任何格式便利方法（例如 String#format(String,Object…) 和 PrintStream.printf）都可能引发所有指定的异常。

由大写字符表示的转换（即“B”、“H”、“S”、“C”、“X”、“E”、“G”、“A”和“T”）是相同的与对应的小写转换字符相同，只是根据当前 Locale 的规则将结果转换为大写。结果等效于以下对 String#toUpperCase() 的调用

    out.toUpperCase() 

一般的

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

以下标志适用于一般转换：

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

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

字符 这种转换可以应用于 char 和 Character。当 Character#isValidCodePoint 返回 true 时，它也可以应用于 byte、Byte、short 和 Short、int 和 Integer 类型。如果它返回 false，则会抛出 IllegalFormatCodePointException。

为常规转换定义的“-”标志适用。如果给出了 ‘#’ 标志，则将抛出 FormatFlagsConversionMismatchException。

宽度定义为通用转换。

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

数字

数值转换分为以下几类：

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

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

号码定位算法

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

1. 字符串中的每个数字字符 d 被替换为相对于当前语言环境的零位 z 计算的语言环境特定数字；即 d – ‘0’ + z。
2. 如果存在小数分隔符，则替换特定于区域设置的小数分隔符。
3. 如果给出’,’ (‘\u002c’) 标志，则通过从最低有效位到最高有效位扫描字符串的整数部分并在由语言环境的分组大小。
4. 如果给出 ‘0’ 标志，则在符号字符（如果有）之后和第一个非零数字之前插入特定于语言环境的零数字，直到字符串的长度等于请求的字段宽度.
5. 如果值为负并且给出了 ‘(‘ 标志，则附加一个 ‘(‘ (‘\u0028’) 并附加一个 ‘)’ (‘\u0029’)。
6. 如果该值为负数（或浮点负零）并且没有给出'(‘ 标志，则在前面加上’-‘ (‘\u002d’)。
7. 如果给出’+’ 标志并且值为正或零（或浮点正零），则将在前面加上’+’ (‘\u002b’)。

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

Byte, Short, Integer, and Long

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

如果转换为 ‘o’、’x’ 或 ‘X’ 并且同时给出了 ‘#’ 和 ‘0’ 标志，则结果将包含基数指示符（’0′ 表示八进制和“0x”或“ 0X” 表示十六进制）、一些零（基于宽度）和值。

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

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

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

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

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

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

BigInteger

以下转换可应用于 BigInteger。

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

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

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

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

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

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

Float and Double

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

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

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

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

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

宽度是要写入输出的最小字符数。这包括任何符号、数字、分组分隔符、小数分隔符、指数符号、基数指示符、括号以及表示无穷大和 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 的定义相同。

Date/Time

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

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

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

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

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

为常规转换定义的“-”标志适用。如果给出了 ‘#’ 标志，则将抛出 FormatFlagsConversionMismatchException。

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

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

Percent

转换不对应于任何参数。

Line Separator

转换不对应于任何参数。

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

Argument Index

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

• 当格式说明符包含参数索引时，使用显式索引。 参数索引是一个十进制整数，指示参数在参数列表中的位置。 第一个参数由“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。

嵌套类摘要

构造函数摘要

方法总结

构造函数详细信息

Formatter

public Formatter()

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

格式化输出的目的地是一个 StringBuilder，可以通过调用 out() 来检索它，并且可以通过调用 toString() 将其当前内容转换为字符串。 对于此 Java 虚拟机实例，使用的语言环境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

Formatter

public Formatter(Appendable a)

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

对于此 Java 虚拟机实例，使用的语言环境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

参数：

Formatter

public Formatter(Locale l)

构造具有指定语言环境的新格式化程序。

格式化输出的目的地是一个 StringBuilder，可以通过调用 out() 来检索它，并且可以通过调用 toString() 将其当前内容转换为字符串。

参数：

Formatter

public Formatter(Appendable a, Locale l)

构造具有指定目标和语言环境的新格式化程序。

参数：

Formatter

public Formatter(String fileName) throws FileNotFoundException

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

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

对于此 Java 虚拟机实例，使用的语言环境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

参数：

Throws:

Formatter

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

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

对于此 Java 虚拟机实例，使用的语言环境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

参数：

Throws:

Formatter

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

使用指定的文件名、字符集和语言环境构造一个新的格式化程序。

参数：

Throws:

Formatter

public Formatter(File file) throws FileNotFoundException

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

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

对于此 Java 虚拟机实例，使用的语言环境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

参数：

Throws:

Formatter

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

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

对于此 Java 虚拟机实例，使用的语言环境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

参数：

Throws:

Formatter

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

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

参数：

Throws:

Formatter

public Formatter(PrintStream ps)

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

对于此 Java 虚拟机实例，使用的语言环境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

字符被写入给定的 PrintStream 对象，因此使用该对象的字符集进行编码。

参数：

Formatter

public Formatter(OutputStream os)

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

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

对于此 Java 虚拟机实例，使用的语言环境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

参数：

Formatter

public Formatter(OutputStream os, String csn) throws UnsupportedEncodingException

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

对于此 Java 虚拟机实例，使用的语言环境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

参数：

Throws:

Formatter

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

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

参数：

Throws:

方法详情

locale

public Locale locale()

返回由构造此格式化程序设置的语言环境。

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

返回:

如果未应用本地化，则为 null，否则为语言环境

Throws:

out

public Appendable out()

返回输出的目的地。

返回:

输出的目的地

Throws:

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() 中返回其内容，但流不能，因为数据被丢弃。

覆盖：

类 Object 中的 toString

返回:

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

Throws:

flush

public void flush()

刷新此格式化程序。 如果目标实现了 Flushable 接口，则会调用其 flush 方法。

刷新格式化程序会将目标中的任何缓冲输出写入底层流。

指定者：

在接口 Flushable 中刷新

Throws:

close

public void close()

关闭此格式化程序。 如果目标实现了 Closeable 接口，则将调用其 close 方法。

关闭格式化程序允许它释放它可能持有的资源（例如打开的文件）。 如果格式化程序已经关闭，则调用此方法无效。

在此格式化程序关闭后尝试调用除 ioException() 之外的任何方法将导致 FormatterClosedException。

指定者：

在接口 AutoCloseable 中关闭

指定者：

在接口Closeable中关闭

ioException

public IOException ioException()

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

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

返回:

Appendable 抛出的最后一个异常，如果不存在此类异常，则返回 null。

format

public Formatter format(String format, Object… args)

使用指定的格式字符串和参数将格式化字符串写入此对象的目标。 使用的语言环境是在构造此格式化程序期间定义的语言环境。

参数：

返回:

这个格式化程序

Throws:

format

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

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

参数：

返回:

这个格式化程序

Throws: