Temporal (Java Platform SE 8 )

All Superinterfaces:

TemporalAccessor

All Known Subinterfaces:

ChronoLocalDate ， ChronoLocalDateTime <D>， ChronoZonedDateTime <D>

所有已知实现类：

HijrahDate ， Instant ， JapaneseDate ， LocalDate ， LocalDateTime ， LocalTime ， MinguoDate ， OffsetDateTime ， OffsetTime ， ThaiBuddhistDate ， Year ， YearMonth ， ZonedDateTime
```
public interface Temporal
extends TemporalAccessor
```
定义对时间对象的读写访问的框架级接口，例如日期，时间，偏移或这些的一些组合。
这是日期，时间和偏移对象的基本界面类型，其完整性足以使用加和减操作。它由那些可以提供和操纵信息的类实现，如fields或queries 。有关此接口的只读版本，请参阅TemporalAccessor。

大多数日期和时间信息可以表示为一个数字。这些模型使用TemporalField进行建模，数字持有使用long处理大值。年份，月份和日期是字段的简单示例，但它们还包括即时和偏移量。有关标准的字段集，请参见ChronoField 。

两个日期/时间信息不能用数字表示， chronology和time-zone 。这些可以通过以下方式访问queries使用上定义的静态方法TemporalQuery 。

该接口是一个框架级接口，不应该在应用程序代码中广泛使用。相反，应用程序应该创建并传递具体类型的LocalDate ，例如LocalDate 。这有很多原因，其中一部分是该接口的实现可能在除ISO之外的日历系统中。有关这些问题的更全面的讨论，请参阅ChronoLocalDate 。

何时实施

如果一个类符合三个条件，则应该实现此接口：
- 它提供访问日期/时间/偏移量信息，根据TemporalAccessor
- 一组字段是从最大到最小的
- 该集合的字段是完整的，使得不需要其他字段来定义表示的字段的值的有效范围
四个例子说明如下：
- LocalDate实现了这个接口，因为它代表一组从天到永远连续的字段，并且不需要外部信息来确定每个日期的有效性。因此，可以正确地执行正/负。
- LocalTime实现了这个接口，因为它表示一组从nanos到几天的连续字段，并且不需要外部信息来确定有效性。它能够正确地执行正/负，通过包裹在一天。
- MonthDay ，结合月份和月份，不实现这个界面。虽然组合是连续的，从几天到几个月内，组合没有足够的信息来定义月日的有效价值范围。因此，无法正确执行正/负。
- 星期几和星期几（“星期五13号”）的组合不应该实现这个界面。它不代表连续的一组字段，因为几天到几个星期的重叠几天到几个月。
实现要求：

此接口对实现的可变性没有任何限制，但是强烈建议不变性。所有的实现必须是Comparable 。

从以下版本开始：

1.8

方法摘要

所有方法接口方法抽象方法 Default Methods
Modifier and Type	Method and Description
`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)` 根据指定的单位计算直到另一个时间的时间量。
`default Temporal`	`with(TemporalAdjuster adjuster)` 通过进行调整，返回与该对象相同类型的调整对象。
`Temporal`	`with(TemporalField field, long newValue)` 返回与该对象具有相同类型的对象，并更改指定的字段。

Methods inherited from interface java.time.temporal.TemporalAccessor
get, getLong, isSupported, query, range

- 方法详细信息
  - isSupported
```
boolean isSupported(TemporalUnit unit)
```
    检查指定的单位是否受支持。
    这将检查指定的单位是否可以添加到该日期时间或从该日期时间中减去。如果为false，那么调用plus(long, TemporalUnit)和minus方法将抛出异常。
    
    实现要求：
    
    实施必须检查和处理在ChronoUnit中定义的所有单位。如果单位得到支持，则必须返回true，否则返回false。
    如果该字段是不是一个ChronoUnit ，则此方法的结果是通过调用获得TemporalUnit.isSupportedBy(Temporal)传递this作为参数。
    
    当这个只读方法被调用时，实现必须确保没有可观察的状态被改变。
    
    参数
    
    unit - 要检查的单位，null返回false
    
    结果
    
    如果可以添加/减去单位，则为真，否则为false
  - with
