- すべてのスーパー・インタフェース:
TemporalAccessor
- 既知のすべてのサブインタフェース:
ChronoLocalDate
,ChronoLocalDateTime<D>
,ChronoZonedDateTime<D>
- 既知のすべての実装クラス:
HijrahDate
,Instant
,JapaneseDate
,LocalDate
,LocalDateTime
,LocalTime
,MinguoDate
,OffsetDateTime
,OffsetTime
,ThaiBuddhistDate
,Year
,YearMonth
,ZonedDateTime
public interface Temporal extends TemporalAccessor
これは、plusとminusを使用して操作できる完全な日付、時間およびオフセット・オブジェクトのベース・インタフェース型です。 これは、情報をフィールドまたは問合せとして提供および操作できるクラスによって実装されます。 このインタフェースの読取り専用バージョンについては、TemporalAccessor
を参照してください。
ほとんどの日時情報は、数値として表されます。 これらは、大きな値を処理するためにlong
で数値を保持するTemporalField
を使用してモデル化されています。 年、月および「月の日」はフィールドの簡単な例ですが、これらにはインスタントとオフセットも含まれています。 フィールドの標準セットについては、ChronoField
を参照してください。
日付/時間情報の2つの部分(chronologyおよびtime-zone)を数値で表すことはできません。 これらには、TemporalQuery
で定義されるstaticメソッドを使用する問合せ
を介してアクセスできます。
このインタフェースはフレームワークレベルのインタフェースであり、アプリケーション・コードで広範囲にわたって使用しないようにしてください。 かわりに、LocalDate
などの具象型のインスタンスを作成して使い回してください。 これには様々な理由がありますが、その1つはこのインタフェースの実装がISO以外の暦体系になっている可能性があることです。 この問題の詳細は、ChronoLocalDate
を参照してください。
実装するケース
3つの条件を満たすクラスでは、このインタフェースを実装する必要があります。
TemporalAccessor
のように、日付/時間/オフセット情報へのアクセスを提供する- フィールドのセットが最大から最小まで連続している
- フィールドのセットが完全であるため、他のフィールドを使用しなくても、表現されるフィールドの値の有効範囲を定義できる
これを、4つの例で説明します。
LocalDate
は、日から永遠まで連続し、外部情報がなくても各日付の有効性を判定できるフィールドのセットを表すため、このインタフェースを実装します。 したがって、plus/minusを正しく実装できます。LocalTime
は、ナノ秒から日まで連続し、外部情報がなくても有効性を判定できるフィールドのセットを表すため、このインタフェースを実装します。 したがって、日を折り返すことにより、plus/minusを正しく実装できます。MonthDay
(月と「月の日」の組合せ)は、このインタフェースを実装しません。 この組合せは、年内の日から月まで連続していますが、「月の日」の値の有効範囲を定義するのに十分な情報を備えていません。 したがって、plus/minusを正しく実装できません。- 曜日と「月の日」の組合せ(「13日の金曜日」)は、このインタフェースを実装できません。 これは、週に対する日と月に対する日が重複しているため、連続したフィールドのセットを表していません。
- 実装要件:
- このインタフェースは実装が可変であることを制限しませんが、不変にすることを強くお薦めします。 すべての実装は
Comparable
である必要があります。 - 導入されたバージョン:
- 1.8
-
メソッドのサマリー
修飾子と型 メソッド 説明 boolean
isSupported(TemporalUnit unit)
指定された単位がサポートされているかどうかをチェックします。default Temporal
minus(long amountToSubtract, TemporalUnit unit)
指定された期間を減算して、このオブジェクトと同じ型のオブジェクトを返します。default Temporal
minus(TemporalAmount amount)
量を減算して、このオブジェクトと同じ型のオブジェクトを返します。Temporal
plus(long amountToAdd, TemporalUnit unit)
このオブジェクトと同じ型のオブジェクトに指定された期間を追加したものを返します。default Temporal
plus(TemporalAmount amount)
このオブジェクトと同じ型のオブジェクトにある時間を追加したものを返します。long
until(Temporal endExclusive, TemporalUnit unit)
別のtemporalまでの時間量を指定された単位で計算します。default Temporal
with(TemporalAdjuster adjuster)
調整を行って、このオブジェクトと同じ型の調整済のオブジェクトを返します。Temporal
with(TemporalField field, long newValue)
指定されたフィールドを変更して、このオブジェクトと同じ型のオブジェクトを返します。インタフェース java.time.temporal.TemporalAccessorで宣言されたメソッド
get, getLong, isSupported, query, range
-
メソッドの詳細
-
isSupported
boolean isSupported(TemporalUnit unit)指定された単位がサポートされているかどうかをチェックします。これは、指定された単位をこの日付/時間に対して加算または減算できるかどうかをチェックします。 falseの場合、
plus(long, TemporalUnit)
およびminus
メソッドの呼び出しは、例外をスローします。- 実装要件:
- 実装は、
ChronoUnit
で定義されたすべての単位を確認して処理する必要があります。 単位がサポートされている場合はtrueを返し、それ以外の場合はfalseを返す必要があります。フィールドが
ChronoUnit
でない場合、このメソッドの結果は、引数としてthis
を渡してTemporalUnit.isSupportedBy(Temporal)
を呼び出すことによって取得されます。実装は、この読取り専用メソッドが呼び出されたときに識別可能な状態が変更されていないことを確認する必要があります。
- パラメータ:
unit
- チェックする単位、nullはfalseを返す- 戻り値:
- 単位を加算/減算できる場合はtrue、できない場合はfalse
-
with
default Temporal with(TemporalAdjuster adjuster)調整を行って、このオブジェクトと同じ型の調整済のオブジェクトを返します。これは、指定されたアジャスタのルールに従って、この日付/時間を調整します。 単純なアジャスタは、年フィールドなどの1つのフィールドだけを設定するなどです。 複雑なアジャスタは、日付を月の最後の日に設定するなどです。 一般的な調整の選択は、
TemporalAdjusters
で指定します。 これらには、「月の最後の日」や「次の水曜日」を見つけることが含まれます。 アジャスタは、さまざまな長さの月やうるう年などの特別なケースの処理を担当します。このメソッドを使用する方法と理由を示すいくつかのサンプル・コード:
date = date.with(Month.JULY); // most key classes implement TemporalAdjuster date = date.with(lastDayOfMonth()); // static import from Adjusters date = date.with(next(WEDNESDAY)); // static import from Adjusters and DayOfWeek
- 実装要件:
実装は、このオブジェクトまたは指定された時間的オブジェクトのどちらも変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。
デフォルト実装は、このコードと同等に動作する必要があります。
return adjuster.adjustInto(this);
- パラメータ:
adjuster
- 使用するアジャスタ、null以外- 戻り値:
- 指定された調整を行った同じ型のオブジェクト、null以外
- 例外:
DateTimeException
- 調整を実行できない場合ArithmeticException
- 数値のオーバーフローが発生した場合
-
with
Temporal with(TemporalField field, long newValue)指定されたフィールドを変更して、このオブジェクトと同じ型のオブジェクトを返します。これは、指定されたフィールドの値を変更して、このオブジェクトに基づいて新しいオブジェクトを返します。 たとえば、
LocalDate
で、これは年、月、または「月の日」を設定するために使用できます。 返されるオブジェクトはこのオブジェクトと同じ識別可能な型を持ちます。フィールドの変更が完全には定義されていない場合もあります。 たとえば、ターゲット・オブジェクトが1月31日を表す日付である場合、月を2月に変更することは不明な場合があります。 このようなケースでは、フィールドは結果の解決を担当します。 通常は1つ前の有効な日付が選択され、この例の場合は2月の最後の有効な日になります。
- 実装要件:
- 実装は、
ChronoField
で定義されたすべてのフィールドを確認して処理する必要があります。 フィールドがサポートされている場合は、調整を行う必要があります。 サポートされていない場合は、UnsupportedTemporalTypeException
をスローする必要があります。フィールドが
ChronoField
でない場合、このメソッドの結果は、第1引数としてthis
を渡してTemporalField.adjustInto(Temporal, long)
を呼び出すことによって取得されます。実装は、このオブジェクトを変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。
- パラメータ:
field
- 結果に設定するフィールド、null以外newValue
- 結果のフィールドの新しい値- 戻り値:
- 指定されたフィールドが設定された同じ型のオブジェクト、null以外
- 例外:
DateTimeException
- フィールドを設定できない場合UnsupportedTemporalTypeException
- フィールドがサポートされていない場合ArithmeticException
- 数値のオーバーフローが発生した場合
-
plus
default Temporal plus(TemporalAmount amount)このオブジェクトと同じ型のオブジェクトにある時間を追加したものを返します。これは、このtemporal (一時)を調整し、指定された量のルールに従って加算します。 この量は通常
Period
ですが、Duration
など、TemporalAmount
インタフェースを実装する他のどの型であってもかまいません。このメソッドを使用する方法と理由を示すいくつかのサンプル・コード:
date = date.plus(period); // add a Period instance date = date.plus(duration); // add a Duration instance date = date.plus(workingDays(6)); // example user-written workingDays method
plus
の後にminus
を呼び出しても、同じ日付/時間が返されることは保証されません。- 実装要件:
実装は、このオブジェクトまたは指定された時間的オブジェクトのどちらも変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。
デフォルト実装は、このコードと同等に動作する必要があります。
return amount.addTo(this);
- パラメータ:
amount
- 追加する量、null以外- 戻り値:
- 指定された調整を行った同じ型のオブジェクト、null以外
- 例外:
DateTimeException
- 加算できない場合ArithmeticException
- 数値のオーバーフローが発生した場合
-
plus
Temporal plus(long amountToAdd, TemporalUnit unit)このオブジェクトと同じ型のオブジェクトに指定された期間を追加したものを返します。このメソッドは、指定された期間を加算して、このオブジェクトに基づいて新しいオブジェクトを返します。 たとえば、
LocalDate
で、これは年、月、または日の数を加算するために使用できます。 返されるオブジェクトはこのオブジェクトと同じ識別可能な型を持ちます。フィールドの変更が完全には定義されていない場合もあります。 たとえば、ターゲット・オブジェクトが1月31日を表す日付である場合、1か月を加算することは不明な場合があります。 このようなケースでは、フィールドは結果の解決を担当します。 通常は1つ前の有効な日付が選択され、この例の場合は2月の最後の有効な日になります。
- 実装要件:
- 実装は、
ChronoUnit
で定義されたすべての単位を確認して処理する必要があります。 単位がサポートされている場合は、加算を行う必要があります。 サポートされていない場合は、UnsupportedTemporalTypeException
をスローする必要があります。単位が
ChronoUnit
でない場合、このメソッドの結果は、第1引数としてthis
を渡してTemporalUnit.addTo(Temporal, long)
を呼び出すことによって取得されます。実装は、このオブジェクトを変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。
- パラメータ:
amountToAdd
- 加算する指定された単位の量、負の場合もあるunit
- 加算する量の単位、nullでない- 戻り値:
- 指定された期間を加算した同じ型のオブジェクト、null以外
- 例外:
DateTimeException
- 単位を加算できない場合UnsupportedTemporalTypeException
- 単位がサポートされていない場合ArithmeticException
- 数値のオーバーフローが発生した場合
-
minus
default Temporal minus(TemporalAmount amount)量を減算して、このオブジェクトと同じ型のオブジェクトを返します。これは、このtemporal (一時)を調整し、指定された量のルールに従って減算します。 この量は通常
Period
ですが、Duration
など、TemporalAmount
インタフェースを実装する他のどの型であってもかまいません。このメソッドを使用する方法と理由を示すいくつかのサンプル・コード:
date = date.minus(period); // subtract a Period instance date = date.minus(duration); // subtract a Duration instance date = date.minus(workingDays(6)); // example user-written workingDays method
plus
の後にminus
を呼び出しても、同じ日付/時間が返されることは保証されません。- 実装要件:
実装は、このオブジェクトまたは指定された時間的オブジェクトのどちらも変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。
デフォルト実装は、このコードと同等に動作する必要があります。
return amount.subtractFrom(this);
- パラメータ:
amount
- 減算する量、null以外- 戻り値:
- 指定された調整を行った同じ型のオブジェクト、null以外
- 例外:
DateTimeException
- 減算ができない場合ArithmeticException
- 数値のオーバーフローが発生した場合
-
minus
default Temporal minus(long amountToSubtract, TemporalUnit unit)指定された期間を減算して、このオブジェクトと同じ型のオブジェクトを返します。このメソッドは、指定された期間を減算して、このオブジェクトに基づいて新しいオブジェクトを返します。 たとえば、
LocalDate
で、これは年、月、または日の数を減算するために使用できます。 返されるオブジェクトはこのオブジェクトと同じ識別可能な型を持ちます。フィールドの変更が完全には定義されていない場合もあります。 たとえば、ターゲットオブジェクトが3月31日を表す日付である場合、1か月を減算することは不明な場合があります。 このようなケースでは、フィールドは結果の解決を担当します。 通常は1つ前の有効な日付が選択され、この例の場合は2月の最後の有効な日になります。
- 実装要件:
- 実装は、デフォルトのメソッド動作と同等の方法で動作する必要があります。
実装は、このオブジェクトを変更できません。 かわりに、元のオブジェクトの調整済のコピーを返す必要があります。 これは、不変および可変の実装に安全で等価な動作を提供します。
デフォルト実装は、このコードと同等に動作する必要があります。
return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
- パラメータ:
amountToSubtract
- 減算する指定された単位の量、負の場合もあるunit
- 減算する量の単位、nullでない- 戻り値:
- 指定された期間が減算された同じ型のオブジェクト、null以外
- 例外:
DateTimeException
- 単位を減算できない場合UnsupportedTemporalTypeException
- 単位がサポートされていない場合ArithmeticException
- 数値のオーバーフローが発生した場合
-
until
long until(Temporal endExclusive, TemporalUnit unit)別のtemporalまでの時間量を指定された単位で計算します。これは、1つの
TemporalUnit
の形で2つの時間的オブジェクト間の時間量を計算します。 開始点と終了点はthis
と指定された時間的オブジェクトです。 終了点は、開始点と同じ型に変換されます(異なる場合)。 終了が開始より前である場合、結果は負になります。 たとえば、2つの時間的オブジェクト間の時間数は、startTime.until(endTime, HOURS)
を使用して計算できます。計算では、2つの時間的オブジェクト間の完全な単位の数を表す整数を返します。 たとえば、時間11:30と13:29の間の量は、2時間には1分足りないため、時間数では1時間だけになります。
このメソッドを使用する等価な方法が2つあります。 1つ目はこのメソッドを直接呼び出すことです。 2つ目は
TemporalUnit.between(Temporal, Temporal)
を使用することです。// these two lines are equivalent temporal = start.until(end, unit); temporal = unit.between(start, end);
この選択は、コードが読みやすくなるのはどちらかに基づいて行ってください。たとえば、このメソッドを使用すると、2つの日付間の日数を計算できます。
long daysBetween = start.until(end, DAYS); // or alternatively long daysBetween = DAYS.between(start, end);
- 実装要件:
- 実装は、入力の時間的オブジェクトが実装と同じ識別可能な型であることを確認することから始める必要があります。 次に、
ChronoUnit
のすべてのインスタンスの計算を実行する必要があります。 サポートされていないChronoUnit
インスタンスに対しては、UnsupportedTemporalTypeException
をスローする必要があります。単位が
ChronoUnit
でない場合、このメソッドの結果は、this
を1つ目の引数として、変換される入力temporal (一時)を2つ目の引数として渡してTemporalUnit.between(Temporal, Temporal)
を呼び出すことによって取得します。要約すると、実装はこの擬似コードと同等の方法で動作する必要があります。
// convert the end temporal to the same type as this class if (unit instanceof ChronoUnit) { // if unit is supported, then calculate and return result // else throw UnsupportedTemporalTypeException for unsupported units } return unit.between(this, convertedEndTemporal);
単位の
between
メソッドは、2つの時間的オブジェクトがgetClass()
によって評価されたまったく同じ型を持つ場合にのみ、呼び出す必要があります。実装は、この読取り専用メソッドが呼び出されたときに識別可能な状態が変更されていないことを確認する必要があります。
- パラメータ:
endExclusive
- このオブジェクトと同じ型に変換される、nullでない終了時間的オブジェクト(これを含まない)unit
- 量を測定する単位、null以外- 戻り値:
- この時間的オブジェクトと指定されたオブジェクト間の、指定された単位での時間量(指定されたオブジェクトがこのオブジェクトより後の場合は正、このオブジェクトより前の場合は負)
- 例外:
DateTimeException
- 量を計算できない場合、または終了時間的オブジェクトをこの時間的オブジェクトと同じ型に変換できない場合UnsupportedTemporalTypeException
- 単位がサポートされていない場合ArithmeticException
- 数値のオーバーフローが発生した場合
-