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

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


概要

クラス構成

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

  • 100日
  • 1年と2か月と3日

などが表現できます。

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

// 2000/1/1 に 1年と2か月と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

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

フィールド

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

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

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)

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

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)

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

このAPIを使うより、getYearsgetMonthsgetDays を使うのをおすすめします。

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

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

このメソッドの使用例は、getYears() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

int getMonths ()

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

このメソッドの使用例は、getYears() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

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

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

// 1年と15か月
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

// 2年と3か月
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

関連記事

ページの先頭へ