```
default Temporal with(TemporalAdjuster adjuster)
```
    通过进行调整，返回与该对象相同类型的调整对象。
    这将根据指定的调整器的规则调整此日期时间。一个简单的调整器可能只是设置一个字段，如年份字段。更复杂的调整器可能会将日期设置为该月的最后一天。 TemporalAdjuster提供了一些常见的调整。这些包括找到“月的最后一天”和“下周三”。调整员负责处理特殊情况，如月份和闰年的不同长度。
    
    一些示例代码，指示如何和为什么使用此方法：
```
  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
    
    异常
    
    DateTimeException - 如果不能进行调整
    
    ArithmeticException - 如果发生数字溢出
  - with
```
Temporal with(TemporalField field,
              long newValue)
```
    返回与该对象具有相同类型的对象，并更改指定的字段。
    这将返回一个基于该对象的新对象，其中指定字段的值已更改。例如，在LocalDate ，这可以用于设置年，月或月的日期。返回的对象将具有与该对象相同的可观察类型。
    
    在某些情况下，更改字段尚未完全定义。例如，如果目标对象是代表1月31日的日期，则将月份更改为2月份将不清楚。在这种情况下，该领域负责解决结果。通常，它将选择先前的有效日期，这将是本例中最后一个有效的二月份。
    
    实现要求：
    
    实现必须检查和处理ChronoField中定义的所有字段。如果该字段被支持，则必须进行调整。如果不支持，那么必须抛出一个UnsupportedTemporalTypeException 。
    如果该字段不是ChronoField ，则通过调用TemporalField.adjustInto(Temporal, long) this作为第一个参数的this获得该方法的结果。
    
    实现不能改变这个对象。相反，必须退还原件的调整副本。这为不可变和可变的实现提供了相当的安全行为。
    
    参数
    
    field - 要在结果中设置的字段，不为null
    
    newValue - 结果中字段的新值
    
    结果
    
    与指定字段集相同类型的对象，不为null
    
    异常
    
    DateTimeException - 如果该字段无法设置
    
    UnsupportedTemporalTypeException - 如果该字段不被支持
    
    ArithmeticException - 如果发生数字溢出
  - plus
```
default Temporal plus(TemporalAmount amount)
```
    返回与此对象相同类型的对象，并添加一个金额。
    这调整这个时间，根据指定量的规则添加。量通常为Period ，而可以是任何其他类型的实现TemporalAmount接口，如Duration 。
    
    一些示例代码，指示如何和为什么使用此方法：
```
  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日的日期，则添加一个月将不清楚。在这种情况下，该领域负责解决结果。通常，它将选择先前的有效日期，这将是本例中最后一个有效的二月份。
    
    实现要求：
    
    实施必须检查和处理在ChronoUnit中定义的所有单位。如果单元被支持，则必须执行添加。如果不支持，那么必须抛出一个UnsupportedTemporalTypeException 。
    如果该单元不是ChronoUnit ，则此方法的结果是通过调用获得TemporalUnit.addTo(Temporal, long)传递this作为第一个参数。
    
    实现不能改变这个对象。相反，必须退还原件的调整副本。这为不可变和可变的实现提供了相当的安全行为。
    
    参数
    
    amountToAdd - 要添加的指定单位的数量，可能为负数
    
    unit - 添加期间的单位，不为空
    
    结果
    
    与指定期间相同类型的对象添加，不为空
    
    异常
    
    DateTimeException - 如果无法添加本机
    
    UnsupportedTemporalTypeException - 如果不支持本机
    
    ArithmeticException - 如果发生数字溢出
  - minus
```
default Temporal minus(TemporalAmount amount)
```
    返回与该对象相同类型的对象，并减去一个数量。
    这调整这个时间，根据指定量的规则减去。量通常为Period ，而可以是任何其他类型的实现TemporalAmount接口，如Duration 。
    
    一些示例代码，指示如何和为什么使用此方法：
