1. DateTimeFormatter class

The special DateTimeFormatter class founds its way into the Date Time API. Its purpose is to make it as easy as possible for programmers to convert a date and time into the exact format that they want. And we are happy to report that Java's creators succeeded.

Using it is very easy. First, you need to create a DateTimeFormatter class and pass in a pattern that specifies how it will display the date and time:

DateTimeFormatter dtf = DateTimeFormatter.ofPattern(pattern);

Where dtf is a DateTimeFormatter variable. DateTimeFormatter.ofPattern() is a static method of the DateTimeFormatter class. And pattern is a string that specifies the pattern that will be used to display the date and time.

Examples

Code Console output
DateTimeFormatter dtf = DateTimeFormatter.ofPattern("MM-dd-yy");
String text = dtf.format( LocalDateTime.now() );
System.out.println(text);


02-22-19

In the example above, we use the ofPattern() method to create a DateTimeFormatter object based on the pattern. And in the next line, we use the format() method to convert a LocalDateTime object into a string. You see the result on the screen.

You can pass almost any object from the Date Time API to the format() method.

The static ofPattern() is also very simple: it takes a pattern as an argument and returns a DateTimeFormatter object. The most interesting part is found in the pattern.


2. Formatting pattern

The string passed in as a pattern is used as a pattern when displaying information. MM is replaced by the number of the month, dd by the day of the month, and yy by the number of the year. The case of the letters matters.

The full table for these time patterns is this:

Letter Meaning
y Year
M Month
d Day
H Hours
m Minutes
s Seconds
S Thousandths of a second
n Nanoseconds.

Not particularly difficult to remember.

But why does the pattern in the example include repeated letters MM, dd and yy? Well, this is where it gets more interesting.

General idea

The number of letters affects the length of the text. The more letters there are, the longer the text will be.

If the letter H is specified once, then 9 hours will be displayed as 9, but if the letter H is specified twice in a row, then 9 hours will be displayed as 09.

If the letter y is specified 2 times in a row, then the year is written using 2 digits. If it occurs 4 times in a row, then 4 digits are used.

If the letter M is specified 2 times in a row, then the number of the month is written. If 3 times in a row, then the name of the month (its first 3 letters) is used. If 4 times in a row, then the full name of the month is used.

Example:

Code Console output
DateTimeFormatter dtf = DateTimeFormatter.ofPattern("MMMM-dd-yyyy");
String text = dtf.format( LocalDateTime.now() );
System.out.println(text);


February-22-2019


3. Complete table of patterns

The full table is quite large and super interesting:

Pattern Variations of the pattern Example Description
y yy, yyyy 19; 2019 Year
M/L M, MM, MMM, MMMM, MMMMM 1; 01; Jan; January; J Month
d d, dd 9; 09 Day
H H, HH 2; 02 Hours
m m, mm 3; 03 Minutes
s s, ss 5; 05 Seconds
S S, SS, SSS, ... 1; 12; 123 Thousandths of a second
n n 123456789 Nanoseconds
G G, GGGG, GGGGG AD; Anno Domini; A; Era
Q/q q, qq, qqq, qqqq 3; 03; Q3; 3rd quarter Quarter
w w 13 Week of the year
W W 3 Week of the month
E EEE, EEEE, EEEEE Mon; Monday; M Day of the week
e/c e, ee, eee, eeee, eeeee 1; 01; Mon; Monday; M Day of the week
a a PM AM or PM
h h 12 12-hour clock.
V VV Europe/Helsinki Time zone
z z zzzz EET;  Eastern European Standard Time Time zone
O O OOOO GMT+2;  GMT+02:00 Time zone

By the way, this isn't actually a complete version. You can find the most complete version here.



4. Parsing time

The DateTimeFormatter class is also interesting for its ability to not only convert a date and time to a string according to a given pattern, but also to perform the reverse operation!

Parsing a string is the process of splitting it into meaningful tokens.

Here's what it looks like:

Code Console output
DateTimeFormatter dtf = DateTimeFormatter.ofPattern("MMMM-dd-yyyy");
LocalDate date = LocalDate.parse("February-23-2019", dtf);
System.out.println(date);


February-23-2019

First, we create a DateTimeFormatter object and set the pattern that is used for parsing.

Then we call the LocalDate.parse() or LocalTime.parse() or LocalDateTime.parse() method and pass in the string to be parsed along with the DateTimeFormatter object, which understands how to parse the passed text and what pattern should be used to do it.

Another example: this time we'll parse time.

Code Console output
DateTimeFormatter dtf = DateTimeFormatter.ofPattern("HH:mm:ss");
LocalTime time = LocalTime.parse("23:59:59", dtf);
System.out.println(time);


23:59:59