Java : Period (日付の量) - API使用例

Period (Java SE 21 & JDK 21) の使い方まとめです。
だいたいのメソッドを網羅済みです。
API仕様書のおともにどうぞ。

概要

ISO-8601暦体系における日付ベースの時間の量(「2年3か月と4日」など)。

クラス構成

Period は、年月日の量 (長さ) を表します。例えば、

100日
1年と2か月と3日

などが表現できます。

似た API に Duration があります。
こちらは、秒とナノ秒を基準とした時間の量です。

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

フィールド

static final Period 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

メソッド

Temporal addTo (Temporal temporal)

指定された時間的オブジェクトにこの期間を加算します。

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)

2つの日付間の年数、月数、および日数で構成されるPeriodを取得します。

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)

この期間がもう一方の期間と等しいかどうかを確認します。

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)

時間的な量からPeriodのインスタンスを取得します。

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)

要求された単位の値を取得します。

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

ISO暦体系であるこの期間の暦を取得します。

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

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

int getDays ()

この期間の日数を取得します。

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

この期間の月数を取得します。

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

この期間でサポートされる一連の単位を取得します。

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

int getYears ()

この期間の年数を取得します。

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

この期間のハッシュ・コード。

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

この期間の3つの単位のいずれかが負の値であるかどうかを確認します。

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

この期間の3つの単位すべてがゼロであるかどうかを確認します。

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)

指定された期間を減算して、この期間のコピーを返します。

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)

指定された日数を減算して、この期間のコピーを返します。

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)

指定された月数を減算して、この期間のコピーを返します。

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)

指定された年数を減算して、この期間のコピーを返します。

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)

この期間の各要素に指定されたスカラーを掛けて、新しいインスタンスを返します。

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

この期間の各量を否定した、新しいインスタンスを返します。

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

その年数および月数を正規化して、この期間のコピーを返します。

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)

年数、月数、および日数を表す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

static Period ofDays (int days)

日数を表すPeriodを取得します。

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)

月数を表すPeriodを取得します。

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)

週数を表すPeriodを取得します。

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)

年数を表すPeriodを取得します。

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)

PnYnMnDなどのテキスト文字列からPeriodを取得します。

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)

この期間のコピーに指定された期間を追加したものを返します。

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)

指定された日数を加算して、この期間のコピーを返します。

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)

指定された月数を加算して、この期間のコピーを返します。

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)

指定された年数を加算して、この期間のコピーを返します。

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)

指定された時間的オブジェクトからこの期間を減算します。

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

この期間をStringとして出力します(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 ()

この期間の合計月数を取得します。

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)

指定された日数を使って、この期間のコピーを返します。

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)

指定された月数を使って、この期間のコピーを返します。

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)

指定された年数を使って、この期間のコピーを返します。

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 使用例

Java : Period (日付の量) - API使用例

概要

フィールド

static final Period ZERO

メソッド

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)

関連記事