Module java.base
Package java.time.temporal

Interface TemporalAmount

所有已知的子接口:
ChronoPeriod
所有已知的实现类:
Duration, Period
public interface TemporalAmount
框架级接口，定义时间量，例如"6小时"、"8天"或"2年3个月"。

这是时间量的基本接口类型。时间量与日期或时间无关，因为它不与时间线上的任何特定点相关联。

时间量可以被视为TemporalUnit到long的Map，通过getUnits()和get(java.time.temporal.TemporalUnit)公开。一个简单的情况可能有一个单一的单位-值对，比如"6小时"。一个更复杂的情况可能有多个单位-值对，比如"7年，3个月和5天"。

有两种常见的实现。 Period是基于日期的实现，存储年、月和日。 Duration是基于时间的实现，存储秒和纳秒，但提供一些使用其他基于持续时间的单位（如分钟、小时和固定的24小时天）的访问。

这个接口是一个框架级接口，不应该在应用代码中广泛使用。相反，应用程序应该创建并传递具体类型的实例，如Period和Duration。

实现要求:
该接口对实现的可变性没有限制，但强烈建议使用不可变性。
自从:
1.8

  • Method Details

    • get

      long get(TemporalUnit unit)
      返回请求单位的值。从getUnits()返回的单位唯一定义TemporalAmount的值。必须为getUnits中列出的每个单位返回一个值。
      实现要求:
      实现可以声明支持未在getUnits()中列出的单位。通常，实现会将额外的单位定义为开发人员方便的转换。
      参数:
      unit - 要返回值的TemporalUnit
      返回:
      单位的长整型值
      抛出:
      DateTimeException - 如果无法获取单位的值
      UnsupportedTemporalTypeException - 如果不支持unit

    • getUnits

      List<TemporalUnit> getUnits()
      返回唯一定义此TemporalAmount值的单位列表。TemporalUnits列表由实现类定义。该列表是在调用getUnits时的单位快照，不可变。单位按照从最长持续时间到最短持续时间的顺序排列。
      实现要求:
      单位列表完全且唯一地表示对象的状态，没有遗漏、重叠或重复。单位按照从最长持续时间到最短持续时间的顺序排列。
      返回:
      TemporalUnits列表；不为null

    • addTo

      Temporal addTo(Temporal temporal)
      添加到指定的时间对象。

      使用实现类中封装的逻辑将数量添加到指定的时间对象。

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

         // 这两行是等效的，但建议使用第二种方法
   dateTime = amount.addTo(dateTime);
   dateTime = dateTime.plus(adder);
      建议使用第二种方法plus(TemporalAmount)，因为在代码中更清晰易读。
      实现要求:
      实现必须接受输入对象并对其进行添加。实现定义了添加的逻辑，并负责记录该逻辑。它可以使用Temporal上的任何方法来查询时间对象并执行添加。返回的对象必须具有与输入对象相同的可观察类型

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

      输入时间对象可能在ISO之外的日历系统中。实现可以选择记录与其他日历系统的兼容性，或通过查询年表拒绝非ISO时间对象。

      此方法可能会从多个线程并行调用。调用时必须是线程安全的。

      参数:
      temporal - 要将数量添加到的时间对象，不为null
      返回:
      添加后具有相同可观察类型的对象，不为null
      抛出:
      DateTimeException - 如果无法添加
      ArithmeticException - 如果发生数值溢出

    • subtractFrom

      Temporal subtractFrom(Temporal temporal)
      从指定的时间对象中减去此对象。

      使用实现类中封装的逻辑从指定的时间对象中减去数量。

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

         // 这两行是等效的，但建议使用第二种方法
   dateTime = amount.subtractFrom(dateTime);
   dateTime = dateTime.minus(amount);
      建议使用第二种方法minus(TemporalAmount)，因为在代码中更清晰易读。
      实现要求:
      实现必须接受输入对象并从中减去。实现定义了减法的逻辑，并负责记录该逻辑。它可以使用Temporal上的任何方法来查询时间对象并执行减法。返回的对象必须具有与输入对象相同的可观察类型

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

      输入时间对象可能在ISO之外的日历系统中。实现可以选择记录与其他日历系统的兼容性，或通过查询年表拒绝非ISO时间对象。

      此方法可能会从多个线程并行调用。调用时必须是线程安全的。

      参数:
      temporal - 要从中减去数量的时间对象，不为null
      返回:
      减去后具有相同可观察类型的对象，不为null
      抛出:
      DateTimeException - 如果无法减去
      ArithmeticException - 如果发生数值溢出