Java LocalDate withMonth Method

Introduction

The LocalDate class in Java8 provides multiple methods to manipulate date values. One such method is withMonth(), which returns a new LocalDate instance after changing or setting the month-of-year.

Skills Graph

Creating a LocalDate instance

The first step is to create a LocalDate instance in Java. The LocalDate class is found in the java.time package, so we'll include the package at the beginning of our code file. The LocalDate class provides a of() method that can create a new LocalDate instance.

import java.time.LocalDate;

public class LocalDateWithMonthMethodExample {
    public static void main(String[] args) {
        // creating a new LocalDate instance
        LocalDate date = LocalDate.of(2022, 10, 12);

        // printing the original date
        System.out.println("Original Date: " + date);
    }
}

Use the following command to compile and run the code in the terminal:

javac LocalDateWithMonthMethodExample.java && java LocalDateWithMonthMethodExample

Using the withMonth() method

The withMonth() method returns a new LocalDate instance with the month-of-year set to the value provided as an argument.

We can set a different month-of-year using the withMonth() method and get a newly created date. Here we are setting the month-of-year to 4 and getting the new date.

// setting the month-of-year to 4 and getting the new date
LocalDate newDate = date.withMonth(4);

// printing the new date
System.out.println("New Date: " + newDate);

Here's the complete code:

import java.time.LocalDate;

public class LocalDateWithMonthMethodExample {
    public static void main(String[] args) {
        // creating a new LocalDate instance
        LocalDate date = LocalDate.of(2022, 10, 12);

        // printing the original date
        System.out.println("Original Date: " + date);

        // setting the month-of-year to 4 and getting the new date
        LocalDate newDate = date.withMonth(4);

        // printing the new date
        System.out.println("New Date: " + newDate);
    }
}

Use the following command to compile and run the code in the terminal:

javac LocalDateWithMonthMethodExample.java && java LocalDateWithMonthMethodExample

You should see the following output:

Original Date: 2022-10-12
New Date: 2022-04-12

Handling invalid month values

If the month value passed into the withMonth() method is invalid, i.e., outside of the range [1, 12], it will throw a DateTimeException.

Here's an example that demonstrates how you can handle an invalid month value.

import java.time.DateTimeException;
import java.time.LocalDate;

public class LocalDateWithMonthMethodExample {
    public static void main(String[] args) {
        // creating a new LocalDate instance
        LocalDate date = LocalDate.of(2022, 10, 12);

        // printing the original date
        System.out.println("Original Date: " + date);

        try {
            // trying to set an invalid month value (13)
            LocalDate newDate = date.withMonth(13);

            // printing the new date
            System.out.println("New Date: " + newDate);
        } catch(DateTimeException ex) {
            System.out.println("Invalid month value provided: " + ex.getMessage());
        }
    }
}

Use the following command to compile and run the code in the terminal:

javac LocalDateWithMonthMethodExample.java && java LocalDateWithMonthMethodExample

You should see the following output:

Original Date: 2022-10-12
Invalid month value provided: Invalid value for MonthOfYear (valid values 1 - 12): 13

Changing the month-of-year in the original date instance

The withMonth() method returns a new LocalDate instance with the month-of-year value set to the new value, and it does not change the original date instance. If you want to change the month-of-year value in the original date, you have to assign the value returned by withMonth() back to the original date instance, like this:

// changing the month-of-year in the original date instance
date = date.withMonth(11);

// printing the updated date
System.out.println("Updated Date: " + date);

Here's the complete code:

import java.time.LocalDate;

public class LocalDateWithMonthMethodExample {
    public static void main(String[] args) {
        // creating a new LocalDate instance
        LocalDate date = LocalDate.of(2022, 10, 12);

        // printing the original date
        System.out.println("Original Date: " + date);

        // setting the month-of-year to 5 and getting the new date
        LocalDate newDate = date.withMonth(5);

        // printing the new date
        System.out.println("New Date: " + newDate);

        // changing the month-of-year in the original date instance
        date = date.withMonth(11);

        // printing the updated date
        System.out.println("Updated Date: " + date);
    }
}

Use the following command to compile and run the code in the terminal:

javac LocalDateWithMonthMethodExample.java && java LocalDateWithMonthMethodExample

You should see the following output:

Original Date: 2022-10-12
New Date: 2022-05-12
Updated Date: 2022-11-12

Handling an invalid day value

If the day-of-month is invalid for the year when changing the month, it will be changed to the last valid day of the new month. For example, if we change the month-of-year from February to April on a leap year, the day value will be automatically adjusted to the last valid day of April.

