Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Date and Time

The Period class

Reference for java.time.Period: an amount of years, months and days, computing the difference between dates, adding to dates, normalizing and parsing.

java.time.Period is an amount of time in calendar units: years, months and days, such as "1 year, 2 months and 3 days" (P1Y2M3D). Unlike a Duration, it is not a fixed number of seconds. How long "one month" lasts depends on the date you add it to, so a Period always works together with a date.

Its main uses are measuring the difference between two dates in human terms (age, subscription length) and adding calendar amounts to a date. The three components are stored separately and are not normalized automatically: Period.ofDays(45) stays 45 days and never becomes "1 month and 15 days".

Java
Period age = Period.between(LocalDate.of(1990, 5, 20), LocalDate.of(2025, 7, 14));

Try it

Java Differences between dates

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Adding and normalizing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public final class Period implements ChronoPeriod, Serializable
Member Description
Period.of(int years, int months, int days) From three components.
ofYears(int), ofMonths(int), ofWeeks(int), ofDays(int) Single-unit periods; weeks become 7 days each.
between(LocalDate start, LocalDate end) Difference as years, months and days.
parse(CharSequence) ISO text such as P1Y2M3D, P3W.
getYears(), getMonths(), getDays() The stored components.
plusYears/Months/Days(long), minus..., plus(TemporalAmount) Component arithmetic.
multipliedBy(int), negated() Scaling and sign flip.
normalized() Converts excess months into years (days unchanged).
toTotalMonths() Years times 12 plus months.
isZero(), isNegative() Sign tests.
addTo(Temporal), subtractFrom(Temporal) Apply to a date.

Throws: DateTimeParseException for bad text, ArithmeticException on overflow, UnsupportedTemporalTypeException when added to a temporal without dates.

Usage notes

  • normalized() only handles months into years. It never turns days into months, because that conversion depends on the dates. P18M45D becomes P1Y6M45D.
  • No weeks field. Period.ofWeeks(2) is stored as 14 days.
  • Order of application. When added to a date, years and months go first (with end-of-month clamping), then days. Adding P1M to January 31 gives the last day of February, not March 3.
  • between works on dates only. For date-times use ChronoUnit or Duration, or call toLocalDate() first.
  • Not comparable. Period has no compareTo; P1M versus P30D has no fixed order. Compare components or apply both to the same date.
  • Equality is component-wise, so Period.ofMonths(12) is not equal to Period.ofYears(1) until normalized.
  • For ages, Period.between(birthDate, today).getYears() is correct; dividing a day count by 365 is not.
  • Zone changes do not matter: Period is purely calendar-based, with no time component.