Java Period – Difference between Dates in Days, Months and Years
Learn to create and use the Period class that was introduced as part of the new Date Time API in Java 8. The Period class represents the period of time in date-based values such as days, months, years, weeks, or years in the ISO-8601 calendar system such as “1 year and 2 months”.
The supported units of a period are YEARS , MONTHS and DAYS . All three fields are always present but may be set to zero or even a negative value.
For example, we can use the instance of Period to represent the total time spent by the student to complete the university degree.
The Period class is used to represent an amount of time using date-based values in the ISO-8601 period formats PnYnMnD and PnW .
For example, the P20Y2M25D string represents 20 years, 2 months, and 25 days.
The period of time can be obtained in the following ways.
1.1. Period between Two Dates
Mostly Period is used to represent a period of time between two dates (e.g. between two LocalDate instances).
LocalDate startLocalDate = LocalDate.of(2020, 3, 12); LocalDate endLocalDate = LocalDate.of(2020, 7, 20); Period periodBetween = Period.between(startLocalDate, endLocalDate); System.out.println(periodBetween); // P4M8D - 4 months and 8 days System.out.println(periodBetween.getDays()); //8 System.out.println(periodBetween.getMonths()); //4 System.out.println(periodBetween.getYears()); //0 System.out.println(periodBetween.get(ChronoUnit.DAYS)); //81.2. Creating Period with Values
Period class following methods to represent a time period in different units:
- ofDays(int days) – period representing a number of days.
- ofMonths(int months) – period representing a number of months.
- ofWeeks(int weeks) – period representing a number of weeks.
- ofYears(int years) – period representing a number of years.
//20 years, 3 months and 20 days Period periodFromUnits = Period.of(20, 3, 20); Period fromDays = Period.ofDays(150); // 150 days Period fromMonths = Period.ofMonths(4); // 4 months Period fromYears = Period.ofYears(10); // 10 years Period fromWeeks = Period.ofWeeks(15); // 15 weeks1.3. Parse String to Period
Period can be obtained from containing ISO-8601 period formats.
//20 years, 3 months and 20 days Period periodFromString1 = Period.parse("P20Y3M20D"); //365 Days Period periodFromString2 = Period.parse("P365D"); //52 Weeks Period periodFromString3 = Period.parse("P52W");2. Extracting the values from Period
The period values can be obtained via getter methods:
- Period.getDays() – Gets the amount of days of this period.
- Period.getMonths() – Gets the amount of months of this period.
- Period.getYears() – Gets the amount of years of this period.
- Period.get(TemporalUnit unit) – Gets the value of the requested unit. Please note that supported units are YEARS, MONTHS and DAYS . All other units throw an UnsupportedTemporalTypeException .
LocalDate startLocalDate = LocalDate.of(2020, 3, 12); LocalDate endLocalDate = LocalDate.of(2020, 7, 20); Period periodBetween = Period.between(startLocalDate, endLocalDate); periodBetween.getDays(); //8 periodBetween.getMonths(); //4 periodBetween.getYears(); //0 periodBetween.get(ChronoUnit.DAYS); //8 //Throws UnsupportedTemporalTypeException periodBetween.get(ChronoUnit.WEEKS);We can add or subtract the time or another period from the given Period instance.
Note that Period is an immutable class so each method, listed below, will return a new instance of Period with the modified value.
- plus(period) – Returns a copy of given period with the specified period added.
- plusYears() – Returns a copy of given period with the specified years added.
- plusMonths() – Returns a copy of given period with the specified months added.
- plusDays() – Returns a copy of given period with the specified days added.
- minus(period) – Returns a copy of given period with the specified period subtracted.
- minusYears() – Returns a copy of given period with the specified years subtracted.
- minusMonths() – Returns a copy of given period with the specified months subtracted.
- minusDays() – Returns a copy of given period with the specified days subtracted.
- multipliedBy(scalar) – Returns a new instance with each element in this period multiplied by the specified scalar.
Period period = Period.ofDays(5); Period periodDaysAdded = period.plus(5); Period periodPlus1Year = period.plusYears(1L);Period and Duration
When you write code to specify an amount of time, use the class or method that best meets your needs: the Duration class, Period class, or the ChronoUnit.between method. A Duration measures an amount of time using time-based values (seconds, nanoseconds). A Period uses date-based values (years, months, days).
Note: A Duration of one day is exactly 24 hours long. A Period of one day, when added to a ZonedDateTime, may vary according to the time zone. For example, if it occurs on the first or last day of daylight saving time.
Duration
A Duration is most suitable in situations that measure machine-based time, such as code that uses an Instant object. A Duration object is measured in seconds or nanoseconds and does not use date-based constructs such as years, months, and days, though the class provides methods that convert to days, hours, and minutes. A Duration can have a negative value, if it is created with an end point that occurs before the start point.
The following code calculates, in nanoseconds, the duration between two instants:
Instant t1, t2; . long ns = Duration.between(t1, t2).toNanos();
The following code adds 10 seconds to an Instant:
Instant start; . Duration gap = Duration.ofSeconds(10); Instant later = start.plus(gap);
A Duration is not connected to the timeline, in that it does not track time zones or daylight saving time. Adding a Duration equivalent to 1 day to a ZonedDateTime results in exactly 24 hours being added, regardless of daylight saving time or other time differences that might result.
ChronoUnit
The ChronoUnit enum, discussed in the The Temporal Package, defines the units used to measure time. The ChronoUnit.between method is useful when you want to measure an amount of time in a single unit of time only, such as days or seconds. The between method works with all temporal-based objects, but it returns the amount in a single unit only. The following code calculates the gap, in milliseconds, between two time-stamps:
import java.time.Instant; import java.time.temporal.Temporal; import java.time.temporal.ChronoUnit; Instant previous, current, gap; . current = Instant.now(); if (previous != null) < gap = ChronoUnit.MILLIS.between(previous,current); >.
Period
To define an amount of time with date-based values (years, months, days), use the Period class. The Period class provides various get methods, such as getMonths, getDays, and getYears, so that you can extract the amount of time from the period.
The total period of time is represented by all three units together: months, days, and years. To present the amount of time measured in a single unit of time, such as days, you can use the ChronoUnit.between method.
The following code reports how old you are, assuming that you were born on January 1, 1960. The Period class is used to determine the time in years, months, and days. The same period, in total days, is determined by using the ChronoUnit.between method and is displayed in parentheses:
LocalDate today = LocalDate.now(); LocalDate birthday = LocalDate.of(1960, Month.JANUARY, 1); Period p = Period.between(birthday, today); long p2 = ChronoUnit.DAYS.between(birthday, today); System.out.println("You are " + p.getYears() + " years, " + p.getMonths() + " months, and " + p.getDays() + " days old. (" + p2 + " days total)"); The code produces output similar to the following:
You are 53 years, 4 months, and 29 days old. (19508 days total)
To calculate how long it is until your next birthday, you could use the following code from the Birthday example. The Period class is used to determine the value in months and days. The ChronoUnit.between method returns the value in total days and is displayed in parentheses.
LocalDate birthday = LocalDate.of(1960, Month.JANUARY, 1); LocalDate nextBDay = birthday.withYear(today.getYear()); //If your birthday has occurred this year already, add 1 to the year. if (nextBDay.isBefore(today) || nextBDay.isEqual(today)) < nextBDay = nextBDay.plusYears(1); >Period p = Period.between(today, nextBDay); long p2 = ChronoUnit.DAYS.between(today, nextBDay); System.out.println("There are " + p.getMonths() + " months, and " + p.getDays() + " days until your next birthday. (" + p2 + " total)"); The code produces output similar to the following:
There are 7 months, and 2 days until your next birthday. (216 total)
These calculations do not account for time zone differences. If you were, for example, born in Australia, but currently live in Bangalore, this slightly affects the calculation of your exact age. In this situation, use a Period in conjunction with the ZonedDateTime class. When you add a Period to a ZonedDateTime, the time differences are observed.