```
  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
    
    异常
    
    DateTimeException - 如果不能进行减法
    
    ArithmeticException - 如果发生数字溢出
  - minus
```
default Temporal minus(long amountToSubtract,
                       TemporalUnit unit)
```
    返回与该对象相同类型的对象，并减去指定的时间段。
    该方法返回一个基于该对象的新对象，减去指定的时间段。例如，在LocalDate ，这可以用来减去几年，几个月或几天。返回的对象将具有与该对象相同的可观察类型。
    
    在某些情况下，更改字段尚未完全定义。例如，如果目标对象是代表3月31日的日期，则减去一个月将不清楚。在这种情况下，该领域负责解决结果。通常，它将选择先前的有效日期，这将是本例中最后一个有效的二月份。
    实现要求：
    实现必须以与默认方法行为相当的庄园行为。
    实现不能改变这个对象。相反，必须退还原件的调整副本。这为不可变和可变的实现提供了相当的安全行为。
    
    默认实现必须与此代码相同：
    
    return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
    参数
    
    amountToSubtract - 扣除指定单位的金额，可能为负数
    
    unit - 减去期间的单位，不为空
    
    结果
    
    与指定周期相同类型的对象减去，不为空
    
    异常
    
    DateTimeException - 如果不能减去单位
    
    UnsupportedTemporalTypeException - 如果不支持本机
    
    ArithmeticException - 如果发生数字溢出
  - until
```
long until(Temporal endExclusive,
           TemporalUnit unit)
```
    根据指定的单位计算直到另一个时间的时间量。
    这可以用单个TemporalUnit来计算两个时间对象之间的时间量。起点和终点是this和指定的时间。如果不同，终点被转换为与起始点相同的类型。如果结束在开始之前，结果将为负数。例如，可以使用startTime.until(endTime, HOURS)两个时间对象之间的小时数。
    
    计算返回一个整数，表示两个时间之间的完整单位数。例如，11时30分至13时29分之间的小时数将只有一个小时，因为它是两分钟不到两分钟。
    
    使用这种方法有两种等效的方法。第一个是直接调用这个方法。二是使用TemporalUnit.between(Temporal, Temporal) ：
```
  // these two lines are equivalent
   temporal = start.until(end, unit);
   temporal = unit.between(start, end); 
```
    应该根据这种做法进行选择，使代码更易读。
    例如，该方法允许计算两个日期之间的天数：
```
  long daysBetween = start.until(end, DAYS);
  // or alternatively
  long daysBetween = DAYS.between(start, end); 
```
    实现要求：
    实现必须首先检查以确保输入的时间对象与实现具有相同的可观察类型。然后他们必须对所有ChronoUnit的实例进行计算。对于UnsupportedTemporalTypeException支持的ChronoUnit实例，必须抛出UnsupportedTemporalTypeException。
    如果该单元不是ChronoUnit ，则此方法的结果是通过调用获得TemporalUnit.between(Temporal, Temporal)传递this作为第一个参数和转换后的输入时间作为第二个参数。
    
    总而言之，实现必须以与此伪代码相同的方式表现：
    
    // 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如果两个时态对象具有完全相同的类型的评估方法只能调用getClass() 。
    
    当这个只读方法被调用时，实现必须确保没有可观察的状态被改变。
    参数
    
    endExclusive - 结束时间，排他，转换为与此对象相同的类型，不为null
    
    unit - 衡量金额的单位，不为空
    
    结果
    
    在该时间对象与指定单位之间的时间量的单位; 如果指定的对象晚于此值，则为正数，如果比此更早，则为负数
    
    异常
    
    DateTimeException - 如果不能计算金额，或者结束时间不能转换为与该时间相同的类型
    
    UnsupportedTemporalTypeException - 如果不支持本机
    
    ArithmeticException - 如果发生数字溢出

Interface Temporal

何时实施

方法摘要

Methods inherited from interface java.time.temporal.TemporalAccessor

方法详细信息

isSupported

with

with

plus

plus

minus

minus

until