Java DateTimeFormatter (with Examples)

Introduced in Java 8 Date Time API changes, the DateTimeFormatter class helps in uniformly parsing and printing the date-time objects in various built-in and custom formatting patterns. Its instances are thread-safe and immutable; and can be used without introducing concurrency issues.

In this tutorial, we will learn to create a DateTimeFormatter instance and use predefined and custom patterns for formatting the following types:

• ZonedDateTime
• LocalDateTime
• LocalDate
• LocalTime

// Creating a DateTimeFormatter for date time information including timezone
public static final DateTimeFormatter ZDT_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss a z");

//Formatting
String formettedOutput = ZDT_FORMATTER.format( ZonedDateTime.now() ); //2023-04-26 15:28:29 pm IST

//Parsing
ZonedDateTime zdt = ZonedDateTime.parse( inputString, ZDT_FORMATTER );  //inputString is supplied by user

1. Format Patterns used with DateTimeFormatter

An instance of DateTimeFormatter is always associated with a formatting pattern, it is created with. We can either use an inbuilt pattern or we can supply a custom pattern.

1.1. Pre-built Instances

There are two ways to refer to the inbuilt patterns:

• Using prebuilt instances of DateTimeFormatter, such as ISO_DATE, ISO_LOCAL_DATE, BASIC_ISO_DATE, ISO_LOCAL_DATE_TIME, RFC_1123_DATE_TIME etc. Most instances are ISO-8601 compliant.

DateTimeFormatter.ISO_LOCAL_DATE.format(LocalDate.of(2023, 4, 25));

• Using one of the following prebuilt localized styles with FormatStyle.

DateTimeFormatter customFormatter = DateTimeFormatter.ofLocalizedDateTime( FormatStyle.LONG );

1.2. Custom Patterns

We can supply a custom pattern built with pattern characters such as ‘uuuu-MMM-dd‘ and use ofPattern() method to create a new instance.

DateTimeFormatter customFormatter = DateTimeFormatter.ofPattern("MM/dd/yyyy 'at' hh:mma z");

1.3. DateTimeFormatterBuilder for building Complex Patterns

Use  DateTimeFormatterBuilder to create a more complex formatter instance.

DateTimeFormatter formatter = new DateTimeFormatterBuilder()
                .parseCaseInsensitive()
                .append(DateTimeFormatter.ISO_LOCAL_DATE_TIME)
                .optionalStart()
                .appendPattern(".SSS")
                .optionalEnd()
                .optionalStart()
                .appendZoneOrOffsetId()
                .optionalEnd()
                .optionalStart()
                .appendOffset("+HHMM", "0000")
                .optionalEnd()
                .toFormatter();

2. Formatting with DateTimeFormatter

2.1. Syntax

The DateTimeFormatter class provides mainly one method to format a given date-time instance of TemporalAccessor type which is the base interface type for date, time and offset objects. It formats the dateTimeObject instance using the specified format.

String formattedOutput = formatter.format(TemporalAccessor temporal);

2.2. Format ZonedDateTime, LocalDateTime, LocalDate, LocalTime

We saw an example of formatting ZonedDateTime in the previous section. Let us learn to format other classes.

LocalDateTime does not have a timezone part so create the pattern accordingly.

static final DateTimeFormatter FOMATTER = DateTimeFormatter.ofPattern("MM/dd/yyyy 'at' hh:mm a");

String output = FOMATTER.format( LocalDateTime.now() );  // 07/15/2018 at 02:49 PM

LocalDate does not have time and timezone parts. So create the pattern accordingly.

static final DateTimeFormatter FOMATTER = DateTimeFormatter.ofPattern("MM/dd/yyyy");

String dateString = FOMATTER.format( LocalDate.now() );  // 07/15/2018	

LocalTime does not have the date and timezone parts so create the pattern accordingly.

static final DateTimeFormatter FOMATTER = DateTimeFormatter.ofPattern("hh:mm a");

String localTimeString = FOMATTER.format( LocalTime.now() );  // 02:53 PM	

3. Parsing with DateTimeFormatter

We can use any of the above-created DateTimeFormatter instances in parse() method to get the instance of that date/time object.

public static final DateTimeFormatter ZDT_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss a z");
ZonedDateTime zdt = ZonedDateTime.parse( str, ZDT_FORMATTER );

4. Useful Custom Patterns for Reference

The custom patterns are built using special letters that have special meanings during the formatting or parsing. Here are some common pattern symbols:

• ‘y’: year
• ‘M’: month (in number form, e.g. “1” for January)
• ‘MMM’: month abbreviation (e.g. “Jan”)
• ‘MMMM’: full month name (e.g. “January”)
• ‘d’: day of the month
• ‘E’: day of week abbreviation (e.g. “Mon”)
• ‘EEEE’: full day of week name (e.g. “Monday”)
• ‘h’: hour (in 1-12 form)
• ‘H’: hour (in 0-23 form)
• ‘m’: minute
• ‘s’: second
• ‘S’: fraction of second
• ‘a’: AM/PM marker
• ‘z’: time zone abbreviation (e.g. “PST”)
• ‘Z’: time zone offset (e.g. “-0800”)

Using the above letters, we have built the following ready-to-use custom patterns.

Happy Learning !!

Sourcecode Download