Java : Period with Examples

Period (Java SE 18 & JDK 18) with Examples.
You will find code examples on most Period methods.


Summary

A date-based amount of time in the ISO-8601 calendar system, such as '2 years, 3 months and 4 days'.

Class diagram

final var period = Period.ofDays(100);
System.out.println(period.getYears()); // 0
System.out.println(period.getMonths()); // 0
System.out.println(period.getDays()); // 100
final var period = Period.of(1, 2, 3);
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

final var date = LocalDate.of(2000, 1, 1);
System.out.println(date); // 2000-01-01

final var ret = date.plus(period);
System.out.println(ret); // 2001-03-04

Fields

static final Period ZERO

A constant for a period of zero.

System.out.println(Period.ZERO); // P0D
System.out.println(Period.ZERO.getYears()); // 0
System.out.println(Period.ZERO.getMonths()); // 0
System.out.println(Period.ZERO.getDays()); // 0

Methods

Temporal addTo (Temporal temporal)

Adds this period to the specified temporal object.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

final var date = LocalDate.of(2000, 1, 1);
System.out.println(date); // 2000-01-01

final var ret = period.addTo(date);
System.out.println(ret); // 2001-03-04
final var period = Period.ofDays(-1);
System.out.println(period); // P-1D
System.out.println(period.getDays()); // -1

final var dateTime = LocalDateTime.of(2000, 1, 1, 0, 0);
System.out.println(dateTime); // 2000-01-01T00:00

final var ret = period.addTo(dateTime);
System.out.println(ret); // 1999-12-31T00:00

static Period between (LocalDate startDateInclusive, LocalDate endDateExclusive)

Obtains a Period consisting of the number of years, months, and days between two dates.

final var date1 = LocalDate.of(2000, 1, 1);
final var date2 = LocalDate.of(2001, 3, 4);

System.out.println(date1); // 2000-01-01
System.out.println(date2); // 2001-03-04

final var period = Period.between(date1, date2);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

boolean equals (Object obj)

Checks if this period is equal to another period.

final var period1 = Period.of(1, 2, 3);
final var period2 = Period.of(1, 2, 3);

System.out.println(period1); // P1Y2M3D
System.out.println(period2); // P1Y2M3D

System.out.println(period1.equals(period2)); // true
final var period1 = Period.ofDays(123);
final var period2 = Period.ofDays(-123);

System.out.println(period1); // P123D
System.out.println(period2); // P-123D

System.out.println(period1.equals(period2)); // false
final var period1 = Period.ofMonths(100);
final var period2 = Period.ofYears(100);

System.out.println(period1); // P100M
System.out.println(period2);  // P100Y

System.out.println(period1.equals(period2)); // false

static Period from (TemporalAmount amount)

Obtains an instance of Period from a temporal amount.

// It may not be a useful example.
final var amount = Period.of(1, 2, 3);
System.out.println(amount); // P1Y2M3D

final var ret = Period.from(amount);
System.out.println(ret); // P1Y2M3D

long get (TemporalUnit unit)

Gets the value of the requested unit.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D

System.out.println(period.get(ChronoUnit.YEARS)); // 1
System.out.println(period.get(ChronoUnit.MONTHS)); // 2
System.out.println(period.get(ChronoUnit.DAYS)); // 3

IsoChronology getChronology ()

Gets the chronology of this period, which is the ISO calendar system.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D

System.out.println(period.getChronology()); // ISO

int getDays ()

Gets the amount of days of this period.

Please see getYears().

int getMonths ()

Gets the amount of months of this period.

Please see getYears().

List<TemporalUnit> getUnits ()

Gets the set of units supported by this period.

final var period = Period.ofDays(123);
System.out.println(period.getUnits()); // [Years, Months, Days]

int getYears ()

Gets the amount of years of this period.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3
final var period = Period.of(123, -456, 100000);
System.out.println(period); // P123Y-456M100000D
System.out.println(period.getYears()); // 123
System.out.println(period.getMonths()); // -456
System.out.println(period.getDays()); // 100000

int hashCode ()

A hash code for this period.

System.out.println(Period.ZERO.hashCode()); // 0
System.out.println(Period.of(1, 2, 3).hashCode()); // 197121
System.out.println(Period.ofDays(123).hashCode()); // 8060928
System.out.println(Period.ofMonths(456).hashCode()); // 116736
System.out.println(Period.ofYears(-789).hashCode()); // -789

boolean isNegative ()

Checks if any of the three units of this period are negative.

