Java Period API

Learn to create and use the Java 8 Period class. The Period API is used to represent the period of time in date-based values such as days, months, years, weeks, or years using the ISO-8601 calendar system.

1. Obtaining a Period

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.

This period of time can be obtained in different ways.

1.1. Period.between()

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));	//8

1.2. Period.ofDays()

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.

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 weeks

1.3. Period.of()

Using of(int years, int months, int days), we can get an instance based on years, months, and days.

//20 years, 3 months and 20 days
Period periodFromUnits = Period.of(20, 3, 20);

1.4. Period.parse()

Period can be obtained from a String 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. Get Period Values

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);

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));	//8

//Throws UnsupportedTemporalTypeException
System.out.println(periodBetween.get(ChronoUnit.WEEKS));

3. Modifying a Period

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);

Happy Learning !!

Sourcecode Download