JavaThe Formatter Class in J2SE 1.5

The Formatter Class in J2SE 1.5 content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Java 1.5 introduces a new class named java.util.Formatter that allows you to do string formatting similar to the printf function in C. It depends heavily on the varargs feature being introduced in 1.5.


The first way you’ll learn to work with the Formatter is not to interact with it directly, but instead to use the new PrintStream method printf. You’re probably most familiar with PrintStream from doing System.out.println calls. Here is a simple example of the new printf method:

String initials = "jjl";
String comment  = "just because";
System.out.printf("reason: %s (noted by %s)", comment, initials);

The example prints the following output on the console:

reason: just because (noted by jjl)

In the example code, you are passing printf a format string that contains embedded format specifiers. You also pass it a list of arguments, each of which corresponds to a format specifier. There are two format specifiers in the example: %s and %s. The first corresponds to the comment argument, and the second corresponds to the initials argument.

A % in a format string designates the start of a format specifier. The end of a format specifier is triggered by one of many possible characters known as conversions. In the %s format specifier, the lowercase s indicates a String conversion. A string conversion means that Java calls toString on the corresponding argument, and substitutes the result for the format specifier.


If you only want to obtain a formatted string, but not print it, you can use the static method format on the String class. Here’s an example that also demonstrates a few numeric conversions:

int a = 65;
String s = 
   String.format("char: %c integral: %d octal: %o hex: %x %n",
      a, a, a, a);

The %n at the end of the format string indicates a platform-specific line separator. When printed, the String s looks like this:

char: A integral: 65 octal: 101 hex: 41

Numeric conversions also support flags for padding, grouping, justification, and sign.

Note: There are four arguments, each using the reference a. Were you to supply only three, or were one of the arguments an invalid type (for example, a string), the format method would have generated one of a few runtime exceptions. This is unlike C, which ignores any formatting problems.

If you want to use the same argument more than once against a format string, you can use a shortcut:

String s = String.format("char: %c integral:
           %<d octal: %<o hex: %<x %n", a);

The a reference is specified only once. The less-than sign (<) in a format specifier means that it should use the same argument as the last format specifier.


Formatter provides an extensive number of date-related conversions. The following code:

String.format("%1$td %1$tb %1$ty", new Date())

produces a string with the value:

26 Feb 04

The 1$ in each format specifier is another way to designate which argument to use. In this example, all three format specifiers target the first argument.

The last part of each format specifier is how you do date conversions—using a two-character sequence starting with a t. The second character indicates the date part to convert. For example, td in the first specifier converts the day of the month.


The Formatter class is at the core of the new formatting capability. It fully supports internationalization by letting you pass a Locale to the constructor; the other formatting methods (e.g. String.format) also allow this.

Formatter also lets you pass an Appendable object. This is a new interface that defines append methods so that the formatter can store its results in a text collector such as a stream object. Sun has modified all relevant Java classes, such as StringBuffer and PrintStream, to implement this interface. Here’s how you might use it:

double avogadro     = 6.0e23;
StringBuffer buffer = new StringBuffer();
Formatter formatter = new Formatter(buffer, Locale.US);
formatter.format("avogadro's number: %e %n", avogadro);
formatter.format("base of the natural log: %e %n", Math.E);

The corresponding output:

avogadro's number:       6.000000e+23
base of the natural log: 2.718282e+00


There are dozens of conversions available in the Formatter class and a few more things that are not covered here. To learn more about formatting, refer to the Java API documentation pages for java.util.Formatter.

Trying It Out

You can download the current beta version of J2SE 1.5 from Sun’s Web site.

About the Author

Jeff Langr is a freelance author and the owner of Langr Software Solutions. He is working on a second book on Java and test-driven development entitled Agile Java, due out from Prentice Hall in fall 2004.

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories