| java.lang.Object | |
| ↳ | java.util.Formatter |
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
Flags. The available flags are:
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
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
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:
It's also possible to format dates and times with
The best non-localized form is ISO 8601,
which you can get with
As with the other conversions, date/time conversion has an uppercase format. Replacing
This table shows the date/time conversions:
Formatter is not thread-safe.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 %"100 64 40".
Flags
,Use grouping separators for large numbers. (Decimal only.)
format("%,d", 1024);1,234
+Always show sign. (Decimal only.)
format("%+d, %+4d", 5, 5);+5, +5
A space indicates that non-negative numbers
should have a leading space. (Decimal only.)
format("x% d% 5d", 4, 4);x 4 4
(Put parentheses around negative numbers. (Decimal only.)
format("%(d, %(d, %(6d", 12, -12, -12);12, (12), (12)
-Left-justify. (Requires width.)
format("%-6dx", 5);format("%-3C, %3C", 'd', 0x65);5 x
D , E
0Pad the number with leading zeros. (Requires width.)
format("%07d, %03d", 4, 5555);0000004, 5555
#Alternate form. (Octal and hex only.)
format("%o %#o", 010, 010);format("%x %#x", 0x12, 0x12);10 01012 0x12. 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.
t and
have a single extra character describing the desired output.
String conversions
All types are acceptable arguments. Values of type Formattable have their
formatTo method invoked; all other types use toString.
sString.
format("%s %s", "hello", "Hello");hello Hello
SUppercase string.
format("%S %S", "hello", "Hello");HELLO HELLO
Character conversions
Byte, Character, Short, and Integer (and primitives that box to those types) are all acceptable
as character arguments. Any other type is an error.
cCharacter.
format("%c %c", 'd', 'E');d E
CUppercase character.
format("%C %C", 'd', 'E');D E
Integer conversions
Byte, Short, Integer, Long, and BigInteger (and primitives that box to those types) are all
acceptable as integer arguments. Any other type is an error.
dDecimal.
format("%d", 26);26
oOctal.
format("%o", 032);32
x, XHexadecimal.
format("%x %X", 0x1a, 0x1a);1a 1A
Floating-point conversions
Float, Double, and BigDecimal (and primitives that box to those types) are all acceptable as
floating-point arguments. Any other type is an error.
fDecimal floating point.
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
e, EEngineering/exponential floating point.
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
g, GDecimal or engineering, depending on the magnitude of the value.
format("%g %g", 0.123, 0.0000123);0.123000 1.23000e-05
a, AHexadecimal floating point.
format("%a", 123.456f);0x1.edd2f2p6
Boolean conversion
Accepts Boolean values. null is considered false, and instances of all other
types are considered true.
b, BBoolean.
format("%b %b", true, false);format("%B %B", true, false);format("%b", null);format("%b", "hello");true falseTRUE FALSEfalsetrue
Hash code conversion
Invokes hashCode on its argument, which may be of any type.
h, HHexadecimal hash code.
format("%h", this);format("%H", this);format("%h", null);190d11190D11null
Zero-argument conversions
%A literal % character.
format("%d%%", 50);50%
nNewline. (The value of the system property
"line.separator".)format("first%nsecond");first\nsecondFormatter, 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.
"%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).
%t with %T will uppercase the field according to the rules of the formatter's
locale.
Date/time conversions
Calendar, Date, and Long (representing milliseconds past the epoch) are all acceptable
as date/time arguments. Any other type is an error. The epoch is 1970-01-01 00:00:00 UTC.
taLocalized weekday name (abbreviated).
format("%ta", cal, cal);Tue
tALocalized weekday name (full).
format("%tA", cal, cal);Tuesday
tbLocalized month name (abbreviated).
format("%tb", cal);Apr
tBLocalized month name (full).
format("%tB", cal);April
tcLocale-preferred date and time representation. (See
DateFormat for more variations.)format("%tc", cal);Tue Apr 01 16:19:17 CEST 2008
tC2-digit century.
format("%tC", cal);20
td2-digit day of month (01-31).
format("%td", cal);01
tDAmbiguous US date format (MM/DD/YY). Do not use.
format("%tD", cal);04/01/08
teDay of month (1-31).
format("%te", cal);1
tFFull date in ISO 8601 format (YYYY-MM-DD).
format("%tF", cal);2008-04-01
thSynonym for
%tb.
tH24-hour hour of day (00-23).
format("%tH", cal);16
tI12-hour hour of day (01-12).
format("%tH", cal);04
tj3-digit day of year (001-366).
format("%tj", cal);092
tk24-hour hour of day (0-23).
format("%tH", cal);16
tl12-hour hour of day (1-12).
format("%tH", cal);4
tLMilliseconds.
format("%tL", cal);359
tm2-digit month of year (01-12).
format("%tm", cal);04
tM2-digit minute.
format("%tM", cal);08
tNNanoseconds.
format("%tN", cal);359000000
tpa.m. or p.m.
format("%tp %Tp", cal, cal);pm PM
tQMilliseconds since the epoch.
format("%tQ", cal);1207059412656
trFull 12-hour time (
%tI:%tM:%tS %Tp).format("%tr", cal);04:15:32 PM
tRShort 24-hour time (
%tH:%tM).format("%tR", cal);16:15
tsSeconds since the epoch.
format("%ts", cal);1207059412
tS2-digit seconds (00-60).
format("%tS", cal);17
tTFull 24-hour time (
%tH:%tM:%tS).format("%tT", cal);16:15:32
ty2-digit year (00-99).
format("%ty", cal);08
tY4-digit year.
format("%tY", cal);2008
tzTime zone GMT offset.
format("%tz", cal);+0100
tZLocalized time zone abbreviation.
format("%tZ", cal);CEST
| Nested Classes | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Formatter.BigDecimalLayoutForm | The enumeration giving the available styles for formatting very large decimal numbers. | ||||||||||
| Public Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a
Formatter. | |||||||||||
Constructs a
Formatter whose output will be written to the
specified Appendable. | |||||||||||
Constructs a
Formatter with the specified Locale. | |||||||||||
Constructs a
Formatter with the specified Locale
and whose output will be written to the
specified Appendable. | |||||||||||
Constructs a
Formatter whose output is written to the specified file. | |||||||||||
Constructs a
Formatter whose output is written to the specified file. | |||||||||||
Constructs a
Formatter with the given Locale and charset,
and whose output is written to the specified file. | |||||||||||
Constructs a
Formatter whose output is written to the specified File. | |||||||||||
Constructs a
Formatter with the given charset,
and whose output is written to the specified File. | |||||||||||
Constructs a
Formatter with the given Locale and charset,
and whose output is written to the specified File. | |||||||||||
Constructs a
Formatter whose output is written to the specified OutputStream. | |||||||||||
Constructs a
Formatter with the given charset,
and whose output is written to the specified OutputStream. | |||||||||||
Constructs a
Formatter with the given Locale and charset,
and whose output is written to the specified OutputStream. | |||||||||||
Constructs a
Formatter whose output is written to the specified PrintStream. | |||||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Closes the
Formatter. | |||||||||||
Flushes the
Formatter. | |||||||||||
Writes a formatted string to the output destination of the
Formatter. | |||||||||||
Writes a formatted string to the output destination of the
Formatter. | |||||||||||
Returns the last
IOException thrown by the Formatter's output
destination. | |||||||||||
Returns the
Locale of the Formatter. | |||||||||||
Returns the output destination of the
Formatter. | |||||||||||
Returns the content by calling the
toString() method of the output
destination. | |||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
From class java.lang.Object
| |||||||||||
From interface java.io.Closeable
| |||||||||||
From interface java.io.Flushable
| |||||||||||
Constructs a Formatter.
The output is written to a StringBuilder which can be acquired by invoking
out() and whose content can be obtained by calling
toString().
The Locale for the Formatter is the default Locale.
Constructs a Formatter whose output will be written to the
specified Appendable.
The locale for the Formatter is the default Locale.
| a | the output destination of the Formatter. If a is null,
then a StringBuilder will be used.
|
|---|
Constructs a Formatter with the specified Locale.
The output is written to a StringBuilder which can be acquired by invoking
out() and whose content can be obtained by calling
toString().
| l | the Locale of the Formatter. If l is null,
then no localization will be used.
|
|---|
Constructs a Formatter with the specified Locale
and whose output will be written to the
specified Appendable.
| a | the output destination of the Formatter. If a is null,
then a StringBuilder will be used. |
|---|---|
| l | the Locale of the Formatter. If l is null,
then no localization will be used.
|
Constructs a Formatter whose output is written to the specified file.
The charset of the Formatter is the default charset.
The Locale for the Formatter is the default Locale.
| fileName | the filename of the file that is used as the output
destination for the Formatter. The file will be truncated to
zero size if the file exists, or else a new file will be
created. The output of the Formatter is buffered. |
|---|
| FileNotFoundException | if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file. |
|---|---|
| SecurityException | if there is a SecurityManager in place which denies permission
to write to the file in checkWrite(file.getPath()).
|
Constructs a Formatter whose output is written to the specified file.
The Locale for the Formatter is the default Locale.
| fileName | the filename of the file that is used as the output
destination for the Formatter. The file will be truncated to
zero size if the file exists, or else a new file will be
created. The output of the Formatter is buffered. |
|---|---|
| csn | the name of the charset for the Formatter. |
| FileNotFoundException | if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file. |
|---|---|
| SecurityException | if there is a SecurityManager in place which denies permission
to write to the file in checkWrite(file.getPath()). |
| UnsupportedEncodingException | if the charset with the specified name is not supported. |
Constructs a Formatter with the given Locale and charset,
and whose output is written to the specified file.
| fileName | the filename of the file that is used as the output
destination for the Formatter. The file will be truncated to
zero size if the file exists, or else a new file will be
created. The output of the Formatter is buffered. |
|---|---|
| csn | the name of the charset for the Formatter. |
| l | the Locale of the Formatter. If l is null,
then no localization will be used. |
| FileNotFoundException | if the filename does not denote a normal and writable file, or if a new file cannot be created, or if any error arises when opening or creating the file. |
|---|---|
| SecurityException | if there is a SecurityManager in place which denies permission
to write to the file in checkWrite(file.getPath()). |
| UnsupportedEncodingException | if the charset with the specified name is not supported. |
Constructs a Formatter whose output is written to the specified File.
The charset of the Formatter is the default charset.
The Locale for the Formatter is the default Locale.
| file | the File that is used as the output destination for the
Formatter. The File will be truncated to zero size if the File
exists, or else a new File will be created. The output of the
Formatter is buffered. |
|---|
| FileNotFoundException | if the File is not a normal and writable File, or if a
new File cannot be created, or if any error rises when opening or
creating the File. |
|---|---|
| SecurityException | if there is a SecurityManager in place which denies permission
to write to the File in checkWrite(file.getPath()).
|
Constructs a Formatter with the given charset,
and whose output is written to the specified File.
The Locale for the Formatter is the default Locale.
| file | the File that is used as the output destination for the
Formatter. The File will be truncated to zero size if the File
exists, or else a new File will be created. The output of the
Formatter is buffered. |
|---|---|
| csn | the name of the charset for the Formatter. |
| FileNotFoundException | if the File is not a normal and writable File, or if a
new File cannot be created, or if any error rises when opening or
creating the File. |
|---|---|
| SecurityException | if there is a SecurityManager in place which denies permission
to write to the File in checkWrite(file.getPath()). |
| UnsupportedEncodingException | if the charset with the specified name is not supported. |
Constructs a Formatter with the given Locale and charset,
and whose output is written to the specified File.
| file | the File that is used as the output destination for the
Formatter. The File will be truncated to zero size if the File
exists, or else a new File will be created. The output of the
Formatter is buffered. |
|---|---|
| csn | the name of the charset for the Formatter. |
| l | the Locale of the Formatter. If l is null,
then no localization will be used. |
| FileNotFoundException | if the File is not a normal and writable File, or if a
new File cannot be created, or if any error rises when opening or
creating the File. |
|---|---|
| SecurityException | if there is a SecurityManager in place which denies permission
to write to the File in checkWrite(file.getPath()). |
| UnsupportedEncodingException | if the charset with the specified name is not supported. |
Constructs a Formatter whose output is written to the specified OutputStream.
The charset of the Formatter is the default charset.
The Locale for the Formatter is the default Locale.
| os | the stream to be used as the destination of the Formatter.
|
|---|
Constructs a Formatter with the given charset,
and whose output is written to the specified OutputStream.
The Locale for the Formatter is the default Locale.
| os | the stream to be used as the destination of the Formatter. |
|---|---|
| csn | the name of the charset for the Formatter. |
| UnsupportedEncodingException | if the charset with the specified name is not supported. |
|---|
Constructs a Formatter with the given Locale and charset,
and whose output is written to the specified OutputStream.
| os | the stream to be used as the destination of the Formatter. |
|---|---|
| csn | the name of the charset for the Formatter. |
| l | the Locale of the Formatter. If l is null,
then no localization will be used. |
| UnsupportedEncodingException | if the charset with the specified name is not supported. |
|---|
Constructs a Formatter whose output is written to the specified PrintStream.
The charset of the Formatter is the default charset.
The Locale for the Formatter is the default Locale.
| ps | the PrintStream used as destination of the Formatter. If
ps is null, then a NullPointerException will
be raised.
|
|---|
Closes the Formatter. If the output destination is Closeable,
then the method close() will be called on that destination.
If the Formatter has been closed, then calling the this method will have no
effect.
Any method but the ioException() that is called after the
Formatter has been closed will raise a FormatterClosedException.
Flushes the Formatter. If the output destination is Flushable,
then the method flush() will be called on that destination.
| FormatterClosedException | if the Formatter has been closed.
|
|---|
Writes a formatted string to the output destination of the Formatter.
| l | the Locale used in the method. If locale is
null, then no localization will be applied. This
parameter does not change this Formatter's default Locale
as specified during construction, and only applies for the
duration of this call. |
|---|---|
| format | a format string. |
| args | the arguments list used in the format() method. If there are
more arguments than those specified by the format string, then
the additional arguments are ignored. |
Formatter.| IllegalFormatException | if the format string is illegal or incompatible with the arguments, or if fewer arguments are sent than those required by the format string, or any other illegal situation. |
|---|---|
| FormatterClosedException | if the Formatter has been closed.
|
Writes a formatted string to the output destination of the Formatter.
| format | a format string. |
|---|---|
| args | the arguments list used in the format() method. If there are
more arguments than those specified by the format string, then
the additional arguments are ignored. |
Formatter.| IllegalFormatException | if the format string is illegal or incompatible with the arguments, or if fewer arguments are sent than those required by the format string, or any other illegal situation. |
|---|---|
| FormatterClosedException | if the Formatter has been closed.
|
Returns the last IOException thrown by the Formatter's output
destination. If the append() method of the destination does not throw
IOExceptions, the ioException() method will always return null.
IOException thrown by the Formatter's output
destination.
Returns the Locale of the Formatter.
Locale for the Formatter or null for no Locale.| FormatterClosedException | if the Formatter has been closed.
|
|---|
Returns the output destination of the Formatter.
Formatter.| FormatterClosedException | if the Formatter has been closed.
|
|---|
Returns the content by calling the toString() method of the output
destination.
toString() method of the output
destination.| FormatterClosedException | if the Formatter has been closed.
|
|---|