System.out.println(Period.ZERO.isNegative()); // false

System.out.println(Period.of(1, 2, 3).isNegative()); // false
System.out.println(Period.of(1, 2, -3).isNegative()); // true
System.out.println(Period.of(1, -2, 3).isNegative()); // true
System.out.println(Period.of(-1, 2, 3).isNegative()); // true

System.out.println(Period.ofDays(123).isNegative()); // false
System.out.println(Period.ofMonths(-456).isNegative()); // true

boolean isZero ()

Checks if all three units of this period are zero.

System.out.println(Period.ZERO.isZero()); // true

System.out.println(Period.of(1, 2, 3).isZero()); // false
System.out.println(Period.of(1, 2, 0).isZero()); // false
System.out.println(Period.of(1, 0, 3).isZero()); // false
System.out.println(Period.of(0, 2, 3).isZero()); // false

System.out.println(Period.ofDays(123).isZero()); // false
System.out.println(Period.ofMonths(-456).isZero()); // false

Period minus (TemporalAmount amountToSubtract)

Returns a copy of this period with the specified period subtracted.

final var period = Period.of(10, 20, 30);
System.out.println(period); // P10Y20M30D
System.out.println(period.getYears()); // 10
System.out.println(period.getMonths()); // 20
System.out.println(period.getDays()); // 30

final var ret = period.minus(Period.of(1, 2, 3));
System.out.println(ret); // P9Y18M27D
System.out.println(ret.getYears()); // 9
System.out.println(ret.getMonths()); // 18
System.out.println(ret.getDays()); // 27
final var period = Period.ofDays(100);
System.out.println(period); // P100D
System.out.println(period.getYears()); // 0
System.out.println(period.getMonths()); // 0
System.out.println(period.getDays()); // 100

final var ret = period.minus(Period.of(1, 2, 3));
System.out.println(ret); // P-1Y-2M97D
System.out.println(ret.getYears()); // -1
System.out.println(ret.getMonths()); // -2
System.out.println(ret.getDays()); // 97

Period minusDays (long daysToSubtract)

Returns a copy of this period with the specified days subtracted.

final var period = Period.of(10, 20, 30);
System.out.println(period); // P10Y20M30D
System.out.println(period.getYears()); // 10
System.out.println(period.getMonths()); // 20
System.out.println(period.getDays()); // 30

final var ret = period.minusDays(5);
System.out.println(ret); // P10Y20M25D
System.out.println(ret.getYears()); // 10
System.out.println(ret.getMonths()); // 20
System.out.println(ret.getDays()); // 25
final var period = Period.ofDays(100);
System.out.println(period); // P100D
System.out.println(period.getDays()); // 100

final var ret = period.minusDays(150);
System.out.println(ret); // P-50D
System.out.println(ret.getDays()); // -50

Period minusMonths (long monthsToSubtract)

Returns a copy of this period with the specified months subtracted.

final var period = Period.of(10, 20, 30);
System.out.println(period); // P10Y20M30D
System.out.println(period.getYears()); // 10
System.out.println(period.getMonths()); // 20
System.out.println(period.getDays()); // 30

final var ret = period.minusMonths(5);
System.out.println(ret); // P10Y15M30D
System.out.println(ret.getYears()); // 10
System.out.println(ret.getMonths()); // 15
System.out.println(ret.getDays()); // 30
final var period = Period.ofMonths(100);
System.out.println(period); // P100M
System.out.println(period.getMonths()); // 100

final var ret = period.minusMonths(150);
System.out.println(ret); // P-50M
System.out.println(ret.getMonths()); // -50

Period minusYears (long yearsToSubtract)

Returns a copy of this period with the specified years subtracted.

final var period = Period.of(10, 20, 30);
System.out.println(period); // P10Y20M30D
System.out.println(period.getYears()); // 10
System.out.println(period.getMonths()); // 20
System.out.println(period.getDays()); // 30

final var ret = period.minusYears(5);
System.out.println(ret); // P5Y20M30D
System.out.println(ret.getYears()); // 5
System.out.println(ret.getMonths()); // 20
System.out.println(ret.getDays()); // 30
final var period = Period.ofYears(100);
System.out.println(period); // P100Y
System.out.println(period.getYears()); // 100

final var ret = period.minusYears(150);
System.out.println(ret); // P-50Y
System.out.println(ret.getYears()); // -50

Period multipliedBy (int scalar)

Returns a new instance with each element in this period multiplied by the specified scalar.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

