Java Reference
In-Depth Information
■
Note
all outputs in this section are in the US locale unless specified otherwise.
The above text contains fixed text and formatted text. The fixed text should appear in the output literally. The
formatted text will depend on the inputs. You can convert the above text into a template as shown:
<month> <day>, <year> is <name>'s birth day.
You have replaced the text that may vary with placeholders that are enclosed in angle brackets, for example,
<month>
,
<day>
, etc. You will need four input values (month, day, year, and name) to use the above template to get
a formatted text. For example, if you supply the values for
<month>
,
<day>
,
<year>
, and
<name>
as
"January"
,
"16"
,
"1970"
, and
"John"
, respectively, the template will produce
January 16, 1970 is John's birth day.
In this example, you have just replaced the placeholders in your template with their actual values. You did not
perform any formatting for the actual values. The formatting that is provided by the
Formatter
class works in a similar
fashion. What we called a placeholder in this example is called a format specifier. What we called a template in this
example is called a format string.
A format specifier always starts with a percent sign (
%
). You can convert your template into a format string, which
can be used with the
Formatter
class as follows:
%1$tB %1$td, %1$tY is %2$s's birth day.
In this format string,
"%1$tB"
,
"%1$td"
,
"%1$tY"
, and
%2$s"
are four format specifiers, whereas
" "
,
", "
,
"is "
,
and
"'s birth day."
are fixed texts.
The following snippet of code uses the above format string to print formatted text. Note that
calendar
and
"John"
are the input values for the format string. In this case, the input value
calendar
is an instance of the
Calendar
class
that encapsulates a date.
LocalDate dob = LocalDate.of(1970, Month.JANUARY, 16);
System.out.printf("%1$tB %1$td, %1$tY is %2$s's birth day.", dob, "John");
January 16, 1970 is John's birth day.
The general syntax for a format specifier is as follows:
%<argument-index$><flags><width><.precision><conversion>
Except the
%
and
<conversion>
parts, all other parts are optional. Note that there is no space between any two
parts of a format specifier. The
%
(percent sign) denotes the start of a format specifier inside a format string. If you
want to specify
%
as the part of a fixed text inside a format string, you need to use two consecutive
%
as
%%
.
The
<argument-index$>
denotes the index of the argument that the format specifier refers to. It consists of an
integer in base-10 format followed by a
$
(dollar sign). The first argument is referred to as
1$
, the second as
2$
, and so
on. You can refer to the same argument multiple times in different format specifiers inside the same format string.
The
<flags>
denotes the format of the output. It is a set of characters. The valid values for
<flags>
depend on the
data type of the argument that the format specifier refers to.
The <
width
> denotes the minimum number of characters that need to be written to the output.
Typically, the <
.precision
> denotes the maximum number of characters to be written to the output. However,
its exact meaning varies depending on the value for
<conversion>
. It is a decimal number. It starts with a dot (
.
).
