模块  java.base
软件包  java.time.temporal

Interface Temporal

  • 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
    定义对时态对象的读写访问的框架级接口，例如日期，时间，偏移或这些的某种组合。

    这是日期，时间和偏移对象的基本接口类型，其完整性足以使用加号和减号进行操作。 它由那些可以提供和操作信息的类实现，如字段或queries 。 有关此接口的只读版本，请参见TemporalAccessor 。

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

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

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

    什么时候实施

    如果类符合三个条件，则应该实现此接口：

    • 它提供对日期/时间/偏移信息的访问，根据TemporalAccessor
    • 字段集从最大到最小是连续的
    • 字段集是完整的，因此不需要其他字段来定义所表示字段的有效值范围

    四个例子说明了这一点：

    • LocalDate实现此接口，因为它表示从天到永久连续的一组字段，并且不需要外部信息来确定每个日期的有效性。 因此，它能够正确实现正/负。
    • LocalTime实现此接口，因为它表示一组从nanos到几天内连续的字段，并且不需要外部信息来确定有效性。 通过环绕一天，它能够正确地实现加/减。
    • MonthDay ，即月份和日期的组合，未实现此接口。 虽然组合是连续的，但是在几年内从几天到几个月，组合没有足够的信息来定义日期的有效值范围。 因此，它无法正确实现加/减。
    • 星期几和星期几（“星期五13”）组合不应实现此界面。 它不代表一组连续的字段，因为几天到几周都会重复几天到几个月。
    实现要求：
    此接口对实现的可变性没有任何限制，但强烈建议使用不变性。 所有实现必须是Comparable 。
    从以下版本开始：
    1.8

    • 方法详细信息

      • 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)
        返回与此对象相同类型的调整对象，并进行调整。

        这将根据指定调整程序的规则调整此日期时间。 简单的调整器可能只是设置其中一个字段，例如年份字段。 更复杂的调整器可能会将日期设置为该月的最后一天。 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月将不清楚。 在这种情况下，该字段负责解析结果。 通常，它会选择上一个有效日期，这个日期是本例中2月的最后一个有效日期。

        实现要求：
        实现必须检查并处理ChronoField中定义的所有字段。 如果支持该字段，则必须执行调整。 如果不受支持，则必须抛出UnsupportedTemporalTypeException 。

        如果该字段是不是一个ChronoField ，则此方法的结果是通过调用获得TemporalField.adjustInto(Temporal, long)传递this作为第一个参数。

        实现不得更改此对象。 相反，必须返回原始的调整副本。 这为不可变和可变实现提供了等效的安全行为。

        参数
        字段 - 要在结果中设置的字段，不为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
        异常
        DateTimeException - 如果无法添加
        ArithmeticException - 如果发生数字溢出

      • plus

        Temporal plus​(long amountToAdd,
              TemporalUnit unit)
        返回与此对象具有相同类型的对象，并添加指定的句点。

        此方法返回基于此对象的新对象，并添加指定的时间段。 例如，在LocalDate ，这可用于添加若干年，月或日。 返回的对象将具有与此对象相同的可观察类型。

        在某些情况下，未完全定义更改字段。 例如，如果目标对象是表示1月31日的日期，则添加一个月将不清楚。 在这种情况下，该字段负责解析结果。 通常，它会选择上一个有效日期，这个日期是本例中2月的最后一个有效日期。

        实现要求：
        实现必须检查并处理ChronoUnit中定义的所有单元。 如果支持该单元，则必须执行添加。 如果不受支持，则必须抛出UnsupportedTemporalTypeException 。

        如果该单元不是ChronoUnit ，则此方法的结果是通过调用获得TemporalUnit.addTo(Temporal, long)传递this作为第一个参数。

        实现不得更改此对象。 相反，必须返回原始的调整副本。 这为不可变和可变实现提供了等效的安全行为。

        参数
        amountToAdd - 要添加的指定单位的数量，可能为负数
        unit - 要添加的金额的单位，而不是空
        结果
        添加了指定期间的相同类型的对象，而不是null
        异常
        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日的日期，则减去一个月将不清楚。 在这种情况下，该字段负责解析结果。 通常，它会选择上一个有效日期，这个日期是本例中2月的最后一个有效日期。

        实现要求：
        实现必须在与默认方法行为等效的庄园中运行。

        实现不得更改此对象。 相反，必须返回原始的调整副本。 这为不可变和可变实现提供了等效的安全行为。

        默认实现必须与此代码等效： 

          return (amountToSubtract == Long.MIN_VALUE ?
      plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
        参数
        amountToSubtract - 要减去的指定单位的数量，可能是负数
        unit - 要减去的金额的单位，而不是空
        结果
        减去指定时间段的相同类型的对象，不为null
        异常
        DateTimeException - 如果无法减去单位
        UnsupportedTemporalTypeException - 如果不支持该设备
        ArithmeticException - 如果发生数字溢出

      • until

        long until​(Temporal endExclusive,
           TemporalUnit unit)
        根据指定单位计算直到另一个时间的时间量。

        这将根据单个TemporalUnit计算两个临时对象之间的时间量。 起点和终点是this和指定的时间。 如果不同，则将终点转换为与起点相同的类型。 如果结束在开始之前，结果将是否定的。 例如，可以使用startTime.until(endTime, HOURS)计算两个时间对象之间的小时startTime.until(endTime, HOURS) 。

        计算返回一个整数，表示两个时间之间的完整单位数。 例如，11:30到13:29之间的小时数仅为1小时，因为它是两小时的一分钟。

        使用此方法有两种等效方法。 第一种是直接调用此方法。 第二个是使用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情况下是不支持的。

        如果该单元不是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);

        请注意，只有当两个临时对象具有由getClass()评估的完全相同的类型时，才必须调用单元的between方法。

        实现必须确保在调用此只读方法时不会更改任何可观察状态。

        参数
        endExclusive - 结束时间，独占，转换为与此对象相同的类型，而不是null
        unit - 计量金额的单位，而不是空
        结果
        以时间为单位的时间对象与指定对象之间的时间量; 如果指定的对象晚于此值，则为正数;如果早于此值，则为负数
        异常
        DateTimeException - 如果无法计算金额，或者结束时间不能转换为与此时间相同的类型
        UnsupportedTemporalTypeException - 如果不支持该装置
        ArithmeticException - 如果发生数字溢出