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);
此格式字符串是 format 方法的第一个参数。它包含三个格式说明符 “%1$tm”、“%1$te” 和 “%1$tY”,它们指出应该如何处理参数以及在文本的什么地方插入它们。格式字符串的其余部分是包括 “Dukes Birthday: ” 和其他任何空格或标点符号的固定文本。 参数列表由传递给位于格式字符串之后的方法的所有参数组成。在上述示例中,参数列表的大小为 1,由对象 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 返回 true 时,可将此转换应用于 int 和 Integer类型
数值
整数 - 可应用于 Java 的整数类型:byte、Byte、short、Short、int、Integer、long、Long 和 BigInteger
浮点 - 可用于 Java 的浮点类型:float、Float、double、Double 和 BigDecimal
日期/时间 - 可应用于 Java 的、能够对日期或时间进行编码的类型:long、Long、Calendar 和 Date.
百分比 - 产生字面值 '%' ('%’)
行分隔符 - 产生特定于平台的行分隔符
下表总结了受支持的转换。由大写字符(如 'B‘、'H’、‘S’、‘C’、‘X’、‘E’、‘G’、‘A' 和 'T’)表示的转换与由相应的小写字符的转换等同,根据流行的 Locale 规则将结果转换为大写形式除外。后者等同于 String#toUpperCase()的以下调用
out.toUpperCase()
转换参数类别说明�***', 'B’常规如果参数 arg 为 null,则结果为 “false”.如果 arg 是一个 boolean 值或 Boolean,则结果为 String.valueOf()返回的字符串。否则结果为 “true”.'h', 'H‘常规如果参数 arg 为 null,则结果为 “null”.否则,结果为调用 Integer.toHexString(arg.hashCode())得到的结果。's', 'S’常规如果参数 arg 为 null,则结果为 “null”.如果 arg 实现 Formattable,则调用 arg.formatTo.否则,结果为调用 arg.toString()得到的结果。‘c', 'C’字符结果是一个 Unicode 字符‘d’整数结果被格式化为十进制整数‘o’整数结果被格式化为八进制整数‘x', 'X’整数结果被格式化为十六进制整数‘e', 'E’浮点结果被格式化为用计算机科学记数法表示的十进制数‘f’浮点结果被格式化为十进制数‘g', 'G’浮点根据精度和舍入运算后的值,使用计算机科学记数形式或十进制格式对结果进行格式化。‘a', 'A’浮点结果被格式化为带有效位数和指数的十六进制浮点数‘t', 'T’日期/时间日期和时间转换字符的前缀。请参阅日期/时间转换。‘%’百分比结果为字面值 '%' (‘%’)‘n’行分隔符结果为特定于平台的行分隔符