Module java.base
Package java.time.temporal

Interface TemporalUnit

所有已知的实现类:
ChronoUnit
public interface TemporalUnit
日期时间单位，如天或小时。

时间的测量建立在年、月、日、小时、分钟和秒等单位上。该接口的实现代表这些单位。

该接口的实例代表单位本身，而不是单位的数量。请参阅Period，它表示常见单位的数量。

最常用的单位在ChronoUnit中定义。更多单位在IsoFields中提供。应用程序代码也可以通过实现该接口来定义单位。

该单位使用双重分派。客户端代码调用类似LocalDateTime的日期时间上的方法，检查单位是否是ChronoUnit。如果是，则日期时间必须处理它。否则，方法调用将重新分派到该接口中匹配的方法。

实现要求:
必须谨慎实现该接口，以确保其他类能够正确运行。所有可实例化的实现必须是final、不可变且线程安全的。建议尽可能使用枚举。
自 JDK 版本:
1.8

  • Method Summary

    Modifier and Type
    Method
    Description
    <R extends Temporal>
    R
    addTo(R temporal, long amount)
    返回添加了指定周期的指定时间对象的副本。
    long
    between(Temporal temporal1Inclusive, Temporal temporal2Exclusive)
    计算两个时间对象之间的时间量。
    Duration
    getDuration()
    获取该单位的持续时间，可能是一个估计值。
    boolean
    isDateBased()
    检查该单位是否表示日期的一个组成部分。
    boolean
    isDurationEstimated()
    检查该单位的持续时间是否是一个估计值。
    default boolean
    isSupportedBy(Temporal temporal)
    检查指定时间对象是否支持该单位。
    boolean
    isTimeBased()
    检查该单位是否表示时间的一个组成部分。
    String
    toString()
    获取该单位的描述性名称。

  • Method Details

    • getDuration

      Duration getDuration()
      获取该单位的持续时间，可能是一个估计值。

      所有单位从该方法返回以标准纳秒为单位的持续时间。持续时间将是正数且非零。例如，一个小时的持续时间为60 * 60 * 1,000,000,000ns。

      一些单位可能返回准确的持续时间，而其他单位返回估计值。例如，由于夏令时更改的可能性，天具有估计的持续时间。要确定持续时间是否是估计值，请使用isDurationEstimated()。

      返回:
      该单位的持续时间，可能是一个估计值，非空

    • isDurationEstimated

      boolean isDurationEstimated()
      检查该单位的持续时间是否是一个估计值。

      所有单位都有一个持续时间，但持续时间并不总是准确的。例如，由于夏令时更改的可能性，天具有估计的持续时间。如果持续时间是估计值，则该方法返回true，如果是准确的，则返回false。请注意，准确/估计忽略闰秒。

      返回:
      如果持续时间是估计值，则返回true，如果是准确的，则返回false

    • isDateBased

      boolean isDateBased()
      检查该单位是否表示日期的一个组成部分。

      如果日期是基于时间的，则可以从日期中推断出含义。它必须具有一个是标准日长度的整数倍的持续时间。请注意，当表示类似36小时的单位时，isDateBased()和isTimeBased()都返回false是有效的。

      返回:
      如果该单位是日期的一个组成部分，则返回true

    • isTimeBased

      boolean isTimeBased()
      检查该单位是否表示时间的一个组成部分。

      如果单位是基于时间的，则可以从时间中推断出含义。它必须具有一个持续时间，该持续时间可以整除标准日的长度而不产生余数。请注意，当表示类似36小时的单位时，isDateBased()和isTimeBased()都返回false是有效的。

      返回:
      如果该单位是时间的一个组成部分，则返回true

    • isSupportedBy

      default boolean isSupportedBy(Temporal temporal)
      检查指定时间对象是否支持该单位。

      这将检查实现日期时间是否可以添加/减去该单位。这可用于避免抛出异常。

      此默认实现使用Temporal.plus(long, TemporalUnit)来派生值。

      参数:
      temporal - 要检查的时间对象，非空
      返回:
      如果该单位受支持，则返回true

    • addTo

      <R extends Temporal> R addTo(R temporal, long amount)
      返回添加了指定周期的指定时间对象的副本。

      添加的周期是该单位的倍数。例如，可以通过在表示“天”的实例上调用此方法，传递日期和周期“3”来将“3天”添加到日期。要添加的周期可能为负数，这相当于减法。

      有两种等效的使用方法。第一种是直接调用此方法。第二种是使用Temporal.plus(long, TemporalUnit)：

         // 这两行是等效的，但建议使用第二种方法
   temporal = thisUnit.addTo(temporal);
   temporal = temporal.plus(thisUnit);
      建议使用第二种方法plus(TemporalUnit)，因为在代码中更易读。

      实现应使用ChronoUnit中提供的单位或ChronoField中提供的字段执行任何查询或计算。如果该单位不受支持，则必须抛出UnsupportedTemporalTypeException。

      实现不得更改指定的时间对象。而是必须返回原始对象的调整副本。这为不可变和可变实现提供了等效的安全行为。

      类型参数:
      R - Temporal对象的类型
      参数:
      temporal - 要调整的时间对象，非空
      amount - 要添加的该单位的数量，正数或负数
      返回:
      调整后的时间对象，非空
      抛出:
      DateTimeException - 如果无法添加数量
      UnsupportedTemporalTypeException - 如果时间对象不支持该单位

    • between

      long between(Temporal temporal1Inclusive, Temporal temporal2Exclusive)
      计算两个时间对象之间的时间量。

      这将根据该单位计算时间量。起始点和结束点作为时间对象提供，并且必须是兼容类型。实现将在计算数量之前将第二个类型转换为第一个类型的实例。如果结束在开始之前，则结果将为负数。例如，可以使用HOURS.between(startTime, endTime)来计算两个时间对象之间的小时数。

      计算返回一个整数，表示两个时间对象之间完整单位的数量。例如，在11:30和13:29之间的小时数将仅为一个小时，因为它比两个小时短一分钟。

      有两种等效的使用方法。第一种是直接调用此方法。第二种是使用Temporal.until(Temporal, TemporalUnit)：

         // 这两行是等效的
   between = thisUnit.between(start, end);
   between = start.until(end, thisUnit);
      应根据哪种方法使代码更易读来进行选择。

      例如，此方法允许计算两个日期之间的天数：

        long daysBetween = DAYS.between(start, end);
  // 或者
  long daysBetween = start.until(end, DAYS);

      实现应使用ChronoUnit中提供的单位或ChronoField中提供的字段执行任何查询或计算。如果该单位不受支持，则必须抛出UnsupportedTemporalTypeException。实现不得更改指定的时间对象。

      实现要求:
      实现必须首先通过使用getClass()检查两个时间对象是否具有相同类型。如果它们不具有相同类型，则必须通过调用temporal1Inclusive.until(temporal2Exclusive, this)来获取结果。
      参数:
      temporal1Inclusive - 基础时间对象，非空
      temporal2Exclusive - 另一个时间对象，排他的，非空
      返回:
      temporal1Inclusive和temporal2Exclusive之间的时间量，以该单位表示；如果temporal2Exclusive晚于temporal1Inclusive，则为正数，如果早于则为负数
      抛出:
      DateTimeException - 如果无法计算数量，或者无法将结束时间转换为与开始时间相同的类型
      UnsupportedTemporalTypeException - 如果时间对象不支持该单位
      ArithmeticException - 如果发生数值溢出

    • toString

      String toString()
      获取该单位的描述性名称。

      应该是复数形式和首字母大写驼峰式，例如'Days'或'Minutes'。

      覆盖:
      toString 在类 Object中
      返回:
      该单位的名称，非空