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

インタフェースTemporalUnit

既知のすべての実装クラス:
ChronoUnit
public interface TemporalUnit
日間、時間などの日付/時間の単位です。

時間の測定は単位(年、月、日、時、分、秒など)に基づいて行われます。 このインタフェースの実装は、これらの単位を表します。

このインタフェースのインスタンスは、単位の量ではなく、単位自体を表します。 一般的な単位によって量を表すクラスについては、Periodを参照してください。

もっとも一般的に使用される単位は、ChronoUnitで定義されます。 その他の単位は、IsoFieldsで提供されます。 アプリケーション・コードでこのインタフェースを実装することにより、単位を記述することもできます。

単位は、二重のディスパッチを使用して機能します。 クライアント・コードは、単位がChronoUnitかどうかを確認するLocalDateTimeのような日付/時間上のメソッドを呼び出します。 そうである場合、日付/時間はそれを処理する必要があります。 それ以外の場合、このメソッド呼出しはこのインタフェース内の一致するメソッドに再度ディスパッチされます。

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

  • メソッドのサマリー

    修飾子と型 メソッド 説明
    <R extends Temporal>
    R    		 addTo​(R temporal, long amount)
    指定された期間を加算して、指定された時間的オブジェクトのコピーを返します。
    long between​(Temporal temporal1Inclusive, Temporal temporal2Exclusive)
    2つの時間的オブジェクトの間の時間量を計算します。
    Duration getDuration()
    この単位のデュレーション(推定時間の場合もある)を取得します。
    boolean isDateBased()
    この単位が日付のコンポーネントを表すかどうかを確認します。
    boolean isDurationEstimated()
    単位のデュレーションが推定値かどうかをチェックします。
    default boolean isSupportedBy​(Temporal temporal)
    指定された時間的オブジェクトでこの単位がサポートされているかどうかを確認します。
    boolean isTimeBased()
    この単位が時間のコンポーネントを表すかどうかを確認します。
    String toString()
    単位のわかりやすい名前を取得します。

  • メソッドの詳細

    • getDuration

      Duration getDuration()
      この単位のデュレーション(推定時間の場合もある)を取得します。

      すべての単位は、このメソッドから標準のナノ秒で測定されたデュレーションを返します。 デュレーションは、ゼロ以外の正の数です。 たとえば、1時間は60 * 60 * 1,000,000,000nsのデュレーションを持っています。

      一部の単位は正確なデュレーションを返しますが、その他は推定値を返します。 たとえば、サマー・タイムの変更の可能性があるため、日は推定のデュレーションを持っています。 デュレーションが推定値かどうかを判定するには、isDurationEstimated()を使用します。

      戻り値:
      この単位のデュレーション。推定値の可能性がある。null以外

    • isDurationEstimated

      boolean isDurationEstimated()
      単位のデュレーションが推定値かどうかをチェックします。

      すべての単位はデュレーションを持っていますが、デュレーションは必ずしも正確ではありません。 たとえば、サマー・タイムの変更の可能性があるため、日は推定のデュレーションを持っています。 このメソッドは、デュレーションが推定値である場合にtrueを返し、正確な値である場合にfalseを返します。 正確か推定かの判定では、うるう秒は無視されます。

      戻り値:
      デュレーションが推定の場合はtrue、正確な場合はfalse

    • isDateBased

      boolean isDateBased()
      この単位が日付のコンポーネントを表すかどうかを確認します。

      日付が日付の意味を示すために使用される場合、その日付は時間ベースです。 標準の1日の長さの整数倍であるデュレーションを持っている必要があります。 たとえば36時間のような単位を表す場合、isDateBased()とisTimeBased()の両方がfalseを返すのは有効です。

      戻り値:
      この単位が日付のコンポーネントである場合はtrue

    • isTimeBased

      boolean isTimeBased()
      この単位が時間のコンポーネントを表すかどうかを確認します。

      単位が時間の意味を示すために使用される場合、その単位は時間ベースです。 標準の1日の長さで割り切れるデュレーションを持っている必要があります。 たとえば36時間のような単位を表す場合、isDateBased()とisTimeBased()の両方がfalseを返すのは有効です。

      戻り値:
      この単位が時間のコンポーネントである場合はtrue

    • isSupportedBy

      default boolean isSupportedBy​(Temporal temporal)
      指定された時間的オブジェクトでこの単位がサポートされているかどうかを確認します。

      これは、実装側の日付/時間がこの単位を加算/減算できることを確認します。 これを使用すると、例外のスローを回避できます。

      このデフォルトの実装は、Temporal.plus(long, TemporalUnit)を使用して値を求めます。

      パラメータ:
      temporal - チェックする時間的オブジェクト。null以外
      戻り値:
      単位がサポートされている場合はtrue

    • addTo

      <R extends Temporal> R addTo​(R temporal, long amount)
      指定された期間を加算して、指定された時間的オブジェクトのコピーを返します。

      加算される期間はこの単位の倍数です。 たとえば、このメソッドを使用して、ある日付に「3日」を加算することができます。それには、「日」を表すインスタンスに対してこのメソッドを呼び出し、日付と期間「3」を渡します。 加算する期間は負でもよく、それは減算と等価です。

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

         // these two lines are equivalent, but the second approach is recommended
   temporal = thisUnit.addTo(temporal);
   temporal = temporal.plus(thisUnit);
      2つ目の方法plus(TemporalUnit)の方がコードを読むときにわかりやすいため、これを使用することをお薦めします。

      実装では、問合せや計算を実行する場合、ChronoUnitで使用可能な単位、またはChronoFieldで使用可能なフィールドを使用するようにしてください。 単位がサポートされていない場合は、UnsupportedTemporalTypeExceptionをスローする必要があります。

      実装では、指定された時間的オブジェクトを変更してはいけません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。

      型パラメータ:
      R - Temporalオブジェクトの型
      パラメータ:
      temporal - 調整する時間的オブジェクト。null以外
      amount - 加算するこの単位の量。正または負
      戻り値:
      調整された時間的オブジェクト。null以外
      例外:
      DateTimeException - 量を加算できない場合
      UnsupportedTemporalTypeException - 単位が時間的オブジェクトによってサポートされない場合

    • between

      long between​(Temporal temporal1Inclusive, Temporal temporal2Exclusive)
      2つの時間的オブジェクトの間の時間量を計算します。

      これは、この単位で量を計算します。 開始点と終了点は時間的オブジェクトで指定され、互換性のある型でなければなりません。 実装では、2番目の型を最初の型のインスタンスに変換してから、量を計算します。 終了が開始より前である場合、結果は負になります。 たとえば、2つの時間的オブジェクト間の時間数での量は、HOURS.between(startTime, endTime)を使用して計算できます。

      計算では、2つの時間的オブジェクト間の完全な単位の数を表す整数を返します。 たとえば、時間11:30と13:29の間の量は、2時間には1分足りないため、時間数では1時間だけになります。

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

         // these two lines are equivalent
   between = thisUnit.between(start, end);
   between = start.until(end, thisUnit);
      この選択は、コードが読みやすくなるのはどちらかに基づいて行ってください。

      たとえば、このメソッドを使用すると、2つの日付間の日数を計算できます。 

        long daysBetween = DAYS.between(start, end);
  // or alternatively
  long daysBetween = start.until(end, DAYS);

      実装では、問合せや計算を実行する場合、ChronoUnitで使用可能な単位、またはChronoFieldで使用可能なフィールドを使用するようにしてください。 単位がサポートされていない場合は、UnsupportedTemporalTypeExceptionをスローする必要があります。 実装では、指定された時間的オブジェクトを変更してはいけません。

      実装要件:
      実装は、getClass()を使用して2つの時間的オブジェクトが同じ型を持っているかどうかを確認することから始める必要があります。 持っていない場合は、temporal1Inclusive.until(temporal2Exclusive, this)を呼び出して結果を取得する必要があります。
      パラメータ:
      temporal1Inclusive - ベースの時間的オブジェクト。null以外
      temporal2Exclusive - 他方の時間的オブジェクト(これを含まない)。null以外
      戻り値:
      temporal1Inclusiveとtemporal2Exclusiveの間の時間量をこの単位で表したもの。temporal2Exclusiveがtemporal1Inclusiveより後であれば正、前であれば負
      例外:
      DateTimeException - 量を計算できない場合、または終了の時間的オブジェクトを開始の時間的オブジェクトと同じ型に変換できない場合
      UnsupportedTemporalTypeException - 単位が時間的オブジェクトによってサポートされない場合
      ArithmeticException - 数値のオーバーフローが発生した場合

    • toString

      String toString()
      単位のわかりやすい名前を取得します。

      これは、「Days」や「Minutes」のように、複数形で先頭が大文字のキャメル・ケースにしてください。

      オーバーライド:
      toString 、クラス:  Object
      戻り値:
      この単位の名前、nullでない