模块 java.base
包 java.time.temporal

接口 TemporalUnit

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

时间的测量是建立在单位上的，例如年、月、日、小时、分钟和秒。该接口的实现代表那些单元。

此接口的实例表示单位本身，而不是单位的数量。请参阅 Period 以了解以常用单位表示数量的类。

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

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

实现要求：
必须小心实现此接口以确保其他类正确运行。所有可以实例化的实现都必须是最终的、不可变的和线程安全的。建议尽可能使用枚举。
自从：
1.8

  • 方法总结

    修饰符和类型
    方法
    描述
    <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()
    获取单位的描述性名称。

  • 方法详情

    • getDuration

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

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

      有些单位可能会返回准确的持续时间，而其他单位可能会返回估计值。例如，由于夏令时可能发生变化，天数具有估计的持续时间。要确定持续时间是否为估计值，请使用 isDurationEstimated() 。

      返回：
      该单元的持续时间，可能是估计值，不为空

    • isDurationEstimated

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

      所有单位都有持续时间，但持续时间并不总是准确的。例如，由于夏令时可能发生变化，天数具有估计的持续时间。如果持续时间是估计值，则此方法返回 true，如果准确则返回 false。请注意，准确/估计会忽略闰秒。

      返回：
      如果持续时间是估计的，则为 true；如果准确，则为 false

    • isDateBased

      boolean isDateBased()
      检查此单位是否代表日期的组成部分。

      如果日期可以用来暗示日期的含义，则日期是基于时间的。它必须有一个 duration，它是标准一天长度的整数倍。注意，isDateBased()和isTimeBased()返回false都是有效的，比如表示36小时这样的单位时。

      返回：
      如果此单位是日期的组成部分，则为真

    • isTimeBased

      boolean isTimeBased()
      检查此单位是否代表时间的组成部分。

      如果一个单位可以用来暗示某个时间的意义，那么它就是基于时间的。它必须有一个 duration 可以划分为一个标准日的长度而没有余数。注意，isDateBased()和isTimeBased()返回false都是有效的，比如表示36小时这样的单位时。

      返回：
      如果此单位是时间的组成部分，则为真

    • isSupportedBy

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

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

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

      参数：
      temporal - 要检查的时间对象，不为空
      返回：
      如果支持该单位则为真

    • addTo

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

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

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

        // these two lines are equivalent, but the second approach is recommended
  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) ：

        // these two lines are equivalent
  between = thisUnit.between(start, end);
  between = start.until(end, thisUnit);
      应该根据哪个使代码更具可读性来做出选择。

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

       long daysBetween = DAYS.between(start, end);
 // or alternatively
 long daysBetween = start.until(end, DAYS);

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

      实现要求：
      实现必须首先使用 getClass() 检查两个时间是否具有相同的类型。如果他们不这样做，则必须通过调用 temporal1Inclusive.until(temporal2Exclusive, this) 获得结果。
      参数：
      temporal1Inclusive - 基本时间对象，不为空
      temporal2Exclusive - 另一个时间对象，独占，不为空
      返回：
      就本单位而言，temporal1Inclusive 和 temporal2Exclusive 之间的时间量；如果 temporal2Exclusive 晚于 temporal1Inclusive 则为正，如果早于 temporal1Inclusive 则为负
      抛出：
      DateTimeException - 如果无法计算金额，或者无法将结束时间转换为与开始时间相同的类型
      UnsupportedTemporalTypeException - 如果时间不支持该单位
      ArithmeticException - 如果发生数字溢出

    • toString

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

      这应该是复数和大写驼峰式，例如“天”或“分钟”。

      重写：
      toString 在类 Object 中
      返回：
      这个单位的名字，不为空