Java : Period with Examples

Period (Java SE 21 & JDK 21) 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.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(2101, 1, 1);
System.out.println(date); // 2101-01-01

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

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

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(2100, 1, 1);
System.out.println(date); // 2100-01-01

final var ret = period.addTo(date);
System.out.println(ret); // 2101-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(2100, 1, 1, 0, 0);
System.out.println(dateTime); // 2100-01-01T00:00

final var ret = period.addTo(dateTime);
System.out.println(ret); // 2099-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(2100, 1, 1);
final var date2 = LocalDate.of(2101, 3, 4);

System.out.println(date1); // 2100-01-01
System.out.println(date2); // 2101-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.

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.

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 getMonths ()

Gets the amount of months 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

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

API Examples
- Calendar
- ChronoLocalDate
- ChronoLocalDateTime
- ChronoZonedDateTime
- Clock
- Date
- DateTimeException
- DateTimeParseException
- DayOfWeek
- Duration
- Era
  - IsoEra
  - JapaneseEra
- Instant
- InstantSource
- JapaneseDate
- LocalDate
- LocalDateTime
- LocalTime
- Month
- MonthDay
- OffsetDateTime
- OffsetTime
- Temporal
- TemporalAccessor
- TemporalAdjuster
- TemporalAdjusters
- TimeZone
- Year
- YearMonth
- ZonedDateTime
- ZoneId
- ZoneOffset

Java : Period with Examples

Summary

Fields

static final Period ZERO

Methods

Temporal addTo (Temporal temporal)

static Period between (LocalDate startDateInclusive, LocalDate endDateExclusive)

boolean equals (Object obj)

static Period from (TemporalAmount amount)

long get (TemporalUnit unit)

IsoChronology getChronology ()

int getDays ()

int getMonths ()

List<TemporalUnit> getUnits ()

int getYears ()

int hashCode ()

boolean isNegative ()

boolean isZero ()

Period minus (TemporalAmount amountToSubtract)

Period minusDays (long daysToSubtract)

Period minusMonths (long monthsToSubtract)

Period minusYears (long yearsToSubtract)

Period multipliedBy (int scalar)

Period negated ()

Period normalized ()

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

static Period ofDays (int days)

static Period ofMonths (int months)

static Period ofWeeks (int weeks)

static Period ofYears (int years)

static Period parse (CharSequence text)

Period plus (TemporalAmount amountToAdd)

Period plusDays (long daysToAdd)

Period plusMonths (long monthsToAdd)

Period plusYears (long yearsToAdd)

Temporal subtractFrom (Temporal temporal)

String toString ()

long toTotalMonths ()

Period withDays (int days)

Period withMonths (int months)

Period withYears (int years)

Related posts