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
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:
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 |
0
|
Pad 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 010
12 0x12
|
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:
String conversions
All types are acceptable arguments. Values of type
Formattable
have their
formatTo
method invoked; all other types use
toString
.
|
|||
s
|
String. |
format("%s %s", "hello", "Hello");
|
hello Hello
|
S
|
Uppercase 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. |
|||
c
|
Character. |
format("%c %c", 'd', 'E');
|
d E
|
C
|
Uppercase 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. |
|||
d
|
Decimal. |
format("%d", 26);
|
26
|
o
|
Octal. |
format("%o", 032);
|
32
|
x
,
X
|
Hexadecimal. |
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. |
|||
f
|
Decimal 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
,
E
|
Engineering/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
,
G
|
Decimal or engineering, depending on the magnitude of the value. |
format("%g %g", 0.123, 0.0000123);
|
0.123000 1.23000e-05
|
a
,
A
|
Hexadecimal 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
,
B
|
Boolean. |
format("%b %b", true, false);
format("%B %B", true, false);
format("%b", null);
format("%b", "hello");
|
true false
TRUE FALSE
false
true
|
Hash code conversion
Invokes
hashCode
on its argument, which may be of any type.
|
|||
h
,
H
|
Hexadecimal hash code. |
format("%h", this);
format("%H", this);
format("%h", null);
|
190d11
190D11
null
|
Zero-argument conversions | |||
%
|
A literal % character. |
format("%d%%", 50);
|
50%
|
n
|
Newline. (The value of
lineSeparator()
.)
|
format("first%nsecond");
|
first\nsecond
|
It's also possible to format dates and times with
Formatter
, though you should
use
SimpleDateFormat
(probably 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).
This table shows the date/time conversions, but you should use
SimpleDateFormat
instead:
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. Use
SimpleDateFormat
instead.
|
|||
ta
|
Localized weekday name (abbreviated). |
format("%ta", cal, cal);
|
Tue
|
tA
|
Localized weekday name (full). |
format("%tA", cal, cal);
|
Tuesday
|
tb
|
Localized month name (abbreviated). |
format("%tb", cal);
|
Apr
|
tB
|
Localized month name (full). |
format("%tB", cal);
|
April
|
tc
|
C library asctime(3) -like output. Do not use. |
format("%tc", cal);
|
Tue Apr 01 16:19:17 CEST 2008
|
tC
|
2-digit century. |
format("%tC", cal);
|
20
|
td
|
2-digit day of month (01-31). |
format("%td", cal);
|
01
|
tD
|
Ambiguous US date format (MM/DD/YY). Do not use. |
format("%tD", cal);
|
04/01/08
|
te
|
Day of month (1-31). |
format("%te", cal);
|
1
|
tF
|
Full date in ISO 8601 format (YYYY-MM-DD). |
format("%tF", cal);
|
2008-04-01
|
th
|
Synonym for
%tb
.
|
||
tH
|
2-digit 24-hour hour of day (00-23). |
format("%tH", cal);
|
16
|
tI
|
2-digit 12-hour hour of day (01-12). |
format("%tI", cal);
|
04
|
tj
|
3-digit day of year (001-366). |
format("%tj", cal);
|
092
|
tk
|
24-hour hour of day (0-23). |
format("%tk", cal);
|
16
|
tl
|
12-hour hour of day (1-12). |
format("%tl", cal);
|
4
|
tL
|
Milliseconds. |
format("%tL", cal);
|
359
|
tm
|
2-digit month of year (01-12). |
format("%tm", cal);
|
04
|
tM
|
2-digit minute. |
format("%tM", cal);
|
08
|
tN
|
Nanoseconds. |
format("%tN", cal);
|
359000000
|
tp
|
a.m. or p.m. |
format("%tp %Tp", cal, cal);
|
pm PM
|
tQ
|
Milliseconds since the epoch. |
format("%tQ", cal);
|
1207059412656
|
tr
|
Full 12-hour time (
%tI:%tM:%tS %Tp
).
|
format("%tr", cal);
|
04:15:32 PM
|
tR
|
Short 24-hour time (
%tH:%tM
).
|
format("%tR", cal);
|
16:15
|
ts
|
Seconds since the epoch. |
format("%ts", cal);
|
1207059412
|
tS
|
2-digit seconds (00-60). |
format("%tS", cal);
|
17
|
tT
|
Full 24-hour time (
%tH:%tM:%tS
).
|
format("%tT", cal);
|
16:15:32
|
ty
|
2-digit year (00-99). |
format("%ty", cal);
|
08
|
tY
|
4-digit year. |
format("%tY", cal);
|
2008
|
tz
|
Time zone GMT offset. |
format("%tz", cal);
|
+0100
|
tZ
|
Localized time zone abbreviation. |
format("%tZ", cal);
|
CEST
|
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.
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.
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
|
|||||||||||
From interface
java.lang.AutoCloseable
|
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
used is the user's default locale.
See "
Be wary of the default locale
".
Constructs a
Formatter
whose output will be written to the
specified
Appendable
.
The
Locale
used is the user's default locale.
See "
Be wary of 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
used is the user's default locale.
See "
Be wary of 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. |
---|
Constructs a
Formatter
whose output is written to the specified file.
The
Locale
used is the user's default locale.
See "
Be wary of 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. |
---|---|
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. |
---|---|
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
used is the user's default locale.
See "
Be wary of 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
.
|
---|
Constructs a
Formatter
with the given charset,
and whose output is written to the specified
File
.
The
Locale
used is the user's default locale.
See "
Be wary of 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
.
|
---|---|
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
.
|
---|---|
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
used is the user's default locale.
See "
Be wary of 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
used is the user's default locale.
See "
Be wary of 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
used is the user's default locale.
See "
Be wary of 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
.
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
.
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.
|
Returns the last
IOException
thrown by the
Formatter
's output
destination. If the
append()
method of the destination does not throw
IOException
s, 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.
|
---|