Java: Format Dates with DateTimeFormatter

Introduction

Java provides an extensive API for handling date and time. In this article, we'll use Java's DateTimeFormatter to format dates - LocalDate, LocalDatetime, LocalTime and ZonedDateTime.

Before formatting dates, you'll have to know How to Get the Current Date and Time in Java.

Format Specifiers

Date and time format specifiers are used for constructing patterns to represent data in a format we'd like to present it in.

In the real world, some date or time components are often represented in more than one way. When it comes to time and date format specifiers in Java, those components have two or more representations too - sometimes it is handy to use a short version, while longer versions are more concise and official.

DateTimeFormatter

Java 8 overhauled the Date/Time API with thread-safe classes that replaced the old and clunky Date and Calendar classes.

This also introduced us to the DateTimeFormatter class, as opposed to the SimpleDateFormat from the old API.

It's worth noting that LocalDate and LocalTime store information about only dates and times respectively, while a LocalDateTime holds information about both the date and time in a single object.

There are two ways of instantiating a DateTimeFormatter:

Writing a pattern:

DateTimeFormatter formatter = DateTimeFormatter
        .ofPattern("EEE, MMM dd. yyyy.");

Using a formatter:

DateTimeFormatter formatter = DateTimeFormatter.ISO_DATE_TIME;

Using a static method:

1. DateTimeFormatter.ofLocalizedDate(FormatStyle dateStyle)
2. DateTimeFormatter.ofLocalizedTime(FormatStyle timeStyle)
3. DateTimeFormatter.ofLocalizedDateTime(FormatStyle datetimeStyle)
4. DateTimeFormatter.ofLocalizedDateTime(FormatStyle dateStyle, FormatStyle timeStyle)

For example, we could set up a DateTimeFormatter with:

DateTimeFormatter formatter = DateTimeFormatter
        .ofLocalizedTime(FormatStyle.SHORT);

Note that each one of them has a mandatory argument. FormatStyle is a built-in enum that provides a few values - FULL, LONG, MEDIUM and SHORT.

How the available enum patterns look when applied to a ZonedDateTime object is shown in the following table:

Formatting LocalTime

In the following code examples, we'll show how to get some of the predefined formatters to do the job for us, as well as making our own. It takes just a few lines of code:

DateTimeFormatter formatter = DateTimeFormatter.ofLocalizedTime(FormatStyle.MEDIUM);
LocalTime time = LocalTime.now();

System.out.println(time.format(formatter));

The resulting output is:

5:17:00 AM

Yet, we should be careful when using predefined formatters. In this case, we can't use FormatStyle.LONG or FormatStyle.FULL, because they also yield some time zone information which generally is not stored in LocalTime object.

Let's see how it looks when we make our own pattern:

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("HH:mm:ss a");
LocalTime time = LocalTime.now();
System.out.println(time.format(formatter));

This outputs:

10:58:28 AM

Of course, you're free to fiddle around with the pattern.

Formatting LocalDate

All the classes supported by DateTimeFormatter have a format(DateTimeFormatter f) method, so the process of applying pattern is fairly simple:

DateTimeFormatter formatter = DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL);
LocalDate d = LocalDate.now();

System.out.println(d.format(formatter));

This piece of code yields:

Thursday, August 13, 2020

Formatting LocalDateTime

Formatting a LocalDateTime is done in the same fashion:

DateTimeFormatter formatter = DateTimeFormatter.ofLocalizedDateTime(FormatStyle.LONG, FormatStyle.MEDIUM);
LocalDateTime dateTime = LocalDateTime.now();

System.out.println(dateTime.format(formatter));

The resulting output is:

August 13, 2020, 5:29:28 AM

Custom patterns are created in the similar matter:

DateTimeFormatter formatter = DateTimeFormatter
        .ofPattern("eee, MMM dd. yyyy.\nHH:mm:ss a");
LocalDateTime dt = LocalDateTime.now();
System.out.println(dt.format(formatter));

This piece of code yields:

Tue, Aug 25. 2020.
11:05:20 AM

Formatting ZonedDateTime

This time we can casually use the predefined formatter for full output:

DateTimeFormatter formatter = DateTimeFormatter.ofLocalizedDateTime(FormatStyle.FULL);
ZonedDateTime dateTime = ZonedDateTime.now();

System.out.println(dateTime.format(formatter));

This piece of code outputs:

Thursday, August 13, 2020 at 5:32:49 AM Central European Summer Time

When it comes to creating our own patterns for ZonedDateTime, we have all the freedom to use whichever specifier we'd like:

DateTimeFormatter formatter = DateTimeFormatter
        .ofPattern("eee, MMM dd. yyyy.\nHH:mm:ss a - zzzz");
ZonedDateTime dateTime = ZonedDateTime.now();
System.out.println(dateTime.format(formatter));

This outputs:

Tue, Aug 25. 2020.
11:09:27 AM - Central European Summer Time

Formatting rules

Format specifiers for DateTimeFormatter slightly differ from the ones for SimpleDateFormat. If you're used to working with SimpleDateFormat, you'll have to adjust some habits by a tiny bit:

• Text - If less than 4 pattern characters are used, component is presented in the short form. Exactly 4 pattern characters will use full form, and exactly 5 will use the narrow form.
• Number - The number of pattern characters is the minimum number of digits. If that number is bigger than the number of digits we actually need to represent a number, then the number is prefixed with corresponding amount of zeros. c and F can only have one occurence, while d, H, h, K, k, m and s can have two occurences. Only D can be used up to three times.
• Number/Text - If 3 or more pattern characters are used, the component is presented in textual form; otherwise in number.
• Fraction - Possible character count is between 1 and 9. If less than 9 of them is stated, value is truncated with only the most significant digits being output.
• Year - If the number of pattern characters is 2, the year is truncated to 2 rightmost digits, otherwise it is interpreted as a number.
• Zone ID - If 2 pattern characters are used, zone ID is output; otherwise the exception is thrown.
• Zone name - If the pattern character is z the output is the daylight savings aware zone name. If there is insufficient information to determine whether DST applies, the name ignoring Daylight Savings time will be used. If the count of characters is 1, 2 or 3, then the short name is output; if 4 the full name is output. Five or more characters throw an exception. As for the character v, DST is ignored. If 1 pattern character is used, then the short name is output; if 4 are used, the output is full name. Any other number of characters throw an exception.

Conclusion

In this article, we've showcased how to format a LocalDate, LocalTime, LocalDateTime and ZonedDateTime using Java's DateTimeFormatter class.