final var ret = period.multipliedBy(2);
System.out.println(ret); // P2Y4M6D
System.out.println(ret.getYears()); // 2
System.out.println(ret.getMonths()); // 4
System.out.println(ret.getDays()); // 6
final var period = Period.ofDays(100);
System.out.println(period); // P100D
System.out.println(period.getDays()); // 100

final var ret = period.multipliedBy(-3);
System.out.println(ret); // P-300D
System.out.println(ret.getDays()); // -300

Period negated ()

Returns a new instance with each amount in this period negated.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

final var ret = period.negated();
System.out.println(ret); // P-1Y-2M-3D
System.out.println(ret.getYears()); // -1
System.out.println(ret.getMonths()); // -2
System.out.println(ret.getDays()); // -3
final var period = Period.of(-123, 456, -789);
System.out.println(period); // P-123Y456M-789D
System.out.println(period.getYears()); // -123
System.out.println(period.getMonths()); // 456
System.out.println(period.getDays()); // -789

final var ret = period.negated();
System.out.println(ret); // P123Y-456M789D
System.out.println(ret.getYears()); // 123
System.out.println(ret.getMonths()); // -456
System.out.println(ret.getDays()); // 789

Period normalized ()

Returns a copy of this period with the years and months normalized.

final var period = Period.of(1, 15, 0);
System.out.println(period); // P1Y15M
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 15
System.out.println(period.getDays()); // 0

final var ret = period.normalized();
System.out.println(ret); // P2Y3M
System.out.println(ret.getYears()); // 2
System.out.println(ret.getMonths()); // 3
System.out.println(ret.getDays()); // 0
final var period = Period.ofMonths(100);
System.out.println(period); // P100M
System.out.println(period.getYears()); // 0
System.out.println(period.getMonths()); // 100

final var ret = period.normalized();
System.out.println(ret); // P8Y4M
System.out.println(ret.getYears()); // 8
System.out.println(ret.getMonths()); // 4

static Period of (int years, int months, int days)

Obtains a Period representing a number of years, months and days.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

static Period ofDays (int days)

Obtains a Period representing a number of days.

final var period = Period.ofDays(123);
System.out.println(period); // P123D
System.out.println(period.getYears()); // 0
System.out.println(period.getMonths()); // 0
System.out.println(period.getDays()); // 123

static Period ofMonths (int months)

Obtains a Period representing a number of months.

final var period = Period.ofMonths(123);
System.out.println(period); // P123M
System.out.println(period.getYears()); // 0
System.out.println(period.getMonths()); // 123
System.out.println(period.getDays()); // 0

static Period ofWeeks (int weeks)

Obtains a Period representing a number of weeks.

final var period = Period.ofWeeks(10);
System.out.println(period); // P70D
System.out.println(period.getYears()); // 0
System.out.println(period.getMonths()); // 0
System.out.println(period.getDays()); // 70

static Period ofYears (int years)

Obtains a Period representing a number of years.

final var period = Period.ofYears(123);
System.out.println(period); // P123Y
System.out.println(period.getYears()); // 123
System.out.println(period.getMonths()); // 0
System.out.println(period.getDays()); // 0

static Period parse (CharSequence text)

Obtains a Period from a text string such as PnYnMnD.

final var period = Period.parse("P1Y2M3D");
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3
final var period = Period.parse("P4W");
System.out.println(period); // P28D
System.out.println(period.getYears()); // 0
System.out.println(period.getMonths()); // 0
System.out.println(period.getDays()); // 28

Period plus (TemporalAmount amountToAdd)

Returns a copy of this period with the specified period added.

final var period = Period.of(10, 20, 30);
System.out.println(period); // P10Y20M30D
System.out.println(period.getYears()); // 10
System.out.println(period.getMonths()); // 20
System.out.println(period.getDays()); // 30

final var ret = period.plus(Period.of(1, 2, 3));
System.out.println(ret); // P11Y22M33D
System.out.println(ret.getYears()); // 11
System.out.println(ret.getMonths()); // 22
System.out.println(ret.getDays()); // 33
final var period = Period.ofDays(-100);
System.out.println(period); // P-100D
System.out.println(period.getYears()); // 0
System.out.println(period.getMonths()); // 0
System.out.println(period.getDays()); // -100

final var ret = period.plus(Period.of(1, 2, 3));
System.out.println(ret); // P1Y2M-97D
System.out.println(ret.getYears()); // 1
System.out.println(ret.getMonths()); // 2
System.out.println(ret.getDays()); // -97

