模块 java.base
包 java.time.temporal

接口 TemporalAmount

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

这是时间量的基本接口类型。金额不同于日期或一天中的时间，因为它不依赖于时间线上的任何特定点。

数量可以被认为是 TemporalUnit 到 long 的 Map，通过 getUnits() 和 get(TemporalUnit) 暴露。一个简单的案例可能只有一个单位值对，例如“6 小时”。更复杂的情况可能有多个单位值对，例如“7 年 3 个月 5 天”。

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

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

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

  • 方法详情

    • get

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

    • getUnits

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

    • addTo

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

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

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

        // These two lines are equivalent, but the second approach is recommended
  dateTime = amount.addTo(dateTime);
  dateTime = dateTime.plus(adder);
      推荐使用第二种方法，plus(TemporalAmount)，代码读起来更清晰。
      实现要求：
      实现必须接受输入对象并添加到它。该实现定义了加法的逻辑并负责记录该逻辑。它可以使用 Temporal 上的任何方法来查询时间对象并执行加法。返回的对象必须与输入对象具有相同的可观察类型

      不得更改输入对象。相反，必须退回原件的调整副本。这为不可变和可变时间对象提供了等效的、安全的行为。

      输入的时间对象可以在除 ISO 之外的日历系统中。实现可以选择记录与其他日历系统的兼容性，或者通过 querying the chronology 拒绝非 ISO 时间对象。

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

      参数：
      temporal - 要添加金额的时间对象，不为空
      返回：
      添加后具有相同可观察类型的对象，不为空
      抛出：
      DateTimeException - 如果无法添加
      ArithmeticException - 如果发生数字溢出

    • subtractFrom

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

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

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

        // these two lines are equivalent, but the second approach is recommended
  dateTime = amount.subtractFrom(dateTime);
  dateTime = dateTime.minus(amount);
      推荐使用第二种方法，minus(TemporalAmount)，代码读起来更清晰。
      实现要求：
      实现必须获取输入对象并从中减去。该实现定义了减法的逻辑并负责记录该逻辑。它可以使用 Temporal 上的任何方法来查询时间对象并执行减法。返回的对象必须与输入对象具有相同的可观察类型

      不得更改输入对象。相反，必须退回原件的调整副本。这为不可变和可变时间对象提供了等效的、安全的行为。

      输入的时间对象可以在除 ISO 之外的日历系统中。实现可以选择记录与其他日历系统的兼容性，或者通过 querying the chronology 拒绝非 ISO 时间对象。

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

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