java.lang.Object | |||
↳ | java.text.Format | ||
↳ | java.text.DateFormat | ||
↳ | java.text.SimpleDateFormat |
A concrete class for formatting and parsing dates in a locale-sensitive
manner. Formatting turns a Date
into a String
, and parsing turns a
String
into a Date
.
You can supply a pattern describing what strings are produced/accepted, but almost all
callers should use getDateInstance()
, getDateTimeInstance()
,
or getTimeInstance()
to get a ready-made instance suitable for the user's
locale.
The main reason you'd create an instance this class directly is because you need to
format/parse a specific machine-readable format, in which case you almost certainly want
to explicitly ask for US
to ensure that you get ASCII digits (rather than,
say, Arabic digits).
(See "Be wary of the default locale".)
The most useful non-localized pattern is "yyyy-MM-dd HH:mm:ss.SSSZ"
, which corresponds
to the ISO 8601 international standard date format.
To specify the time format, use a time pattern string. In this
string, any character from 'A'
to 'Z'
or 'a'
to 'z'
is
treated specially. All other characters are passed through verbatim. The interpretation of each
of the ASCII letters is given in the table below. ASCII letters not appearing in the table are
reserved for future use, and it is an error to attempt to use them.
Symbol | Meaning | Presentation | Example |
D | day in year | (Number) | 189 |
E | day of week | (Text) | Tuesday |
F | day of week in month | (Number) | 2 (2nd Wed in July) |
G | era designator | (Text) | AD |
H | hour in day (0-23) | (Number) | 0 |
K | hour in am/pm (0-11) | (Number) | 0 |
L | stand-alone month | (Text/Number) | July / 07 |
M | month in year | (Text/Number) | July / 07 |
S | fractional seconds | (Number) | 978 |
W | week in month | (Number) | 2 |
Z | time zone (RFC 822) | (Timezone) | -0800 |
a | am/pm marker | (Text) | PM |
c | stand-alone day of week | (Text/Number) | Tuesday / 2 |
d | day in month | (Number) | 10 |
h | hour in am/pm (1-12) | (Number) | 12 |
k | hour in day (1-24) | (Number) | 24 |
m | minute in hour | (Number) | 30 |
s | second in minute | (Number) | 55 |
w | week in year | (Number) | 27 |
y | year | (Number) | 2010 |
z | time zone | (Timezone) | Pacific Standard Time |
' | escape for text | (Delimiter) | 'Date=' |
'' | single quote | (Literal) | 'o''clock' |
The number of consecutive copies (the "count") of a pattern character further influences the format.
zzzz
might give Pacific Standard Time
whereas z
might give PST
. Note that the count does not specify the
exact width of the field.
Years are handled specially: yy
truncates to the last 2 digits, but any
other number of consecutive y
s does not truncate. So where yyyy
or
y
might give 2010
, yy
would give 10
.
Fractional seconds are also handled specially: they're zero-padded on the right.
MM
might give 07
while MMM
gives July
.
The two pattern characters L
and c
are ICU-compatible extensions, not
available in the RI. These are necessary for correct localization in languages such as Russian
that distinguish between, say, "June" and "June 2010".
When numeric fields are adjacent directly, with no intervening delimiter characters, they constitute a run of adjacent numeric fields. Such runs are parsed specially. For example, the format "HHmmss" parses the input text "123456" to 12:34:56, parses the input text "12345" to 1:23:45, and fails to parse "1234". In other words, the leftmost field of the run is flexible, while the others keep a fixed width. If the parse fails anywhere in the run, then the leftmost field is shortened by one character, and the entire run is parsed again. This is repeated until either the parse succeeds or the leftmost field is one character in length. If the parse still fails at that point, the parse of the run fails.
See set2DigitYearStart(Date)
for more about handling two-digit years.
If you're formatting for human use, you should use an instance returned from
DateFormat
as described above. This code:
DateFormat[] formats = new DateFormat[] { DateFormat.getDateInstance(), DateFormat.getDateTimeInstance(), DateFormat.getTimeInstance(), }; for (DateFormat df : formats) { System.err.println(df.format(new Date(0))); }
Produces this output when run on an en_US
device in the PDT time zone:
Dec 31, 1969 Dec 31, 1969 4:00:00 PM 4:00:00 PMAnd will produce similarly appropriate localized human-readable output on any user's system.
If you're formatting for machine use, consider this code:
String[] formats = new String[] { "yyyy-MM-dd", "yyyy-MM-dd HH:mm", "yyyy-MM-dd HH:mmZ", "yyyy-MM-dd HH:mm:ss.SSSZ", "yyyy-MM-dd'T'HH:mm:ss.SSSZ", }; for (String format : formats) { SimpleDateFormat sdf = new SimpleDateFormat(format, Locale.US); System.err.format("%30s %s\n", format, sdf.format(new Date(0))); sdf.setTimeZone(TimeZone.getTimeZone("UTC")); System.err.format("%30s %s\n", format, sdf.format(new Date(0))); }
Which produces this output when run in the PDT time zone:
yyyy-MM-dd 1969-12-31 yyyy-MM-dd 1970-01-01 yyyy-MM-dd HH:mm 1969-12-31 16:00 yyyy-MM-dd HH:mm 1970-01-01 00:00 yyyy-MM-dd HH:mmZ 1969-12-31 16:00-0800 yyyy-MM-dd HH:mmZ 1970-01-01 00:00+0000 yyyy-MM-dd HH:mm:ss.SSSZ 1969-12-31 16:00:00.000-0800 yyyy-MM-dd HH:mm:ss.SSSZ 1970-01-01 00:00:00.000+0000 yyyy-MM-dd'T'HH:mm:ss.SSSZ 1969-12-31T16:00:00.000-0800 yyyy-MM-dd'T'HH:mm:ss.SSSZ 1970-01-01T00:00:00.000+0000
As this example shows, each SimpleDateFormat
instance has a TimeZone
.
This is because it's called upon to format instances of Date
, which represents an
absolute time in UTC. That is, Date
does not carry time zone information.
By default, SimpleDateFormat
will use the system's default time zone. This is
appropriate for human-readable output (for which, see the previous sample instead), but
generally inappropriate for machine-readable output, where ambiguity is a problem. Note that
in this example, the output that included a time but no time zone cannot be parsed back into
the original Date
. For this
reason it is almost always necessary and desirable to include the timezone in the output.
It may also be desirable to set the formatter's time zone to UTC (to ease comparison, or to
make logs more readable, for example).
SimpleDateFormat
is not thread-safe. Users should create a separate instance for
each thread.
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.text.DateFormat
|
[Expand]
Inherited Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.text.DateFormat
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a new
SimpleDateFormat for formatting and parsing
dates and times in the SHORT style for the user's default locale. | |||||||||||
Constructs a new
SimpleDateFormat using the specified
non-localized pattern and the DateFormatSymbols and Calendar for the user's default locale. | |||||||||||
Constructs a new
SimpleDateFormat using the specified
non-localized pattern and DateFormatSymbols and the Calendar for the user's default locale. | |||||||||||
Constructs a new
SimpleDateFormat using the specified
non-localized pattern and the DateFormatSymbols and Calendar for the specified locale. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Changes the pattern of this simple date format to the specified pattern
which uses localized pattern characters.
| |||||||||||
Changes the pattern of this simple date format to the specified pattern
which uses non-localized pattern characters.
| |||||||||||
Returns a new
SimpleDateFormat with the same pattern and
properties as this simple date format. | |||||||||||
Compares the specified object with this simple date format and indicates
if they are equal.
| |||||||||||
Formats the specified date as a string using the pattern of this date
format and appends the string to the specified string buffer.
| |||||||||||
Formats the specified object using the rules of this simple date format
and returns an
AttributedCharacterIterator with the formatted
date and attributes. | |||||||||||
Returns the date which is the start of the one hundred year period for two-digit year values.
| |||||||||||
Returns the
DateFormatSymbols used by this simple date format. | |||||||||||
Returns an integer hash code for this object.
| |||||||||||
Parses a date from the specified string starting at the index specified
by
position . | |||||||||||
Sets the date which is the start of the one hundred year period for two-digit year values.
| |||||||||||
Sets the
DateFormatSymbols used by this simple date format. | |||||||||||
Returns the pattern of this simple date format using localized pattern
characters.
| |||||||||||
Returns the pattern of this simple date format using non-localized
pattern characters.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class java.text.DateFormat
| |||||||||||
From class java.text.Format
| |||||||||||
From class java.lang.Object
|
Constructs a new SimpleDateFormat
for formatting and parsing
dates and times in the SHORT
style for the user's default locale.
See "Be wary of the default locale".
Constructs a new SimpleDateFormat
using the specified
non-localized pattern and the DateFormatSymbols
and Calendar
for the user's default locale.
See "Be wary of the default locale".
pattern | the pattern. |
---|
NullPointerException | if the pattern is null . |
---|---|
IllegalArgumentException | if pattern is not considered to be usable by this
formatter.
|
Constructs a new SimpleDateFormat
using the specified
non-localized pattern and DateFormatSymbols
and the Calendar
for the user's default locale.
See "Be wary of the default locale".
template | the pattern. |
---|---|
value | the DateFormatSymbols. |
NullPointerException | if the pattern is null . |
---|---|
IllegalArgumentException | if the pattern is invalid. |
Constructs a new SimpleDateFormat
using the specified
non-localized pattern and the DateFormatSymbols
and Calendar
for the specified locale.
template | the pattern. |
---|---|
locale | the locale. |
NullPointerException | if the pattern is null . |
---|---|
IllegalArgumentException | if the pattern is invalid. |
Changes the pattern of this simple date format to the specified pattern which uses localized pattern characters.
template | the localized pattern. |
---|
Changes the pattern of this simple date format to the specified pattern which uses non-localized pattern characters.
template | the non-localized pattern. |
---|
NullPointerException | if the pattern is null . |
---|---|
IllegalArgumentException | if the pattern is invalid. |
Returns a new SimpleDateFormat
with the same pattern and
properties as this simple date format.
Compares the specified object with this simple date format and indicates
if they are equal. In order to be equal, object
must be an
instance of SimpleDateFormat
and have the same DateFormat
properties, pattern, DateFormatSymbols
and creation year.
object | the object to compare with this object. |
---|
true
if the specified object is equal to this simple date
format; false
otherwise.Formats the specified date as a string using the pattern of this date format and appends the string to the specified string buffer.
If the field
member of field
contains a value specifying
a format field, then its beginIndex
and endIndex
members
will be updated with the position of the first occurrence of this field
in the formatted text.
date | the date to format. |
---|---|
buffer | the target string buffer to append the formatted date/time to. |
fieldPos | on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text. |
IllegalArgumentException | if there are invalid characters in the pattern. |
---|
Formats the specified object using the rules of this simple date format
and returns an AttributedCharacterIterator
with the formatted
date and attributes.
object | the object to format. |
---|
AttributedCharacterIterator
with the formatted date
and attributes.NullPointerException | if the object is null . |
---|---|
IllegalArgumentException | if the object cannot be formatted by this simple date format. |
Returns the date which is the start of the one hundred year period for two-digit year values.
See set2DigitYearStart(Date)
for details.
Returns the DateFormatSymbols
used by this simple date format.
DateFormatSymbols
object.
Returns an integer hash code for this object. By contract, any two
objects for which equals(Object)
returns true
must return
the same hash code value. This means that subclasses of Object
usually override both methods or neither method.
Note that hash values must not change over time unless information used in equals comparisons also changes.
See Writing a correct hashCode
method
if you intend implementing your own hashCode
method.
Parses a date from the specified string starting at the index specified
by position
. If the string is successfully parsed then the index
of the ParsePosition
is updated to the index following the parsed
text. On error, the index is unchanged and the error index of ParsePosition
is set to the index where the error occurred.
string | the string to parse using the pattern of this simple date format. |
---|---|
position | input/output parameter, specifies the start index in string from where to start parsing. If parsing is successful,
it is updated with the index following the parsed text; on
error, the index is unchanged and the error index is set to
the index where the error occurred. |
null
if there is an
error.IllegalArgumentException | if there are invalid characters in the pattern. |
---|
Sets the date which is the start of the one hundred year period for two-digit year values.
When parsing a date string using the abbreviated year pattern yy
, SimpleDateFormat
must interpret the abbreviated year relative to some
century. It does this by adjusting dates to be within 80 years before and 20
years after the time the SimpleDateFormat
instance was created. For
example, using a pattern of MM/dd/yy
, an
instance created on Jan 1, 1997 would interpret the string "01/11/12"
as Jan 11, 2012 but interpret the string "05/04/64"
as May 4, 1964.
During parsing, only strings consisting of exactly two digits, as
defined by isDigit(char)
, will be parsed into the
default century. Any other numeric string, such as a one digit string, a
three or more digit string, or a two digit string that isn't all digits (for
example, "-1"
), is interpreted literally. So using the same pattern, both
"01/02/3"
and "01/02/003"
are parsed as Jan 2, 3 AD.
Similarly, "01/02/-3"
is parsed as Jan 2, 4 BC.
If the year pattern does not have exactly two 'y' characters, the year is
interpreted literally, regardless of the number of digits. So using the
pattern MM/dd/yyyy
, "01/11/12"
is parsed as Jan 11, 12 A.D.
Sets the DateFormatSymbols
used by this simple date format.
value | the new DateFormatSymbols object.
|
---|
Returns the pattern of this simple date format using localized pattern characters.
Returns the pattern of this simple date format using non-localized pattern characters.