public class SimpleDateFormat extends DateFormat
SimpleDateFormatis a concrete class for formatting and parsing dates in a locale-sensitive manner. It allows for formatting (date → text), parsing (text → 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
of these class methods can return a date/time formatter initialized
with a default format pattern. You may modify the format pattern
applyPattern methods as desired.
For more information on using these methods, see
Date and time formats are specified by date and time pattern
Within date and time pattern strings, unquoted letters from
'Z' and from
'z' are interpreted as pattern letters representing the
components of a date or time string.
Text can be quoted using single quotes (
') to avoid
"''" 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
The following pattern letters are defined (all other characters from
'Z' and from
'z' are reserved):
Pattern letters are usually repeated, as their number determines the exact presentation:
Letter Date or Time Component Presentation Examples
Era designator Text
Week year Year
Month in year (context sensitive) Month
Month in year (standalone form) Month
Week in year Number
Week in month Number
Day in year Number
Day in month Number
Day of week in month Number
Day name in week Text
Day number of week (1 = Monday, ..., 7 = Sunday) Number
Am/pm marker Text
Hour in day (0-23) Number
Hour in day (1-24) Number
Hour in am/pm (0-11) Number
Hour in am/pm (1-12) Number
Minute in hour Number
Second in minute Number
Time zone General time zone
Pacific Standard Time;
Time zone RFC 822 time zone
Time zone ISO 8601 time zone
Calendaris the Gregorian calendar, the following rules are applied.
SimpleDateFormatmust 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
SimpleDateFormatinstance is created. For example, using a pattern of "MM/dd/yy" and a
SimpleDateFormatinstance 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
Character.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.
'Y'is specified and the calendar doesn't support any week years, the calendar year (
'y') is used instead. The support of week years can be tested with a call to
DateFormatSymbolshas been set explicitly with constructor
SimpleDateFormat(String, DateFormatSymbols)or method
setDateFormatSymbols(DateFormatSymbols), the month names given by the
GMTOffsetTimeZone:Hours must be between 0 and 23, and Minutes must be between 00 and 59. The format is locale independent and digits must be taken from the Basic Latin block of the Unicode standard.
:Minutes Sign: one of
+ -Hours: Digit Digit Digit Minutes: Digit Digit Digit: one of
0 1 2 3 4 5 6 7 8 9
For parsing, RFC 822 time zones are also
RFC822TimeZone: Sign TwoDigitHours Minutes TwoDigitHours: Digit DigitTwoDigitHours must be between 00 and 23. Other definitions are as for general time zones.
For parsing, general time zones are also accepted.
ISO8601TimeZone: OneLetterISO8601TimeZone TwoLetterISO8601TimeZone ThreeLetterISO8601TimeZone OneLetterISO8601TimeZone: Sign TwoDigitHoursOther definitions are as for general time zones or RFC 822 time zones.
ZTwoLetterISO8601TimeZone: Sign TwoDigitHours Minutes
ZThreeLetterISO8601TimeZone: Sign TwoDigitHours
For formatting, if the offset value from GMT is 0,
produced. If the number of pattern letters is 1, any fraction of an hour
is ignored. For example, if the pattern is
"X" and the time zone is
"+05" is produced.
"Z" is parsed as the UTC time zone designator.
General time zones are not accepted.
SimpleDateFormatalso supports localized date and time pattern strings. In these strings, the pattern letters described above may be replaced with other, locale dependent, pattern letters.
SimpleDateFormatdoes not deal with the localization of text other than the pattern letters; that's up to the client of the class.
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
"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
Date formats are not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.
AM_PM_FIELD, calendar, DATE_FIELD, DAY_OF_WEEK_FIELD, DAY_OF_WEEK_IN_MONTH_FIELD, DAY_OF_YEAR_FIELD, DEFAULT, ERA_FIELD, FULL, HOUR_OF_DAY0_FIELD, HOUR_OF_DAY1_FIELD, HOUR0_FIELD, HOUR1_FIELD, LONG, MEDIUM, MILLISECOND_FIELD, MINUTE_FIELD, MONTH_FIELD, numberFormat, SECOND_FIELD, SHORT, TIMEZONE_FIELD, WEEK_OF_MONTH_FIELD, WEEK_OF_YEAR_FIELD, YEAR_FIELD
|Constructor and Description|
|Modifier and Type||Method and Description|
Applies the given localized pattern string to this date format.
Applies the given pattern string to this date format.
Creates a copy of this
Compares the given object with this
Formats the given
Formats an Object producing an
Returns the beginning date of the 100-year period 2-digit years are interpreted as being within.
Gets a copy of the date and time format symbols of this date format.
Returns the hash code value for this
Parses text from a string to produce a
Sets the 100-year period 2-digit years will be interpreted as being in to begin on the date the user specifies.
Sets the date and time format symbols of this date format.
Returns a localized pattern string describing this date format.
Returns a pattern string describing this date format.
format, format, getAvailableLocales, getCalendar, getDateInstance, getDateInstance, getDateInstance, getDateTimeInstance, getDateTimeInstance, getDateTimeInstance, getInstance, getNumberFormat, getTimeInstance, getTimeInstance, getTimeInstance, getTimeZone, isLenient, parse, parseObject, setCalendar, setLenient, setNumberFormat, setTimeZone
public SimpleDateFormat(String pattern)
SimpleDateFormatusing the given pattern and the default date format symbols for the default
FORMATlocale. Note: This constructor may not support all locales. For full coverage, use the factory methods in the
This is equivalent to calling
SimpleDateFormatusing the given pattern and the default date format symbols for the given locale. Note: This constructor may not support all locales. For full coverage, use the factory methods in the
public SimpleDateFormat(String pattern, DateFormatSymbols formatSymbols)
SimpleDateFormatusing the given pattern and date format symbols.
public void set2DigitYearStart(Date startDate)
startDate- During parsing, two digit years will be placed in the range
startDate + 100 years.
public Date get2DigitYearStart()
public StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition pos)
Dateinto a date/time string and appends the result to the given
date- the date-time value to be formatted into a date-time string.
toAppendTo- where the new date-time text is to be appended.
pos- the formatting position. On input: an alignment field, if desired. On output: the offsets of the alignment field.
NullPointerException- if the given
public AttributedCharacterIterator formatToCharacterIterator(Object obj)
AttributedCharacterIterator. You can use the returned
AttributedCharacterIteratorto build the resulting String, as well as to determine information about the resulting String.
Each attribute key of the AttributedCharacterIterator will be of type
DateFormat.Field, with the corresponding attribute value
being the same as the attribute key.
obj- The object to format
NullPointerException- if obj is null.
IllegalArgumentException- if the Format cannot format the given object, or if the Format's pattern string is invalid.
public Date parse(String text, ParsePosition pos)
The method attempts to parse text starting at the index given by
If parsing succeeds, then the index of
pos is updated
to the index after the last character used (parsing does not necessarily
use all characters up to the end of the string), and the parsed
date is returned. The updated
pos can be used to
indicate the starting point for the next call to this method.
If an error occurs, then the index of
pos is not
changed, the error index of
pos is set to the index of
the character where the error occurred, and null is returned.
This parsing operation uses the
calendar to produce a
Date. All of the
calendar's date-time fields are cleared before parsing, and the
values of the date-time fields are used for any missing
date-time information. For example, the year value of the
Date is 1970 with
no year value is given from the parsing operation. The
TimeZone value may be overwritten, depending on the given
pattern and the time zone value in
TimeZone value that has previously been set by a call to
setTimeZone may need
to be restored for further operations.
String, part of which should be parsed.
ParsePositionobject with index and error index information as described above.
Dateparsed from the string. In case of error, returns null.
public String toPattern()
public String toLocalizedPattern()
public void applyPattern(String pattern)
public void applyLocalizedPattern(String pattern)
public DateFormatSymbols getDateFormatSymbols()
public void setDateFormatSymbols(DateFormatSymbols newFormatSymbols)
public Object clone()
SimpleDateFormat. This also clones the format's date format symbols.
public int hashCode()
public boolean equals(Object obj)
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2023, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.