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

インタフェースTemporalAmount

既知のすべてのサブインタフェース:
ChronoPeriod
既知のすべての実装クラス:
Duration, Period
public interface TemporalAmount
「6時間」、「8日間」、「2年3か月」などの時間量を定義するフレームワークレベルのインタフェースです。

これは、時間の量のベース・インタフェース型です。 量は、時系列の特定のポイントに関連付けられない点で、日付や時とは異なります。

この量は、getUnits()およびget(TemporalUnit)を介して公開される、TemporalUnitのlongへのMapと考えることができます。 簡単な例には、1つの単位/値ペア(「6時間」など)が含まれます。 より複雑なケースには、複数の単位/値ペア(「7年3か月と5日」など)が含まれます。

2つの一般的な実装があります。 Periodは、年、月および日を格納する日付ベースの実装です。 Durationは、秒およびナノ秒を格納する時間ベースの実装ですが、他のデュレーション・ベースの単位(分、時、固定の24時間日など)を使用して一部のアクセスを提供します。

このインタフェースはフレームワークレベルのインタフェースであり、アプリケーション・コードで広範囲にわたって使用しないようにしてください。 かわりに、PeriodやDurationなどの具象型のインスタンスを作成して使い回してください。

実装要件:
このインタフェースは実装が可変であることを制限しませんが、不変にすることを強くお薦めします。
導入されたバージョン:
1.8

  • メソッドのサマリー

    修飾子と型 メソッド 説明
    Temporal addTo​(Temporal temporal)
    指定された時間的オブジェクトに加算します。
    long get​(TemporalUnit unit)
    要求された単位の値を返します。
    List<TemporalUnit> getUnits()
    このTemporalAmountの値を一意に定義する単位のリストを返します。
    Temporal subtractFrom​(Temporal temporal)
    指定された時間的オブジェクトからこのオブジェクトを減算します。

  • メソッドの詳細

    • get

      long get​(TemporalUnit unit)
      要求された単位の値を返します。 getUnits()から返される単位は、TemporalAmountの値を一意に定義します。 getUnitsでリストされる各単位の値を返す必要があります。
      実装要件:
      実装は、getUnits()でリストされない単位のサポートを宣言できます。 一般に、実装は開発者の便宜のために追加の単位を変換として宣言します。
      パラメータ:
      unit - 値を返す対象のTemporalUnit
      戻り値:
      単位のlong値
      例外:
      DateTimeException - 単位の値を取得できない場合
      UnsupportedTemporalTypeException - unitがサポートされていない場合

    • getUnits

      List<TemporalUnit> getUnits()
      このTemporalAmountの値を一意に定義する単位のリストを返します。 TemporalUnitsのリストは、実装クラスによって定義されます。 このリストは、getUnitsが呼び出された時点での単位のスナップショットであり、可変ではありません。 単位は、単位のデュレーションがもっとも長いものからもっとも短いものに向かって並んでいます。
      実装要件:
      単位のリストは、オブジェクトの状態を省略、重複、反復なしで完全かつ一意に表します。 単位は、デュレーションがもっとも長いものからもっとも短いものに向かって並んでいます。
      戻り値:
      TemporalUnitsのリスト、nullでない

    • addTo

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

      実装クラスにカプセル化されたロジックを使用して、指定された時間的オブジェクトに量を加算します。

      このメソッドを使用する等価な方法が2つあります。 1つ目はこのメソッドを直接呼び出すことです。 2つ目は、Temporal.plus(TemporalAmount)を使用する方法です。 

         // These two lines are equivalent, but the second approach is recommended
   dateTime = amount.addTo(dateTime);
   dateTime = dateTime.plus(adder);
      コード内での読みやすさが大幅に向上するため、2つ目のアプローチ(plus(TemporalAmount))を使用することをお薦めします。

      実装要件:
      実装は、入力オブジェクトを取り、それに加算する必要があります。 実装は、加算のロジックを定義し、そのロジックをドキュメント化します。 Temporal上の任意のメソッドを使用して時間的オブジェクトを問い合せ、加算を実行できます。 返されるオブジェクトは、入力オブジェクトと同じ識別可能な型を持つ必要があります。

      入力オブジェクトは変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の時間的オブジェクトに対して同等の安全な動作を提供します。

      入力の時間的オブジェクトは、ISO以外の暦体系にすることができます。 実装は、他の暦体系との互換性をドキュメント化したり、暦を問い合せることによってISO以外の時間的オブジェクトを拒否したりすることもできます。

      このメソッドは、複数のスレッドから並列に呼び出される可能性があります。 呼び出されるときは、スレッドセーフである必要があります。

      パラメータ:
      temporal - 量が加算される時間的オブジェクト、nullでない
      戻り値:
      加算を行った同じ識別可能な型のオブジェクト、nullでない
      例外:
      DateTimeException - 加算できない場合
      ArithmeticException - 数値のオーバーフローが発生した場合

    • subtractFrom

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

      実装クラスにカプセル化されたロジックを使用して、指定された時間的オブジェクトから量を減算します。

      このメソッドを使用する等価な方法が2つあります。 1つ目はこのメソッドを直接呼び出すことです。 2つ目は、Temporal.minus(TemporalAmount)を使用する方法です。 

         // these two lines are equivalent, but the second approach is recommended
   dateTime = amount.subtractFrom(dateTime);
   dateTime = dateTime.minus(amount);
      コード内での読みやすさが大幅に向上するため、2つ目のアプローチ(minus(TemporalAmount))を使用することをお薦めします。

      実装要件:
      実装は、入力オブジェクトを取り、それから減算する必要があります。 実装は、減算のロジックを定義し、そのロジックをドキュメント化します。 Temporal上の任意のメソッドを使用して時間的オブジェクトを問い合せ、減算を実行できます。 返されるオブジェクトは、入力オブジェクトと同じ識別可能な型を持つ必要があります。

      入力オブジェクトは変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の時間的オブジェクトに対して同等の安全な動作を提供します。

      入力の時間的オブジェクトは、ISO以外の暦体系にすることができます。 実装は、他の暦体系との互換性をドキュメント化したり、暦を問い合せることによってISO以外の時間的オブジェクトを拒否したりすることもできます。

      このメソッドは、複数のスレッドから並列に呼び出される可能性があります。 呼び出されるときは、スレッドセーフである必要があります。

      パラメータ:
      temporal - 量が減算される時間的オブジェクト、nullでない
      戻り値:
      減算を行った同じ識別可能な型のオブジェクト、nullでない
      例外:
      DateTimeException - 減算できない場合
      ArithmeticException - 数値のオーバーフローが発生した場合