LocalDate Class in Java

Post author:Noel Kamphoa
Post published:May 5, 2024
Post category:Core Java Tutorials / Java Entry Level / Text, Date, Time, and Numeric Objects

1. Introduction

Java 8 introduced, through JSR 310, a complete overhaul of the Date/Time API by providing new, more advanced classes for Date processing. LocalDate is one such class that we will focus on in this article.

2. What is a LocalDate?

LocalDate is a class from the java.time package. The class represents a date in terms of date fields (year, month, day), without any time or timezone information. You should not confuse LocalDate with the legacy java.util.Date class. The LocalTime and LocalDateTime classes are covered in separate articles.

The main particularity of LocalDate is that it is immutable and thread-safe.

3. Creating a LocalDate

There are two main ways of creating a LocalDate in Java. The first way is by using the LocalDate.now() methods and the second way is with the LocalDate.of() methods.

3.1. Using `LocalDate.now()` Methods

You can create a LocalDate object with the current date in this way:

        LocalDate now = LocalDate.now();

This will query the system clock in the default timezone.
Optionally, you can provide a custom Clock to the now() method:

        Clock clock = Clock.systemDefaultZone();
        LocalDate now = LocalDate.now(clock);

It is a best practice to pass a Clock into any method that requires the current instant. This has the advantage of making your code more testable.

Furthermore, if you need to construct a date object for a specific TimeZone, you can pass a ZoneId object to the now() method:

        ZoneId zoneId = ZoneId.of("Europe/Paris");
        LocalDate now = LocalDate.now(zoneId);

3.2. Using `LocalDate.of()` Methods

You can also create a LocalDate object by providing values for the year, month, and day:

        LocalDate date = LocalDate.of(2024,5,1);//2024-05-01

Instead of sending an integer for the month, you may provide directly a Month Enum object:

        LocalDate date = LocalDate.of(2024, Month.MAY,1);//2024-05-01

All these factory methods will throw a DateTimeException if the value of any field is out of range, or if the day-of-month is invalid for the month-year.

4. Formatting a LocalDate

By default, the LocalDate is formatted using the ISO-8601 date format. You can use a different format by passing a DateTimeFormatter object to the format() method:

        LocalDate date = LocalDate.of(2024, 5,1);// 2024-05-01
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("dd/MM/yyyy");
        String formattedDate = date.format(formatter);// 01/05/2024

5. Parsing from String to LocalDate

Assuming that you have a date in ISO-8601 date format and want to build a LocalDate out of it, you can use the parse() method in this way:

        String myDate = "2024-05-01";// ISO-8601 date format
        LocalDate date = LocalDate.parse(myDate);// 2024-05-01

Moreover, if the date is in a different format, you can pass a custom DateTimeFormatter to the parse() method:

        String myDate = "01/05/2024";//Custom format
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("dd/MM/yyyy");
        LocalDate date = LocalDate.parse(myDate,formatter);// 2024-05-01

Java will throw a DateTimeParseException if it is not able to parse the String with the given date format.

6. Operating on a LocalDate

6.1. Comparing two LocalDate objects

You can use isAfter(), isBefore(), and isEqual() methods to compare two LocalDate objects:

        LocalDate firstDate = LocalDate.of(2024,5,1);
        LocalDate secondDate = LocalDate.of(2024,4,30);
        LocalDate thirdDate = LocalDate.of(2024,5,2);
        LocalDate fourthDate = LocalDate.of(2024,5,1);
        boolean test1 = firstDate.isAfter(secondDate);//true
        boolean test2 = firstDate.isBefore(thirdDate);//true
        boolean test3 = firstDate.isEqual(fourthDate);//true

Since the LocalDate class implements the Comparable<E> interface, you may also use the compareTo() method:

        LocalDate firstDate = LocalDate.of(2024,5,1);
        LocalDate secondDate = LocalDate.of(2024,4,30);
        LocalDate thirdDate = LocalDate.of(2024,5,2);
        int test1 = firstDate.compareTo(secondDate);// A positive number
        int test2 = firstDate.compareTo(thirdDate);// A negative number

Lastly, you should know that the LocalDate class also overrides the equals() method and provides a convenient way to check the equality of two dates:

        LocalDate firstDate = LocalDate.of(2024,5,1);
        LocalDate secondDate = LocalDate.of(2024,4,30);
        LocalDate thirdDate = LocalDate.of(2024,5,1);
        boolean test1 = firstDate.equals(secondDate);// false
        boolean test2 = firstDate.equals(thirdDate);// true

6.2. Temporal Arithmetic with LocalDate objects

The LocalDate class provides plusXXX() and minusXXX() methods to increment and decrement the object field values. Since the LocalDate is immutable, all these methods return a copy of the original object with the given fields updated.

        LocalDate date = LocalDate.of(2024,5,1);//2024-05-01
        LocalDate nextDay = date.plusDays(1);//2024-05-02
        LocalDate previousDay = date.minusDays(1);//2024-04-30
        LocalDate nextMonth = date.plusMonths(1);//2024-06-01
        LocalDate previousMonth = date.minusMonths(1);//2024-04-01
        LocalDate nextYear = date.plusYears(1);//2025-05-01
        LocalDate previousYear = date.minusYears(1);//2023-05-01