Java 1.5 Tiger A Developers Notebook [Electronic resources]

9.2 Writing Formatted Output

Once you've got your Formatter instance, I'm going to make the rather silly leap to assuming you want to use it. The best way to do this is through the format( ) method.

NOTE

A sink is a term used to refer to where output goes tosort of a collection bin. Often this is some output mechanism, like an Output-Stream, or an object that can later output what is in the sink, such as StringBuffer.

9.2.1 How do I do that?

First, let's deal with the easy stuffthis new class has some simple methods to let you find out how it's configured:

// Return the locale for this Formatter
public Locale locale( );
// Returns the last thrown IOException by the sink
public IOException ioException( );
// Returns the sink for output
public Appendable out( );

There is also a close( ) method, which, unsurprisingly, closes the formatter when you're done with output (which is particularly important when you're holding onto file resources).

The most interesting methods are the two versions of format( ):

// Notice the varargs for multiple object arguments
public Formatter format(String format, Object... args);
// Same as above, but with a Locale
public Formatter format(Locale l, String format, Object... args);

While these methods return the object they're working on, it's common to not assign this return value, and merely discard it instead. This method works, as shown here (in a simple example):

StringBuilder sb = new StringBuilder( );
Formatter formatter = new Formatter(sb);
formatter.format("Remaining account balance: $%.2f", balance);

NOTE

If you're unclear on how varargs or the Object... notation works, check out Chapter 5.

This example would output the value in the balance variable, as a floating point number, with two decimal places allowed. For those of you used to methods like printf( ) in C, this is no big deal. For those of you who didn't grow up on a steady diet of structs, this is still probably a bit odd.

First, the String to output is passed inno big deal here. However, within that String are several items that are dynamicnot known until run-time. In the previous example, the dynamic item is the value of balance. Anytime you need to insert dynamic data like that, the % indicates that a value will be supplied, in the argument list (remember Object...), to be inserted into the String. The characters after the % indicate how that value should be formatted:

%[argument][flags][width][.precision]type

9.2.1.1 Types

The only requirement here is type , so the example you saw previously could be written in its simplest format as shown here:

formatter.format("Remaining account balance: $%f", balance);

NOTE

If uppercase and lowercase versions are listed (%s, %S), the uppercase variant produces the same output as the lowercase variant, except that all lowercase letters are converted to uppercase.

Table 9-1 is a rundown of all the available types. Note that these are actually conversion typesif the value supplied is not in the specified format, a conversion is attempted.

Because date/time are a bit of a special case, they are listed in their own table, Table 9-2.

I know that's a lot of dry detail, especially for a down-and-dirty book such as this, but now you've got all the conversion codes at your fingertips.

9.2.1.2 Precision

You can add an optional precision indicator to your format string:

formatter.format("Remaining account balance: $%.2f", balance);

By adding .2, it indicates that the value of balance should be given two decimal places of precision, ensuring you get a number like 2510.00 instead of 2510. .2 in this case fills the precision spot in the syntax list. Here are a few rules that apply:

For %e, %E, and %f, the default precision is 6.

For %g and %G, the precision is the total number of significant digits to be displayed.

For %s, %h, and %b (and their uppercase variants), the precision determines the maximum characters output.

If the formatted output exceeds precision , the output is truncated. Additionally, specifying precision for other conversion types can result in an exception at runtime (not compile time).

Trailing zeros are always added as needed, to match the specified (or default) precision, for numeric types.

9.2.1.3 Width

In addition to precision, the total minimum number of characters to be produced can be set through width :

formatter.format("Remaining account balance: $%6.2f", balance);

Here, the balance will be shown with at least six digits of total characters. If the formatted output is less than the specified width, zeroes are added as padding on the left (values are right-justified). A width can be specified for any conversion type other than %n (which isn't a true conversion type anywayit's a line separator).

If precision is smaller than width , the formatted value is truncated to the supplied precision, and then padded with zeros to the supplied width.

9.2.1.4 Argument

By default, calls to format( ) (and printf( ), detailed in "Using the printf( ) Convenience Method") match each conversion with the arguments supplied to the method, in order, one after another. However, you can optionally change that behavior with an argument indicator:

formatter.format("Remaining account balance: $%6.2f"+
"(Today's total balance:     $%<8.2f)", balance);

Here, the < argument is used to indicate that the previous argument should be used (again), rather than continuing on. This is a clever way to reuse arguments without listing them in the argument list multiple times. It also allows the same argument to be formatted in different ways:

formatter.format("Date: %tD%nTime: %<tr%n", System.currentTimeMillis( ));

You can also explicitly refer to an argument by its position, using the syntax [arg-number]$. Thus, you could refer to the second argument in the list with %2$.

9.2.1.5 Flags

The final option you have is to specify one or more flags, which are non-numeric characters that appear just before width and precision indicators:

formatter.format("Remaining account balance: $%(,6.2f"+
"(Today's total balance:     $%(,<8.2f)", balance);

In this example, two flags are used: the parenthetical ((), and the comma indicator (,). The parenthetical indicates that negative values should be placed in parentheses, and the comma instructs the formatter to insert commas (or any other local-specific grouping separator) between digits. So, output from these instructions would look like $(8,134.28), or $(008,134.28), depending on the width specified. Table 9-3 has the complete list of valid flags.

Table 9-3. Format flags

Flag	Description
-	Indicates that the formatted value should be left-justified, based on width .
#	Indicates that the formatted output should appear in alternate form. For %o, this means a leading 0. For %x and %X, output will include a leading 0x (0X). For %s and %S, the flag is passed on to the object's formatTo( ) method.
+	Indicates that numeric output should always include a sign (+ or -).
' '	The space value (which is hard to show in a book) indicates that non-negative values should be prefixed with a space. This is generally used for alignment with negative numbers.
(	Indicates that negative numbers should appear in parentheses.
0	Indicates that numeric values should be padded on the left.
,	Indicates that the locale-specific grouping character should be used for numeric values.

NOTE

The # flag only works in conjunction with %s and %S if the argument implements java.util. Formattable.

9.2.1.6 Output

It's worth saying that with all of this talk of formatting, nothing is output until you actually use your sink:

System.out.println(sb.toString( ));

It's easy to do lots of great formatting work, and then forget to actually output the results. There are also several other ways to output formatted strings like this, covered in the following recipes.

NOTE

If you've chosen a stream as your sink, then the output occurs as you format it .