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. It allows for formatting (date to text), parsing (text to date) and normalization.
SimpleDateFormat
allows you to start by choosing any user-defined
patterns for date-time formatting. However, you are encouraged to create a
date-time formatter with either getTimeInstance
, getDateInstance
, or getDateTimeInstance
in DateFormat
. Each
of these class methods can return a date/time formatter initialized with a
default format pattern. You may modify the format pattern using the applyPattern
methods as desired. For more information on using these
methods, see DateFormat
.
To specify the time format, use a time pattern string. In this pattern, all ASCII letters are reserved as pattern letters, which are defined as follows:
Symbol | Meaning | Presentation | Example |
---|---|---|---|
G | era designator | (Text) | AD |
y | year | (Number) | 1996 |
M | month in year | (Text & Number) | July & 07 |
d | day in month | (Number) | 10 |
h | hour in am/pm (1˜12) | (Number) | 12 |
H | hour in day (0˜23) | (Number) | 0 |
m | minute in hour | (Number) | 30 |
s | second in minute | (Number) | 55 |
S | fractional second | (Number) | 978 |
E | day of week | (Text) | Tuesday |
D | day in year | (Number) | 189 |
F | day of week in month | (Number) | 2 (2nd Wed in July) |
w | week in year | (Number) | 27 |
W | week in month | (Number) | 2 |
a | am/pm marker | (Text) | PM |
k | hour in day (1˜24) | (Number) | 24 |
K | hour in am/pm (0˜11) | (Number) | 0 |
z | time zone | (Text) | Pacific Standard Time |
Z | time zone (RFC 822) | (Number) | -0800 |
v | time zone (generic) | (Text) | Pacific Time |
V | time zone (location) | (Text) | United States (Los Angeles) |
' | escape for text | (Delimiter) | 'Date=' |
'' | single quote | (Literal) | 'o''clock' |
The count of pattern letters determines the format:
(Text): 4 or more pattern letters → use the full form, less than 4 pattern letters → use a short or abbreviated form if one exists.
(Number): the minimum number of digits. Shorter numbers are zero-padded to this amount. Year is handled specially; that is, if the count of 'y' is 2, the year will be truncated to 2 digits. (if "yyyy" produces "1997", "yy" produces "97".) Unlike other fields, fractional seconds are padded on the right with zero.
(Text & Number): 3 or over, use text, otherwise use number.
Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting time text even they are not embraced within single quotes.
A pattern containing any invalid pattern letter will result in an exception thrown during formatting or parsing.
Format Pattern Result -------------- ------- "yyyy.MM.dd G 'at' HH:mm:ss vvvv" → 1996.07.10 AD at 15:08:56 Pacific Time "EEE, MMM d, ''yy" → Wed, July 10, '96 "h:mm a" → 12:08 PM "hh 'o''clock' a, zzzz" → 12 o'clock PM, Pacific Daylight Time "K:mm a, vvv" → 0:00 PM, PT "yyyyy.MMMMM.dd GGG hh:mm aaa" → 01996.July.10 AD 12:08 PM
SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, "PST"); pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000); pdt.setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000); // Format the current time. SimpleDateFormat formatter = new SimpleDateFormat( "yyyy.MM.dd G 'at' hh:mm:ss a zzz"); Date currentTime_1 = new Date(); String dateString = formatter.format(currentTime_1); // Parse the previous string back into a Date. ParsePosition pos = new ParsePosition(0); Date currentTime_2 = formatter.parse(dateString, pos);
In the example, the time value currentTime_2
obtained from parsing
will be equal to currentTime_1
. However, they may not be equal if the
am/pm marker 'a' is left out from the format pattern while the
"hour in am/pm" pattern symbol is used. This information loss can happen when
formatting the time in PM.
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 is created. For
example, using a pattern of "MM/dd/yy" and a SimpleDateFormat
instance created on Jan 1, 1997, the string "01/11/12" would be interpreted
as Jan 11, 2012 while the string "05/04/64" would be interpreted 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 "01/02/3" or "01/02/003" are
parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "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" parses to Jan 11, 12 A.D.
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.
For time zones that have no names, use the strings "GMT+hours:minutes" or "GMT-hours:minutes".
The calendar defines the first day of the week, the first week of the year, whether hours are zero based or not (0 vs. 12 or 24) and the time zone. There is one common decimal format to handle all the numbers; the digit count is handled programmatically according to the pattern.
[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 default locale. | |||||||||||
Constructs a new
SimpleDateFormat using the specified
non-localized pattern and the DateFormatSymbols and Calendar for the default locale. | |||||||||||
Constructs a new
SimpleDateFormat using the specified
non-localized pattern and DateFormatSymbols and the Calendar for the 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. | |||||||||||
Answers the Date which is the start of the one hundred year period for
two digits 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
digits 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 default locale.
Constructs a new SimpleDateFormat
using the specified
non-localized pattern and the DateFormatSymbols
and Calendar
for 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 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. |
Answers the Date which is the start of the one hundred year period for two digits year values.
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.
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 digits year values.
date | the new date. |
---|
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.