Java SimpleDateFormat

Java SimpleDateFormat

The java.text.SimpleDateFormat class is used to both parse and format dates according to a formatting pattern you specify yourself.

This text explains how to use the SimpleDateFormat class to format dates.

Creating a SimpleDateFormat

You create a SimpleDateFormat instance like this:

String pattern = "yyyy-MM-dd";
SimpleDateFormat simpleDateFormat = new SimpleDateFormat(pattern);

The pattern String parameter passed to the SimpleDateFormat constructor is the pattern to use for parsing and formatting of dates. The pattern syntax is covered later in this text.

Formatting Dates

Once you have created a SimpleDateFormat instance you can format dates using its format() method. Here is an example:

String pattern = "yyyy-MM-dd";
SimpleDateFormat simpleDateFormat = new SimpleDateFormat(pattern);

String date = simpleDateFormat.format(new Date());
System.out.println(date);

The Date instance passed to the format() method is a java.util.Date instance.

The output printed from this code would be:

2012-11-03

Parsing Dates

You can parse a String into a java.util.Date instance using the parse() method of the SimpleDateFormat instance. Here is an example:

String pattern = "yyyy-MM-dd";
SimpleDateFormat simpleDateFormat = new SimpleDateFormat(pattern);

Date date = simpleDateFormat.parse("2012-12-24");

Once this code is executed, the date variable points to a Date instance representing december 24th, 2012.

Creating a SimpleDateFormat For a Specific Locale

You can create a SimpleDateFormat instance targeted at a specific Locale. Doing so will format the dates according to that Locale whenever relevant. For instance, a formatting pattern including the name of the week day will write the week day in the language of the given Locale. Here is an example:

String pattern = "EEEEE MMMMM yyyy HH:mm:ss.SSSZ";
SimpleDateFormat simpleDateFormat =
        new SimpleDateFormat(pattern, new Locale("da", "DK"));

String date = simpleDateFormat.format(new Date());
System.out.println(date);

The output printed from this code could be:

lørdag november 2012 10:38:45.156+0100

Notice how week day (lø = saturday) and month (november) is written in Danish.

Pattern Syntax

You can use the following symbols in your formatting pattern:

G	Era designator (before christ, after christ)
y	Year (e.g. 12 or 2012). Use either yy or yyyy.
M	Month in year. Number of M's determine length of format (e.g. MM, MMM or MMMMM)
d	Day in month. Number of d's determine length of format (e.g. d or dd)
h	Hour of day, 1-12 (AM / PM) (normally hh)
H	Hour of day, 0-23 (normally HH)
m	Minute in hour, 0-59 (normally mm)
s	Second in minute, 0-59 (normally ss)
S	Millisecond in second, 0-999 (normally SSS)
E	Day in week (e.g Monday, Tuesday etc.)
D	Day in year (1-366)
F	Day of week in month (e.g. 1st Thursday of December)
w	Week in year (1-53)
W	Week in month (0-5)
a	AM / PM marker
k	Hour in day (1-24, unlike HH's 0-23)
K	Hour in day, AM / PM (0-11)
z	Time Zone
'	Escape for text delimiter
'	Single quote

Characters other than these will be treated as normal text to insert into the pattern, and thus into the formatted dates.

Some characters can be used in different numbers. For instance, you can write either yy for a 2-character version of the year (e.g. 12), or you can write yyyy for a 4-character version of the year (e.g. 2012). For more information about the patterns accepted, see the JavaDoc for the SimpleDateFormat class.

Pattern Examples

Here are a few patterns examples:

Pattern	Example
dd-MM-yy	31-01-12
dd-MM-yyyy	31-01-2012
MM-dd-yyyy	01-31-2012
yyyy-MM-dd	2012-01-31
yyyy-MM-dd HH:mm:ss	2012-01-31 23:59:59
yyyy-MM-dd HH:mm:ss.SSS	2012-01-31 23:59:59.999
yyyy-MM-dd HH:mm:ss.SSSZ	2012-01-31 23:59:59.999+0100
EEEEE MMMMM yyyy HH:mm:ss.SSSZ	Saturday November 2012 10:45:42.720+0100

DateFormatSymbols

It is possible to customize the date symbols used in the formatted output, for a specific Locale. You do so using a java.text.DateFormatSymbols instance. Here is an example:

Locale locale = new Locale("en", "UK");
DateFormatSymbols dateFormatSymbols = new DateFormatSymbols(locale);
dateFormatSymbols.setWeekdays(new String[]{
        "Unused",
        "Sad Sunday",
        "Manic Monday",
        "Thriving Tuesday",
        "Wet Wednesday",
        "Total Thursday",
        "Fat Friday",
        "Super Saturday",
});

String pattern = "EEEEE MMMMM yyyy";
SimpleDateFormat simpleDateFormat =
        new SimpleDateFormat(pattern, dateFormatSymbols);

String date = simpleDateFormat.format(new Date());
System.out.println(date);

First a new DateFormatSymbols instance is created for the UK Locale.

Second, a new set of names for week days is set. Notice that the first string "unused" is never used. The indices in this array must start from one, to be indexable by the Calendar.SUNDAY, Calendar.MONDAY etc. constants. The Calendar.SUNDAY constant is 1, Calendar.MONDAY is 2 etc.

Third a SimpleDateFormat is created using the DateFormatSymbols, and a date is formatted with it. The output printed from this could would look like this:

Super Saturday November 2012

Notice how the custom week day name is used.

You can set more date formatting symbols on the DateFormatSymbols instance. Here are the methods you can use to set additional symbols:

dateFormatSymbols.setWeekdays();
dateFormatSymbols.setAmPmStrings();
dateFormatSymbols.setEras();
dateFormatSymbols.setLocalPatternChars();
dateFormatSymbols.setMonths();
dateFormatSymbols.setShortMonths();
dateFormatSymbols.setShortWeekdays();
dateFormatSymbols.setZoneStrings();

See the JavaDoc for the java.text.DateFormatSymbols class for more details about these methods and symbols.