Converts the specified date/time to a string according to the specified formatting styles or pattern.
Formatting with Styles
You can use one of the default date/time formatters based on the default locale.
Such formatters are provided by Java
(precisely, by java.text.DateFormat
class)
and referred as styles whose names should be specified
in the function parameters.
The following table shows all available styles together with their general meanings
(the exact formatting result of each style depends on the locale):
Style | Meaning | Example |
"SHORT" |
Short style pattern (completely numeric) | 12.01.52 or 3:30pm |
"MEDIUM" |
Medium style pattern (longer) | Jan 12, 1952 |
"LONG" |
Long style pattern (even longer) | January 12, 1952 or 3:30:32pm |
"FULL" |
Full style pattern (pretty completely specified) | Tuesday, April 12, 1952 AD or 3:30:42pm PST |
Formatting with Pattern
Alternatively, you can specify your own date/time formatting pattern.
The Java implementation of this function processes date/time formatting patterns using
java.text.SimpleDateFormat
class of the standard Java API. Basically, this looks as the following:
DateFormat f = new SimpleDateFormat (pattern);
return f.format (dateTime);
Here, we provide the reduced description copied from that documentation for your convenience:
Date and time formats are specified by date and time pattern strings.
Within date and time pattern strings, unquoted letters from 'A'
to 'Z'
and from 'a'
to 'z'
are interpreted
as pattern letters representing the components of a date or time string.
Text can be quoted using single quotes ('
) to avoid interpretation.
"''"
represents a single quote. All other characters are not interpreted;
they're simply copied into the output string during formatting or matched against the
input string during parsing.
The following pattern letters are defined (all other characters from
'A'
to 'Z'
and from 'a'
to 'z'
are reserved):
Letter | Component | Presentation | Examples |
G |
Era designator | Text | AD |
y |
Year | Year | 1996 ; 96 |
M |
Month in year | Month | July ; Jul ; 07 |
w |
Week in year | Number | 27 |
W |
Week in month | Number | 2 |
D
|
Day in year | Number | 189 |
d |
Day in month | Number | 10 |
F |
Day of week in month | Number | 2 |
E |
Day in week | Text | Tuesday ; Tue |
a |
Am/pm marker | Text | PM |
H |
Hour in day (0-23) | Number | 0 |
k |
Hour in day (1-24) | Number | 24 |
K |
Hour in am/pm (0-11) | Number | 0 |
h |
Hour in am/pm (1-12) | Number | 12 |
m |
Minute in hour | Number | 30 |
s |
Second in minute | Number | 55 |
S |
Millisecond | Number | 978 |
z |
Time zone | General time zone | Pacific Standard Time ; PST ; GMT-08:00 |
Z |
Time zone | RFC 822 time zone | -0800 |
Pattern letters are usually repeated, as their number determines the exact presentation:
GMTOffsetTimeZone:
GMT Sign Hours : Minutes
Sign: one of
+ -
Hours:
Digit
Digit Digit
Minutes:
Digit Digit
Digit: one of
0 1 2 3 4 5 6 7 8 9
RFC822TimeZone:
Sign TwoDigitHours Minutes
TwoDigitHours:
Digit Digit
SimpleDateFormat
also supports localized date and time pattern strings.
In these strings, the pattern letters described above may be replaced with other,
locale dependent, pattern letters.
Pattern Examples
The following examples show how date and time patterns are interpreted
in the U.S. locale. The given date and time are 2001-07-04 12:08:56 local time
in the U.S. Pacific Time time zone.
Date and Time Pattern | Result |
"yyyy.MM.dd G 'at' HH:mm:ss z" |
2001.07.04 AD at 12:08:56 PDT |
"EEE, MMM d, ''yy" |
Wed, Jul 4, '01 |
"h:mm a" |
12:08 PM |
"hh 'o''clock' a, zzzz" |
12 o'clock PM, Pacific Daylight Time |
"K:mm a, z" |
0:08 PM, PDT |
"yyyyy.MMMMM.dd GGG hh:mm aaa" |
02001.July.04 AD 12:08 PM |
"EEE, d MMM yyyy HH:mm:ss Z" |
Wed, 4 Jul 2001 12:08:56 -0700 |
"yyMMddHHmmssZ" |
010704120856-0700 |
"yyyy-MM-dd'T'HH:mm:ss.SSSZ" |
2001-07-04T12:08:56.235-0700 |
Parameters:
dateTime
dateStyle
timeStyle
When one of the style names is specified as null
,
the corresponding date or time representation will be omitted.
Note: If both styles are null
or
neither styles nor pattern are specified,
the "SHORT"
style will be used by default
for both date and time.
pattern
Note: For compatibility reasons, instead of a pattern, it is possible to specify in this parameter the date and time styles as well. The separate date and time styles can be written as a single string with semicolon (;) used as separator, for example:
"FULL;SHORT"
Examples:
dateTime.format("SHORT", "LONG")
dateTime.format("SHORT;LONG")
12/01/52 3:30:32pm
dateTime.format("LONG", null)
dateTime.format("LONG;")
January 12, 1952
dateTime.format(null, "LONG")
dateTime.format(";LONG")
3:30:32pm
dateTime.format("FULL", "FULL")
dateTime.format("FULL")
Tuesday, January 12, 1952 AD, 3:30:42pm PST
dateTime.format("SHORT", "SHORT")
dateTime.format("SHORT")
dateTime.format()
12/01/52 3:30pm
dateTime.format("dd.MM.yyyy HH:mm")
12.01.1952 15:30