Creating Periods
Like the temporal classes, the Period class does not provide any public constructors, but rather provides an overloaded static factory method of() to construct periods of different lengths, based on date units.
Period p = Period.of(2, 4, 8); // (1)
System.out.println(p); // (2) P2Y4M8D (2 Years, 4 Months, 8 Days)
Period p1 = Period.ofYears(10); // P10Y, period of 10 years.
Period p2 = Period.ofMonths(14); // P14M, period of 14 months.
Period p3 = Period.ofDays(40); // P40D, period of 40 days.
Period p4 = Period.ofWeeks(2); // P14D, period of 14 days (2 weeks).
The most versatile of() method requires the amount of time for all date units: years, months, and days, as at (1). Other of() methods create a period based on a particular date unit, as shown in the examples above.
The toString() method of the Period class returns a text representation of a Period according to the ISO standard: PyYmMdD—that is, y Years, m Months, and d Days. The output from (2) above, P2Y4M8D, indicates a period of 2 years, 4 months, and 8 days.
The code snippet below does not create a period of 3 years, 4 months, and 5 days— it creates a period of only 5 days. The first method call is invoked with the class name, and the subsequent method calls are on the new Period object returned as a consequence of the previous call. The of() method creates a new Period object based on its argument.
Period period = Period.ofYears(3).ofMonths(4).ofDays(5); // P5D. Logical error.
As we would expect, we can create a period that represents the amount of time between two dates by calling the static method between() of the Period class.
LocalDate d1 = LocalDate.of(2021, 3, 1); // 2021-03-01
LocalDate d2 = LocalDate.of(2022, 3, 1); // 2022-03-01
Period period12 = Period.between(d1, d2); // P1Y
Period period21 = Period.between(d2, d1); // P-1Y
The Period class also provides the static method parse() to create a period from a string that contains a text representation of a period in the ISO standard. If the format of the string is not correct, a java.time.format.DateTimeParseException is thrown.
Period period2 = Period.parse(“P1Y15M20D”); // 1 year, 15 months, 20 days
Period period3 = Period.parse(“P20D”); // 20 days
Period period4 = Period.parse(“P5W”); // 35 days (5 weeks)
// Period pX = Period.parse(“P24H”); // java.time.format.DateTimeParseException
static Period ZERO
This constant defines a Period of length zero (P0D).
static Period of(int years, int months, int days)
static Period ofYears(int years)
static Period ofMonths(int months)
static Period ofWeeks(int weeks)
static Period ofDays(int days)
These static factory methods return a Period representing an amount of time equal to the specified value of a date unit. Date units that are implicit are set to zero. A week is equal to 7 days. The argument value can be negative.
static Period between(LocalDate startDateInclusive,
LocalDate endDateExclusive)
This static method returns a Period consisting of the number of years, months, and days between the two dates. The calculation excludes the end date. The result of this method can be a negative period if the end date is before the start date.
String toString()
Returns a text representation of a Period according to the ISO standard. Typical formats are PyYmMdD and PnW—that is, y Years, m Months, and d Days, or n Weeks.
static Period parse(CharSequence text)
This static method returns a Period parsed from a character sequence—for example, “P3Y10M2D” (3 years, 10 months, 2 days). A java.time.format.Date-TimeParseException is thrown if the text cannot be parsed to a period.