モジュール java.base
パッケージ java.time.chrono

インタフェースChronoPeriod

すべてのスーパー・インタフェース:
TemporalAmount
既知のすべての実装クラス:
Period
public interface ChronoPeriod
extends TemporalAmount
任意の暦での「3年、4か月、5日」などの、日付ベースの時間の量、高度なグローバリゼーション・ユース・ケース向けです。

このインタフェースは、暦体系の日付ベースの時間の量をモデル化します。 ほとんどの暦体系では年、月、および日が使われていますが、一部では使われていません。 そのため、このインタフェースは、Chronologyによって定義されている一連のサポートされる単位の形でのみ動作します。 サポートされている一連の単位は特定の暦に固定されています。 サポートされている単位の量はゼロに設定できます。

期間は、方向性のある時間の量としてモデル化されます。つまり、期間の個々の部分は負になることがあります。

実装要件:
このインタフェースは、他のクラスが正常に動作するように、注意して実装する必要があります。 インスタンス化可能なすべての実装は、最終、不変、およびスレッドセーフである必要があります。 サブクラスは、可能であれば直列化可能にしてください。
導入されたバージョン:
1.8

  • メソッドのサマリー

    修飾子と型 メソッド 説明
    Temporal addTo​(Temporal temporal)
    指定された時間的オブジェクトにこの期間を加算します。
    static ChronoPeriod between​(ChronoLocalDate startDateInclusive, ChronoLocalDate endDateExclusive)
    2つの日付の間の時間の量から構成されるChronoPeriodを取得します。
    boolean equals​(Object obj)
    暦を含めて、この期間が別の期間と等しいかどうかをチェックします。
    long get​(TemporalUnit unit)
    要求された単位の値を取得します。
    Chronology getChronology()
    サポートされる単位の意味を定義する暦を取得します。
    List<TemporalUnit> getUnits()
    この期間でサポートされる一連の単位を取得します。
    int hashCode()
    この期間のハッシュ・コード。
    default boolean isNegative()
    この期間のサポートされる単位のいずれかが負であるかどうかをチェックします。
    default boolean isZero()
    この期間のサポートされる単位のすべてがゼロであるかどうかをチェックします。
    ChronoPeriod minus​(TemporalAmount amountToSubtract)
    指定された期間を減算して、この期間のコピーを返します。
    ChronoPeriod multipliedBy​(int scalar)
    この期間の各量を指定されたスカラーで乗算して、新しいインスタンスを返します。
    default ChronoPeriod negated()
    この期間の各量を否定した、新しいインスタンスを返します。
    ChronoPeriod normalized()
    各単位の量を正規化して、この期間のコピーを返します。
    ChronoPeriod plus​(TemporalAmount amountToAdd)
    この期間のコピーに指定された期間を追加したものを返します。
    Temporal subtractFrom​(Temporal temporal)
    指定された時間的オブジェクトからこの期間を減算します。
    String toString()
    この期間をStringとして出力します。

  • メソッドの詳細

    • between

      static ChronoPeriod between​(ChronoLocalDate startDateInclusive, ChronoLocalDate endDateExclusive)
      2つの日付の間の時間の量から構成されるChronoPeriodを取得します。

      開始日は含まれますが、終了日は含まれません。 期間はChronoLocalDate.until(ChronoLocalDate)を使用して計算されます。 そのため、計算は暦固有です。

      最初の日付の暦が使われます。 2つ目の日付の暦は無視され、計算が開始される前に、日付がターゲットの暦システムに変換されます。

      このメソッドの結果は、終了が開始より前である場合に、負の期間になることがあります。 ほとんどの場合に、プラス/マイナス記号はサポートされる各フィールドで同じになります。

      パラメータ:
      startDateInclusive - 開始日(この日を含む)、計算の暦を指定、null以外
      endDateExclusive - 終了日(この日を含まない)、任意の暦、null以外
      戻り値:
      この日付と終了日の間の期間、null以外
      関連項目:
      ChronoLocalDate.until(ChronoLocalDate)

    • get

      long get​(TemporalUnit unit)
      要求された単位の値を取得します。

      サポートされている単位は暦固有です。 それらは一般に、YEARS、MONTHS、DAYSです。 サポートされていない単位を要求すると、例外をスローします。

      定義:
      インタフェースTemporalAmountのget
      パラメータ:
      unit - 値を返す対象のTemporalUnit
      戻り値:
      単位のlong値
      例外:
      DateTimeException - 単位がサポートされていない場合
      UnsupportedTemporalTypeException - 単位がサポートされていない場合

    • getUnits

      List<TemporalUnit> getUnits()
      この期間でサポートされる一連の単位を取得します。

      サポートされている単位は暦固有です。 それらは一般に、YEARS、MONTHS、DAYSです。 それらは最大から最小の順番で返されます。

      このセットは、get(TemporalUnit)と一緒に使用して、期間の全体の状態にアクセスできます。

      定義:
      インタフェースTemporalAmountのgetUnits
      戻り値:
      サポートされる単位を含むリスト、null以外

    • getChronology

      Chronology getChronology()
      サポートされる単位の意味を定義する暦を取得します。

      期間は暦によって定義されます。 サポートされる単位を制御し、加算/減算を同じ暦のChronoLocalDateインスタンスに制限します。

      戻り値:
      期間を定義する暦、null以外

    • isZero

      default boolean isZero()
      この期間のサポートされる単位のすべてがゼロであるかどうかをチェックします。
      戻り値:
      この期間がゼロの長さである場合true

    • isNegative

      default boolean isNegative()
      この期間のサポートされる単位のいずれかが負であるかどうかをチェックします。
      戻り値:
      この期間のいずれかの単位が負の場合true

    • plus

      ChronoPeriod plus​(TemporalAmount amountToAdd)
      この期間のコピーに指定された期間を追加したものを返します。

      指定された量がChronoPeriodの場合、この期間と同じ暦である必要があります。 実装では、他のTemporalAmount実装を受け入れることも拒否することも選択できます。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      パラメータ:
      amountToAdd - 加算する期間、null以外
      戻り値:
      要求された期間を加算し、この期間に基づいたChronoPeriod、null以外
      例外:
      ArithmeticException - 数値のオーバーフローが発生した場合

    • minus

      ChronoPeriod minus​(TemporalAmount amountToSubtract)
      指定された期間を減算して、この期間のコピーを返します。

      指定された量がChronoPeriodの場合、この期間と同じ暦である必要があります。 実装では、他のTemporalAmount実装を受け入れることも拒否することも選択できます。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      パラメータ:
      amountToSubtract - 減算する期間、null以外
      戻り値:
      要求された期間を減算した、この期間に基づいたChronoPeriod、null以外
      例外:
      ArithmeticException - 数値のオーバーフローが発生した場合

    • multipliedBy

      ChronoPeriod multipliedBy​(int scalar)
      この期間の各量を指定されたスカラーで乗算して、新しいインスタンスを返します。

      これは、サポートされる単位が個別に乗算された期間を返します。 たとえば、3を乗算した「2年、-3か月、4日」の期間は、「6年、-9か月、12日」を返します。 正規化は実行されません。

      パラメータ:
      scalar - 乗算するスカラー、null以外
      戻り値:
      スカラーによって乗算された量のこの期間に基づいたChronoPeriod、null以外
      例外:
      ArithmeticException - 数値のオーバーフローが発生した場合

    • negated

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

      これは、サポートされる各単位が個別に否定された期間を返します。 たとえば、「2年、-3か月、4日」の期間は「-2年、3か月、-4日」に否定されます。 正規化は実行されません。

      戻り値:
      否定された量のこの期間に基づいたChronoPeriod、null以外
      例外:
      ArithmeticException - 数値オーバーフローが発生した場合、これはいずれかの単位の値がLong.MIN_VALUEである場合にのみ発生する

    • normalized

      ChronoPeriod normalized()
      各単位の量を正規化して、この期間のコピーを返します。

      正規化のプロセスは各暦体系に固有です。 たとえば、ISO暦体系では、年と月が正規化されますが、日は正規化されません。そのため、「15か月」は「1年と3か月」に正規化されます。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      戻り値:
      正規化された各単位の量のこの期間に基づいたChronoPeriod、null以外
      例外:
      ArithmeticException - 数値のオーバーフローが発生した場合

    • addTo

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

      これは、この期間を加算した入力と同じ識別可能な型の時間的オブジェクトを返します。

      ほとんどのケースで、Temporal.plus(TemporalAmount)を使用して、呼び出しパターンを逆にすると明確になります。 

         // these two lines are equivalent, but the second approach is recommended
   dateTime = thisPeriod.addTo(dateTime);
   dateTime = dateTime.plus(thisPeriod);

      指定された時間的オブジェクトはこの期間と同じ暦である必要があります。 これは、ゼロ以外のサポートされる単位が加算された時間的オブジェクトを返します。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      定義:
      インタフェースTemporalAmountのaddTo
      パラメータ:
      temporal - 調整する時間的オブジェクト。null以外
      戻り値:
      調整が行われた同じ型のオブジェクト、null以外
      例外:
      DateTimeException - 加算できない場合
      ArithmeticException - 数値のオーバーフローが発生した場合

    • subtractFrom

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

      これは、この期間を減算した入力と同じ識別可能な型の時間的オブジェクトを返します。

      ほとんどのケースで、Temporal.minus(TemporalAmount)を使用して、呼び出しパターンを逆にすると明確になります。 

         // these two lines are equivalent, but the second approach is recommended
   dateTime = thisPeriod.subtractFrom(dateTime);
   dateTime = dateTime.minus(thisPeriod);

      指定された時間的オブジェクトはこの期間と同じ暦である必要があります。 これは、ゼロ以外のサポートされる単位が減算された時間的オブジェクトを返します。

      このインスタンスは不変で、このメソッド呼び出しによって影響を受けません。

      定義:
      インタフェースTemporalAmountのsubtractFrom
      パラメータ:
      temporal - 調整する時間的オブジェクト。null以外
      戻り値:
      調整が行われた同じ型のオブジェクト、null以外
      例外:
      DateTimeException - 減算できない場合
      ArithmeticException - 数値のオーバーフローが発生した場合

    • equals

      boolean equals​(Object obj)
      暦を含めて、この期間が別の期間と等しいかどうかをチェックします。

      この期間を別の期間と比較して、タイプ、各量、暦が同じであることを確認します。 これは、「15か月」の期間が「1年と3か月」の期間と等しくないことを意味することに注意してください。

      オーバーライド:
      equals 、クラス:  Object
      パラメータ:
      obj - チェックするオブジェクト、nullはfalseを返す
      戻り値:
      これが他の期間と等しい場合はtrue
      関連項目:
      Object.hashCode()、HashMap

    • hashCode

      int hashCode()
      この期間のハッシュ・コード。
      オーバーライド:
      hashCode 、クラス:  Object
      戻り値:
      適切なハッシュ・コード
      関連項目:
      Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

    • toString

      String toString()
      この期間をStringとして出力します。

      出力には、期間の量と暦が含まれます。

      オーバーライド:
      toString 、クラス:  Object
      戻り値:
      この期間の文字列表現、null以外