Period plusDays (long daysToAdd)

Returns a copy of this period with the specified days added.

final var period = Period.of(10, 20, 30);
System.out.println(period); // P10Y20M30D
System.out.println(period.getYears()); // 10
System.out.println(period.getMonths()); // 20
System.out.println(period.getDays()); // 30

final var ret = period.plusDays(5);
System.out.println(ret); // P10Y20M35D
System.out.println(ret.getYears()); // 10
System.out.println(ret.getMonths()); // 20
System.out.println(ret.getDays()); // 35
final var period = Period.ofDays(-100);
System.out.println(period); // P-100D
System.out.println(period.getDays()); // -100

final var ret = period.plusDays(150);
System.out.println(ret); // P50D
System.out.println(ret.getDays()); // 50

Period plusMonths (long monthsToAdd)

Returns a copy of this period with the specified months added.

final var period = Period.of(10, 20, 30);
System.out.println(period); // P10Y20M30D
System.out.println(period.getYears()); // 10
System.out.println(period.getMonths()); // 20
System.out.println(period.getDays()); // 30

final var ret = period.plusMonths(5);
System.out.println(ret); // P10Y25M30D
System.out.println(ret.getYears()); // 10
System.out.println(ret.getMonths()); // 25
System.out.println(ret.getDays()); // 30
final var period = Period.ofMonths(-100);
System.out.println(period); // P-100M
System.out.println(period.getMonths()); // -100

final var ret = period.plusMonths(150);
System.out.println(ret); // P50M
System.out.println(ret.getMonths()); // 50

Period plusYears (long yearsToAdd)

Returns a copy of this period with the specified years added.

final var period = Period.of(10, 20, 30);
System.out.println(period); // P10Y20M30D
System.out.println(period.getYears()); // 10
System.out.println(period.getMonths()); // 20
System.out.println(period.getDays()); // 30

final var ret = period.plusYears(5);
System.out.println(ret); // P15Y20M30D
System.out.println(ret.getYears()); // 15
System.out.println(ret.getMonths()); // 20
System.out.println(ret.getDays()); // 30
final var period = Period.ofYears(-100);
System.out.println(period); // P-100Y
System.out.println(period.getYears()); // -100

final var ret = period.plusYears(150);
System.out.println(ret); // P50Y
System.out.println(ret.getYears()); // 50

Temporal subtractFrom (Temporal temporal)

Subtracts this period from the specified temporal object.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

final var date = LocalDate.of(2000, 12, 30);
System.out.println(date); // 2000-12-30

final var ret = period.subtractFrom(date);
System.out.println(ret); // 1999-10-27

String toString ()

Outputs this period as a String, such as P6Y3M1D.

final var str1 = Period.of(1, 2, 3).toString();
System.out.println(str1); // P1Y2M3D

final var str2 = Period.ZERO.toString();
System.out.println(str2); // P0D

final var str3 = Period.ofWeeks(10).toString();
System.out.println(str3); // P70D

long toTotalMonths ()

Gets the total number of months in this period.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

System.out.println(period.toTotalMonths()); // 14
final var period = Period.ofYears(100);
System.out.println(period); // P100Y
System.out.println(period.getYears()); // 100
System.out.println(period.getMonths()); // 0
System.out.println(period.getDays()); // 0

System.out.println(period.toTotalMonths()); // 1200

Period withDays (int days)

Returns a copy of this period with the specified amount of days.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

final var ret = period.withDays(100);
System.out.println(ret); // P1Y2M100D
System.out.println(ret.getYears()); // 1
System.out.println(ret.getMonths()); // 2
System.out.println(ret.getDays()); // 100

Period withMonths (int months)

Returns a copy of this period with the specified amount of months.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

final var ret = period.withMonths(100);
System.out.println(ret); // P1Y100M3D
System.out.println(ret.getYears()); // 1
System.out.println(ret.getMonths()); // 100
System.out.println(ret.getDays()); // 3

Period withYears (int years)

Returns a copy of this period with the specified amount of years.

final var period = Period.of(1, 2, 3);
System.out.println(period); // P1Y2M3D
System.out.println(period.getYears()); // 1
System.out.println(period.getMonths()); // 2
System.out.println(period.getDays()); // 3

final var ret = period.withYears(100);
System.out.println(ret); // P100Y2M3D
System.out.println(ret.getYears()); // 100
System.out.println(ret.getMonths()); // 2
System.out.println(ret.getDays()); // 3

Related posts

To top of page