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".
Period age = Period.between(LocalDate.of(1990, 5, 20), LocalDate.of(2025, 7, 14));
Try it
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.
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
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.P18M45DbecomesP1Y6M45D.- 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
P1Mto January 31 gives the last day of February, not March 3. betweenworks on dates only. For date-times useChronoUnitorDuration, or calltoLocalDate()first.- Not comparable.
Periodhas nocompareTo;P1MversusP30Dhas no fixed order. Compare components or apply both to the same date. - Equality is component-wise, so
Period.ofMonths(12)is not equal toPeriod.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.
Related
Duration,LocalDate,ChronoUnit- Tutorial: Dates and Times