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:
For the detailed syntax of date/time formatting patterns, please, consult the Java API documentation for this class (available at Java Technology website:DateFormat f = new SimpleDateFormat (pattern); return f.format (dateTime);
http://java.sun.com/
).
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
The date/time value to be formatted.
dateStyle
timeStyle
Specify two separate styles for both date and time representations respectively.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
The formatting 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:
When only one style name is specified, it will be used for both date and time."FULL;SHORT"
Examples:
dateTime.format("SHORT", "LONG")
dateTime.format("SHORT;LONG")
Specify that the date should be formatted with the predefined short pattern whereas the time with the long one. Result example:12/01/52 3:30:32pm
dateTime.format("LONG", null)
dateTime.format("LONG;")
Specify that only date should be present and formatted with the predefined long pattern. Result example:January 12, 1952
dateTime.format(null, "LONG")
dateTime.format(";LONG")
Specify that only time should be present and formatted with the predefined long pattern. Result example:3:30:32pm
dateTime.format("FULL", "FULL")
dateTime.format("FULL")
Specify that both date and time should be present and formatted with the predefined full pattern. Result example:Tuesday, January 12, 1952 AD, 3:30:42pm PST
dateTime.format("SHORT", "SHORT")
dateTime.format("SHORT")
dateTime.format()
Specify that both date and time should be present and formatted with the predefined short pattern. Result example:12/01/52 3:30pm
dateTime.format("dd.MM.yyyy HH:mm")
Specify formatting with the custom pattern. Result example:12.01.1952 15:30