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

インタフェースTemporalField

既知のすべての実装クラス:
ChronoField
public interface TemporalField
月や分などの日時フィールド。

日付と時間は、時系列を人間にとって意味のある要素に分割するフィールドを使用して表現されます。 このインタフェースの実装は、これらのフィールドを表します。

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

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

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

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    <R extends Temporal>
    R
    adjustInto​(R temporal, long newValue)
    このフィールドの値が設定された、指定された時間的オブジェクトのコピーを返します。
    TemporalUnit
    getBaseUnit()
    フィールドの測定単位を取得します。
    default String
    getDisplayName​(Locale locale)
    要求されたロケールでのフィールドの表示名を取得します。
    long
    getFrom​(TemporalAccessor temporal)
    指定された時間的オブジェクトからこのフィールドの値を取得します。
    TemporalUnit
    getRangeUnit()
    フィールドの範囲を取得します。
    boolean
    isDateBased()
    このフィールドが日付のコンポーネントを表しているかどうかを確認します。
    boolean
    isSupportedBy​(TemporalAccessor temporal)
    このフィールドが時間的オブジェクトでサポートされているかどうかを確認します。
    boolean
    isTimeBased()
    このフィールドが時間のコンポーネントを表しているかどうかを確認します。
    ValueRange
    range()
    フィールドの有効値の範囲を取得します。
    ValueRange
    rangeRefinedBy​(TemporalAccessor temporal)
    時間的オブジェクトを使用して結果を絞り込むことにより、このフィールドの有効値の範囲を取得します。
    default TemporalAccessor
    resolve​(Map<TemporalField,​Long> fieldValues, TemporalAccessor partialTemporal, ResolverStyle resolverStyle)
    このフィールドを解決して、より簡単な代替または日付を提供します。
    String
    toString()
    そのフィールドのわかりやすい名前を取得します。

  • メソッドの詳細

    • getDisplayName

      default String getDisplayName​(Locale locale)
      要求されたロケールでのフィールドの表示名を取得します。

      ロケール用の表示名がない場合は、適切なデフォルトを返す必要があります。

      デフォルトの実装では、ロケールがnullでないことを確認し、toString()を返す必要があります。

      パラメータ:
      locale - 使用するロケール。null以外
      戻り値:
      ロケール用の表示名または適切なデフォルト。null以外

    • getBaseUnit

      TemporalUnit getBaseUnit()
      フィールドの測定単位を取得します。

      フィールドの単位は、範囲内で変化する期間です。 たとえば、フィールド「MonthOfYear」の単位は「Months」です。 getRangeUnit()も参照してください。

      戻り値:
      フィールドのベース単位を定義する単位、null以外

    • getRangeUnit

      TemporalUnit getRangeUnit()
      フィールドの範囲を取得します。

      フィールドの範囲は、フィールドがその範囲内で変化する期間です。 たとえば、フィールド「MonthOfYear」の範囲は「Years」です。 getBaseUnit()も参照してください。

      範囲がnullになることはありません。 たとえば、「Year」フィールドは「YearOfForever」の短縮形です。 したがって、その単位は「Years」で、範囲は「Forever」です。

      戻り値:
      フィールドの範囲を定義する単位、null以外

    • range

      ValueRange range()
      フィールドの有効値の範囲を取得します。

      すべてのフィールドはlong整数で表現できます。 このメソッドは、その値の有効範囲を記述するオブジェクトを返します。 このメソッドは、一般にISO-8601暦体系のみに適用されます。

      結果は有効な最小値と最大値を記述しているだけなので、それらを深く解釈しすぎないことが重要です。 たとえば、範囲内の値であっても、フィールドに対して無効な場合があります。

      戻り値:
      フィールドの有効値の範囲。null以外

    • isDateBased

      boolean isDateBased()
      このフィールドが日付のコンポーネントを表しているかどうかを確認します。

      EPOCH_DAYから導出できるフィールドは、日付ベースです。 たとえば「1週間のうちの分」のようなフィールドを表す場合、isDateBased()とisTimeBased()の両方がfalseを返すのは有効です。

      戻り値:
      このフィールドが日付のコンポーネントである場合はtrue

    • isTimeBased

      boolean isTimeBased()
      このフィールドが時間のコンポーネントを表しているかどうかを確認します。

      NANO_OF_DAYから導出できるフィールドは、時間ベースです。 たとえば「1週間のうちの分」のようなフィールドを表す場合、isDateBased()とisTimeBased()の両方がfalseを返すのは有効です。

      戻り値:
      このフィールドが時間のコンポーネントである場合はtrue

    • isSupportedBy

      boolean isSupportedBy​(TemporalAccessor temporal)
      このフィールドが時間的オブジェクトでサポートされているかどうかを確認します。

      これは、時間的オブジェクトのアクセサがこのフィールドをサポートしているかどうかを判定します。 これがfalseを返す場合、このフィールドについて時間的オブジェクトに問い合せることはできません。

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

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

      実装では、サポートされているかどうかを判定するために、ChronoFieldで使用可能なフィールドを使用するようにしてください。

      パラメータ:
      temporal - 問い合せる時間的オブジェクト。null以外
      戻り値:
      このフィールドについて日付/時間に問合せできる場合はtrue、そうでない場合はfalse

    • rangeRefinedBy

      ValueRange rangeRefinedBy​(TemporalAccessor temporal)
      時間的オブジェクトを使用して結果を絞り込むことにより、このフィールドの有効値の範囲を取得します。

      これは時間的オブジェクトを使用してフィールドの有効値の範囲を見つけます。 これは、range()に似ていますが、このメソッドは時間的オブジェクトを使用して結果を調整します。 たとえば、フィールドがDAY_OF_MONTHの場合、月の長さには28、29、30および31日の4つの可能性があるため、rangeメソッドは正確ではありません。 このメソッドを日付に使用すると、範囲は正確になり、これら4つのオプションのうち1つだけが返されます。

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

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

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

      パラメータ:
      temporal - 結果を絞り込むために使用される時間的オブジェクト。null以外
      戻り値:
      このフィールドの有効値の範囲。null以外
      例外:
      DateTimeException - フィールドの範囲を取得できない場合
      UnsupportedTemporalTypeException - フィールドが時間的オブジェクトによってサポートされない場合

    • getFrom

      long getFrom​(TemporalAccessor temporal)
      指定された時間的オブジェクトからこのフィールドの値を取得します。

      これは、このフィールドの値について時間的オブジェクトに問い合せます。

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

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

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

      パラメータ:
      temporal - 問い合せる時間的オブジェクト。null以外
      戻り値:
      このフィールドの値。null以外
      例外:
      DateTimeException - フィールドの値を取得できない場合
      UnsupportedTemporalTypeException - フィールドが時間的オブジェクトによってサポートされない場合
      ArithmeticException - 数値のオーバーフローが発生した場合

    • adjustInto

      <R extends Temporal> R adjustInto​(R temporal, long newValue)
      このフィールドの値が設定された、指定された時間的オブジェクトのコピーを返します。

      これは、指定された時間的オブジェクトに基づく、このフィールドの値が変更された新しい時間的オブジェクトを返します。 たとえば、LocalDateで、これは年、月、または「月の日」を設定するために使用できます。 返されるオブジェクトは、指定されたオブジェクトと同じ識別可能な型を持ちます。

      フィールドの変更が完全には定義されていない場合もあります。 たとえば、ターゲット・オブジェクトが1月31日を表す日付である場合、月を2月に変更することは不明な場合があります。 このようなケースでは、実装が結果の解決を担当します。 通常は1つ前の有効な日付が選択され、この例の場合は2月の最後の有効な日になります。

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

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

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

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

      型パラメータ:
      R - Temporalオブジェクトの型
      パラメータ:
      temporal - 調整する時間的オブジェクト。null以外
      newValue - フィールドの新しい値
      戻り値:
      調整された時間的オブジェクト。null以外
      例外:
      DateTimeException - フィールドを設定できない場合
      UnsupportedTemporalTypeException - フィールドが時間的オブジェクトによってサポートされない場合
      ArithmeticException - 数値のオーバーフローが発生した場合

    • resolve

      default TemporalAccessor resolve​(Map<TemporalField,​Long> fieldValues, TemporalAccessor partialTemporal, ResolverStyle resolverStyle)
      このフィールドを解決して、より簡単な代替または日付を提供します。

      このメソッドは、解析の解決フェーズで呼び出されます。 これは、アプリケーションで定義されたフィールドをより標準的なフィールド(ChronoField上のフィールドなど)や日付に単純化できるように設計されています。

      アプリケーションは、通常、このメソッドを直接呼び出さないでください。

      実装要件:
      実装が単純化できる(または他のフィールドと結合できる)フィールドを表している場合は、このメソッドを実装する必要があります。

      指定されたマップには、解析の現在の状態が含まれています。 マップは可変であり、このフィールドおよび関連するフィールドを解決するために変更する必要があります。 マップにこのフィールドが含まれる場合、このメソッドは解析中にのみ呼び出されます。したがって、実装はこのフィールドが存在することを前提としてください。

      フィールドの解決は、このフィールド(および場合によっては他のフィールド)の値を確認し、より単純な値(ChronoFieldなど)でマップを更新するか、または完全なChronoLocalDateを返すことで行われます。 解決に成功した場合、コードは解決されたすべてのフィールド(このフィールドを含む)をマップから削除する必要があります。

      たとえば、IsoFieldsクラスには四半期フィールドと「四半期の日」フィールドが含まれています。 そのクラスに含まれるこのメソッドの実装は、2つのフィールドとYEARを完全なLocalDateに解決します。 解決メソッドは、LocalDateを返す前に3つのフィールドをマップからすべて削除します。

      暦とゾーンの問合せを可能にするため、部分的に完全な時間的オブジェクトが使用されます。 一般には、暦のみが必要になります。 ゾーンと暦以外の項目の問合せは定義されていないため、それに依存してはいけません。 他のメソッド(get、getLong、range、isSupportedなど)の動作は予測不可能であり、結果は定義されていません。

      解決が可能なはずだが、データが無効である場合は、リゾルバ・スタイルを使用して適切な非厳密レベルを決定するようにしてください。その場合、DateTimeExceptionまたはArithmeticExceptionのスローが必要になることがあります。 解決が可能でない場合、解決メソッドはnullを返す必要があります。

      時間フィールドを解決すると、マップが変更され、nullが返されます。 日付フィールドを解決すると、通常はメソッドから日付が返され、解決されたフィールドを削除するためにマップが変更されます。 ただし、日付フィールドを、日付を生成できる他のChronoFieldインスタンス(EPOCH_DAYなど)に解決することも許容されます。

      必ずしもすべてのTemporalAccessor実装が戻り値として受け入れられるわけではありません。 このメソッドを呼び出す実装は、ChronoLocalDate、ChronoLocalDateTime、ChronoZonedDateTimeおよびLocalTimeを受け入れる必要があります。

      デフォルト実装はnullを返す必要があります。

      パラメータ:
      fieldValues - フィールドと値のマップ、更新可能、null以外
      partialTemporal - ゾーンと暦を問い合せるための部分的に完全な時間的オブジェクト。他の項目の問合せは未定義であり、推奨されない。null以外
      resolverStyle - 要求された解決のタイプ、null以外
      戻り値:
      解決された時間的オブジェクト。解決によってマップが変更されただけの場合、または解決が行われなかった場合はnull
      例外:
      ArithmeticException - 数値のオーバーフローが発生した場合
      DateTimeException - 解決時にエラーが発生した場合。 temporal上のフィールドがサポートされているかどうかを最初に確認せずに、そのフィールドを問い合せた場合は、これをスローしてはいけません。

    • toString

      String toString()
      そのフィールドのわかりやすい名前を取得します。

      フィールドがFOREVERの範囲を持っている(「Year」や「Era」など、ベース単位のみが指定されている)場合を除き、この名前のフォーマットは「BaseOfRange」(「MonthOfYear」など)となります。

      オーバーライド:
      toString 、クラス:  Object
      戻り値:
      フィールドの名前、nullでない