// creating a new LocalDate instance
LocalDate date = LocalDate.of(2024, 2, 29);

// printing the original date
System.out.println("Original Date: " + date);

// setting the month-of-year to April
LocalDate newDate = date.withMonth(4);

// printing the new date
System.out.println("New Date: " + newDate);

Here's the complete code:

import java.time.LocalDate;

public class LocalDateWithMonthMethodExample {
    public static void main(String[] args) {
        // creating a new LocalDate instance
        LocalDate date = LocalDate.of(2024, 2, 29);

        // printing the original date
        System.out.println("Original Date: " + date);

        // setting the month-of-year to April
        LocalDate newDate = date.withMonth(4);

        // printing the new date
        System.out.println("New Date: " + newDate);
    }
}

Use the following command to compile and run the code in the terminal:

javac LocalDateWithMonthMethodExample.java && java LocalDateWithMonthMethodExample

You should see the following output:

Original Date: 2024-02-29
New Date: 2024-04-30

Using the withMonth() method in a loop

We can use the withMonth() method in a loop to generate a list of dates with different month-of-year values. Here's an example that generates dates for each month of the year 2022:

// generating dates for each month of the year 2022
for (int month = 1; month <= 12; month++) {
    LocalDate date = LocalDate.of(2022, month, 1);
    System.out.println("Date for " + date.getMonth() + ": " + date);
}

Here's the complete code:

import java.time.LocalDate;

public class LocalDateWithMonthMethodExample {
    public static void main(String[] args) {
        // generating dates for each month of the year 2022
        for (int month = 1; month <= 12; month++) {
            LocalDate date = LocalDate.of(2022, month, 1);
            System.out.println("Date for " + date.getMonth() + ": " + date);
        }
    }
}

Use the following command to compile and run the code in the terminal:

javac LocalDateWithMonthMethodExample.java && java LocalDateWithMonthMethodExample

You should see the following output:

Date for JANUARY: 2022-01-01
Date for FEBRUARY: 2022-02-01
Date for MARCH: 2022-03-01
Date for APRIL: 2022-04-01
Date for MAY: 2022-05-01
Date for JUNE: 2022-06-01
Date for JULY: 2022-07-01
Date for AUGUST: 2022-08-01
Date for SEPTEMBER: 2022-09-01
Date for OCTOBER: 2022-10-01
Date for NOVEMBER: 2022-11-01
Date for DECEMBER: 2022-12-01

Using the getMonthValue() method

The getMonthValue() method is used to get the month-of-year value of a date. Here's an example that demonstrates how to use the withMonth() and getMonthValue() methods to change and get the month-of-year value of a date:

// creating a new LocalDate instance
LocalDate date = LocalDate.of(2022, 11, 15);

// printing the original date
System.out.println("Original Date: " + date);

// getting the month-of-year value
int originalMonthValue = date.getMonthValue();

// changing the month-of-year to 10
date = date.withMonth(10);

// getting the new month-of-year value
int newMonthValue = date.getMonthValue();

// printing the updated date and month values
System.out.println("Updated Date: " + date);
System.out.println("Original Month Value: " + originalMonthValue);
System.out.println("New Month Value: " + newMonthValue);

Here's the complete code:

import java.time.LocalDate;

public class LocalDateWithMonthMethodExample {
    public static void main(String[] args) {
        // creating a new LocalDate instance
        LocalDate date = LocalDate.of(2022, 11, 15);

        // printing the original date
        System.out.println("Original Date: " + date);

        // getting the month-of-year value
        int originalMonthValue = date.getMonthValue();

        // changing the month-of-year to 10
        date = date.withMonth(10);

        // getting the new month-of-year value
        int newMonthValue = date.getMonthValue();

        // printing the updated date and month values
        System.out.println("Updated Date: " + date);
        System.out.println("Original Month Value: " + originalMonthValue);
        System.out.println("New Month Value: " + newMonthValue);
    }
}

Use the following command to compile and run the code in the terminal:

javac LocalDateWithMonthMethodExample.java && java LocalDateWithMonthMethodExample

You should see the following output:

Original Date: 2022-11-15
Updated Date: 2022-10-15
Original Month Value: 11
New Month Value: 10

Summary

In this lab, you learned how to use the withMonth() method to create a copy of a LocalDate instance with the month-of-year set to a new value. You also learned how to handle invalid month values and how to use the getMonthValue() method to get the month-of-year value of a LocalDate instance. The withMonth() method is a useful tool for manipulating dates and can be used in many different ways, including generating a list of dates for each month of the year.