Formatter

Class Overview

Formats arguments according to a format string (like printf in C).

It's relatively rare to use a Formatter directly. A variety of classes offer convenience methods for accessing formatter functionality. Of these, format(String, Object...) is generally the most useful. PrintStream and PrintWriter both offer format and printf methods.

Format strings consist of plain text interspersed with format specifiers, such as "name: %s weight: %03dkg\n". Being a Java string, the usual Java string literal backslash escapes are of course available.

Format specifiers (such as "%s" or "%03d" in the example) start with a % and describe how to format their corresponding argument. It includes an optional argument index, optional flags, an optional width, an optional precision, and a mandatory conversion type. In the example, "%s" has no flags, no width, and no precision, while "%03d" has the flag 0, the width 3, and no precision.

Not all combinations of argument index, flags, width, precision, and conversion type are valid.

Argument index. Normally, each format specifier consumes the next argument to format. For convenient localization, it's possible to reorder arguments so that they appear in a different order in the output than the order in which they were supplied. For example, "%4$s" formats the fourth argument (4$) as a string (s). It's also possible to reuse an argument with <. For example, format("%o %<d %<x", 64) results in "100 64 40".

Flags. The available flags are:

+5,   +5

x 4    4

12, (12),   (12)

5      x

D  ,   E

Width. The width is a decimal integer specifying the minimum number of characters to be used to represent the argument. If the result would otherwise be shorter than the width, padding will be added (the exact details of which depend on the flags). Note that you can't use width to truncate a field, only to make it wider: see precision for control over the maximum width.

Precision. The precision is a . followed by a decimal integer, giving the minimum number of digits for d, o, x, or X; the minimum number of digits after the decimal point for a, A, e, E, f, or F; the maximum number of significant digits for g or G; or the maximum number of characters for s or S.

Conversion type. One or two characters describing how to interpret the argument. Most conversions are a single character, but date/time conversions all start with t and have a single extra character describing the desired output.

Many conversion types have a corresponding uppercase variant that converts its result to uppercase using the rules of the relevant locale (either the default or the locale set for this formatter).

This table shows the available single-character (non-date/time) conversion types:

format("%f", 123.456f);
format("%.1f", 123.456f);
format("%1.5f", 123.456f);
format("%10f", 123.456f);
format("%6.0f", 123.456f);

123.456001
123.5
123.45600
123.456001
   123

format("%e", 123.456f);
format("%.1e", 123.456f);
format("%1.5E", 123.456f);
format("%10E", 123.456f);
format("%6.0E", 123.456f);

1.234560e+02
1.2e+02
1.23456E+02
1.234560E+02
 1E+02

It's also possible to format dates and times with Formatter, though you should seriously consider using SimpleDateFormat via the factory methods in DateFormat instead. The facilities offered by Formatter are low-level and place the burden of localization on the developer. Using getDateInstance(), getTimeInstance(), and getDateTimeInstance() is preferable for dates and times that will be presented to a human. Those methods will select the best format strings for the user's locale.

The best non-localized form is ISO 8601, which you can get with "%tF" (2010-01-22), "%tF %tR" (2010-01-22 13:39), "%tF %tT" (2010-01-22 13:39:15), or "%tF %tT%z" (2010-01-22 13:39:15-0800).

As with the other conversions, date/time conversion has an uppercase format. Replacing %t with %T will uppercase the field according to the rules of the formatter's locale.

This table shows the date/time conversions:

Number localization. Some conversions use localized decimal digits rather than the usual ASCII digits. So formatting 123 with %d will give 123 in English locales but ١٢٣ in appropriate Arabic locales, for example. This number localization occurs for the decimal integer conversion %d, the floating point conversions %e, %f, and %g, and all date/time %t or %T conversions, but no other conversions.

Thread safety. Formatter is not thread-safe.

Summary

[Expand] Inherited Methods
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Called before the object's memory is reclaimed by the VM. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
From interface java.io.Closeable abstract void close() Closes the object and release any system resources it holds.
From interface java.io.Flushable abstract void flush() Flushes the object by writing out any buffered data to the underlying output.