[Series title]:?--驯服 Tiger：格式化输出
让它有 printf
John Zukowski (jaz@zukowski.net)
总裁，JZ Ventures, Inc.
2004 年 4 月
J2SE 1.4 版原来的计划是包括对格式化输出的支持。可能由于时间限制及这个功能对新版本的发布不起决定作用的缘故，在发表的版本中没有加入这些功能。现在有了 Tiger，对打印带格式的字符串有了内在支持。
对于那些从一开始就使用 Java 编程而从没有接触过 C 的人，或者，对那些对 C 没有足够了解的人，格式化字符串是一些古怪的文本串，它们指定一组变量的输出特性。不是用加号将字符串连接在一起（如 firstName + " " + lastName），而是提供一个字符串描述输出，并提供参数以在方法调用结束时，替换字符串中的占位符：String s = String.format("%1$s %2$s", firstName, lastName)。
Formatter 类
首先，让我们分析新的 java.util.Formatter 类。您可能不会经常直接使用这个类，但是它提供了所要进行的格式化的内部机制。在这个类的 Javadoc 中，会看到一个描述所支持的格式化选项的表。这些选项的范围从以类似 %7.4f 这样的格式指定浮点数的精度和位数，到格式化时间的 %tT，到格式化第三个参数 %3$s。
用 Formatter 格式化输出分为两步：创建一个 Appendable 对象以存储输出，用 format() 方法将带格式的内容放到这个对象中。下面列出了 Appendable 接口的实现器：
BufferedWriter
CharArrayWriter
CharBuffer
FileWriter
FilterWriter
LogStream
OutputStreamWriter
PipedWriter
PrintStream
PrintWriter
StringBuffer
StringBuilder
StringWriter
Writer
在使用 Formatter 类时，可以将实现了这个接口的对象传递给构造函数 Formatter 以把它作为目标。大多数这种类看起来很相似，除了 StringBuilder 类。StringBuilder 与 StringBuffer 类几乎相同，只有一个大的区别：它不是线程安全的。如果知道要在单线程中构建字符串，就使用 StringBuilder。如果构建过程会跨越多个线程，则使用 StringBuffer。清单 1 显示了通常如何开始使用 Formatter：
清单 1. formatter 的典型用法
StringBuilder sb = new StringBuilder();
Formatter formatter = new Formatter(sb, Locale.US);
创建了Formatter 类后，用格式化字符串和参数调用其 format() 方法。如果需要使用与传递给出构造函数的不同的 Locale 作为格式化输出的一部分，还可以向 format() 方法传递一个 Locale 对象。清单 2 显示了两种不同的 format()：
清单 2. Formatter 的 format() 方法
public Formatter format(String format,
Object... args)
public Formatter format(Locale l,
String format,
Object... args)
如果希望得到精度为 10 位数字的 Pi 值，清单 3 中的代码会将这个值放到 StringBuilder 中并打印输出。打印 formatter 对象将显示 Appendable 对象的内容。
清单 3. 演示一个 Formatter
import java.util.Locale;
import java.util.Formatter;
public class Build {
public static void main(String args[]) {
StringBuilder sb = new StringBuilder();
Formatter formatter = new Formatter(sb, Locale.US);
formatter.format("PI = %12.10f", Math.PI);
System.out.println(formatter);
}
}
不要忘记用 -source 1.5 选项编译，否则编译器不会识别变量参数列表。因为格式化输出并将它发送给控制台是一项常见的任务，所以对这种操作提供了方便的方法。我们将在下面对此进行讨论。
PrintStream 支持
PrintStream 类中定义了常见的、分别用于写入标准输出和标准错误的 System.out 和 System.err 对象。Tiger 引入了两个新的构造函数（用于直接写入文件）和六个方法以提供对格式化的支持（三对）。第一对是另一版本的 append() 方法。这一对方法实现了新的 java.lang.Appendable 接口。一般不会直接调用这些方法。直接调用的是 format() 和 printf()，其中 printf() 版本只是 format() 版本的方便的包装器，如清单 4 所示：
清单 4. PrintStream.format 方法
public PrintStream format(String format,
Object... args)
public PrintStream format(Locale l,
String format,
Object... args)
要记住新的变量参数支持，它是由 ... 指派的，如上面清单 4 所示。
清单 5 演示了用 PrintStream 的 format() 方法打印今天的日期：
清单 5. 使用 PrintStream.format 的例子
/
import java.util.Calendar;
public class Now {
public static void main(String args[]) {
System.out.format(
"Today is %1$tB %1$te, %1$tY.",
Calendar.getInstance()
);
}
}
运行这个程序的输出是 Today is April 2, 2004.，当然实际的输出取决于运行这个程序的日期。上面代码中的格式化字符串 %1$tB 告诉程序使用第一个参数并打印 date 对象的完整月名。格式化字符串 %1$te 意味着显示月中的日期，而格式化字符串 %1$tY 是四位数字的年。在 Formatter 对象的 Javadoc 中列出了打印日期的其他选项。
String 支持
String 类有两个新的 static format() 方法，它们的作用与相应的 printf() 类似。发送一个格式化字符串和参数（还可能有 Locale）、并使用在格式化字符串中指定的格式转换参数。如果是这个方法的 String 版本，那么是以 String 对象而不是经过流返回结果。这些方法不是很显眼，但是有了它们就可以避免直接使用 Formatter 对象并创建中间的 StringBuilder。
格式化任意对象
到目前为止看到的每项内容都是描述如何使用新的格式化能力对已有对象和基本数据进行格式化。如果希望用 Formatter 提供对自己的对象的支持，那么就要用到 Formattable 接口。通过在自己的类中实现如清单 6 所示的一个 formatTo() 方法，可以对自已的类使用格式化字符串：
清单 6. Formattable 接口
void formatTo(Formatter formatter,
int flags,
Integer width,
Integer precision)
清单 7 演示了通过提供一个具有 name 属性的简单类来使用 Formattable 接口。这个 name 显示在输出中，它支持控制输出的宽度和对齐。
清单 7. formattable 使用示例
import java.util.Locale;
import java.util.Formatter;
import java.util.Formattable;
public class MyObject implements Formattable {
String name;
public MyObject(String name) {
this.name = name;
}
public void formatTo(
Formatter fmt,
int f,
Integer width,
Integer precision) {
StringBuilder sb = new StringBuilder();
if (precision == null) {
// no max width
sb.append(name);
} else if (name.length() < precision) {
sb.append(name);
} else {
sb.append(name.substring(0, precision - 1)).append('*');
}
// apply width and justification
if ((width != null) && (sb.length() < width)) {
for (int i = 0, n=sb.length(); i < width - n; i++) {
if ((f & Formattable.LEFT_JUSTIFY) == Formattable.LEFT_JUSTIFY) {
sb.append(' ');
} else {
sb.insert(0, ' ');
}
}
}
fmt.format(sb.toString());
}
public static void main(String args[]) {
MyObject my1 = new MyObject("John");
MyObject my2 = new MyObject("Really Long Name");
// First / Using toString()
System.out.println("First Object : " + my1);
// Second / Using Formatter
System.out.format("First Object : '%s'\\n", my1);
// Second / Using Formatter
System.out.format("Second Object: '%s'\\n", my2);
// Second / Using Formatter with width
System.out.format("Second Object: '%10.5s'\\n", my2);
// Second / Using Formatter with width and left justification
System.out.format("Second Object: '%-10.5s'\\n", my2);
}
}
运行这个程序会生成如清单 8 所示的输出。前两行展示了使用 toString 和 Formatter 的不同结果。后三行显示宽度和对齐控制的选项。
清单 9. formattable 输出示例
First Object : MyObject@10b62c9
First Object : 'John'
Second Object: 'Really Long Name'
Second Object: ' Real*'
Second Object: 'Real* '
结束语
除非通过使用 C 对它们已经很熟悉了，否则掌握 Formatter 中提供的所有格式化选项要花一些时间。有一些小的区别，但是大部分的行为是非常类似的。Java 平台上的一个重要的不同是当格式化字符串无效时会抛出异常。
一定要仔细查看 Formatter 类的 Javadoc 中所列出的可用的格式化字符串。在创建自己的自定义类时，不仅提供一个 toString() 实现，而且实现 Formattable 接口通常会有帮助。
