Guide to Java Period

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.

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.

The period of time can be obtained in the following ways.

1.1. Period between Two Date Time Objects

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. 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 weeks

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

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