This is correct and informative, but it might provide more detail than the reader really needs to see, or more
than you have room to show. Using a formatter you can control the format of the converted text, such as
restricting the value to only three decimal places, or padding the converted string with spaces so that it
occupies a minimum width regardless of the actual value being converted. All of these operations are possible
starting from the result of toString, but it is much easier to have a formatter do it for you.
The primary method of a Formatter object is the format method. In its simplest form it takes a format
string followed by a sequence of arguments, which are the objects and values you want to format. For
convenience the PrintStream and PrintWriter classes provide a printf method (for "print
formatted") that takes the same arguments as format and passes them through to an associated Formatter
instance. We use the System.out.printf method to demonstrate how format strings are used.
The format string contains normal text together with format specifiers that tell the formatter how you want the
following values to be formatted. For example, you can print the value of Math.PI to three decimal places
using
System.out.printf("The value of Math.PI is %.3f %n", Math.PI);
which prints
The value of Math.PI is 3.142
A format specifier starts with a % character and ends with a character that indicates the type of conversion to
perform. In the example above, the f conversion means that the argument is expected to be a floating-point
value and that it should be formatted in the normal decimal format. In contrast, an e conversion is a
floating-point conversion that produces output in scientific notation (such as 3.142e+00). Other
conversions include 'd for integers in decimal format, x for integers in hexadecimal, and s for strings or
general object conversions. Conversion indicators that can produce non-digit text are defined in both a
lowercase and uppercase form, such as e and E, where the uppercase form indicates that all text in the output
will be converted to uppercase (as if the resulting String had toUpperCase invoked on it).
In addition to the conversion indicator, a format specifier can contain other values that control the layout of
the converted value. In the example above the ".3" is a precision indicator, which for a floating-point
decimal conversion indicates how many decimal places should appear in the result, with the value rounded up
or down as appropriate. You can also control the width of the output text, ensuring that different formatted
elements line up correctly (such as for printing data in a tabular form) regardless of the actual value being
formatted. There are also flags that can be specified to control things like the justification (left or right) and
the padding character to use to maintain the minimum width. The exact meaning of precision, width, and flags
depends on the conversion being applied.
There are two special conversions that we quickly mention. The first is the % conversion used to output the %
character. Because the % character marks the start of a format specifier, you need a way to include a %
character that should actually appear in the output. The format specifier %% will do just that (just as the escape
character \ is used to produce the single character ). You can specify a width with this conversion to pad
the output with spaces: on the left if no flags are given, and on the right if the flag is given to request
left-justification.
The second special conversion is the line separator conversion n. A format specifier of %n (as used in the
example) outputs the platform specific line separator. The line separator string is defined by the system
property line.separator and is not necessarily a single newline character (\n)see "System Properties"
on page 663. Unlike println that outputs the line separator for you, printf and format require that you