Guide to Java LocalDate

Learn about the LocalDate class in Java, how to create its instances and other use cases such as parsing, formatting and adding duration and periods.

1. Overview

The java.time.LocalDate class, introduced in Java 8, represents a local date without time and zone information e.g. ‘2019-03-27‘. We can use the LocalDate instances when we need to represent a day without any specific time of the day – such as birthday, holiday or leaves taken by an employee.

Note that the LocalDate instances are immutable and thread-safe.

The following is the LocalDate class declaration in the JDK.

public final class LocalDate
	extends Object
	implements Temporal, TemporalAdjuster, ChronoLocalDate, Serializable
{
	//class body
}

2. Creating Instance of LocalDate

Generally, we will be creating LocalDate instances in two conditions i.e. get current date or create LocalDate with given values of the day, month and year.

2.1. Get Current Date

Use the now() to get today’s date. To get the date in another timezone, pass the ZoneId to the now() method.

LocalDate today = LocalDate.now();

//Today's date in GMT
LocalDate todayInGMT = LocalDate.now(ZoneId.of("GMT"));

2.2. Create LocalDate with Values

To create a local date for a specific day, month and year – use the various overloaded factory method of().

LocalDate today = LocalDate.of(2022, 1, 27);

LocalDate today = LocalDate.of(2022, Month.JANUARY, 27)

We can also get an instance of LocalDate using the epoch day.

LocalDate date = LocalDate.ofEpochDay(18823);

Another interesting way to get the LocalDate is using the day of the year. For example, 6th Feb 2022 is the 37th day of the year.

LocalDate date = LocalDate.ofYearDay(2022, 37);   //6th Feb 2022

3. Parse String to LocalDate

The LocalDate class has two overloaded parse() methods to convert a string to a LocalDate instance.

parse(CharSequence text)	//1

parse(CharSequence text, DateTimeFormatter formatter)	//2

• Use first method if the string contains date in ISO_LOCAL_DATE pattern i.e. yyyy-MM-dd. This is default pattern of local dates in Java.
• For any other date pattern, we need to use second method where we pass the date string as well as a formatter which represents the custom pattern if that date string.

LocalDate localDate = LocalDate.parse("2022-02-06");

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("d-MMM-yyyy");
LocalDate localDate = LocalDate.parse("6-Feb-2022", formatter);

4. Format LocalDate to String

Use LocalDate.format(DateTimeFormatter) method to format a local date to the desired string representation.

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("d-MMM-yyyy");

LocalDate today = LocalDate.now();

String dateString = today.format(formatter);	//23-Feb-2022

5. Add and Subtract to LocalDate

LocalDate provides below methods that return a new and modified LocalDate instance relative to the specified LocalDate instance.

• plusDays()
• plusWeeks()
• plusMonths()
• plusYears()
• minusDays()
• minusWeeks()
• minusMonths()
• minusYears()

LocalDate today = LocalDate.now();

//Same date 3 years later
LocalDate localDate1 = today.plusYears(3);	

//local date before 3 months
LocalDate localDate2 = today.minusMonths(3);

6. LocalDate Examples

Let’s get a better understanding of LocalDate class using some examples.

• Parse String to LocalDate
• Format LocalDate to String
• Convert LocalDate to java.util.Date
• Convert Date to LocalDate
• Convert LocalDate to java.sql.Date
• Convert LocalDate to ZonedDateTime
• Convert LocalDate to LocalDateTime

Happy Learning !!