compact1, compact2, compact3

java.time.temporal

Interface TemporalAmount

All Known Subinterfaces:

ChronoPeriod

所有已知实现类：

Duration ， Period

public interface TemporalAmount

定义一段时间的框架级界面，如“6小时”，“8天”或“2年3个月”。

这是时间量的基本界面类型。 数额与日期或时间不同，因为它不与时间线上的任何特定点相关。

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

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

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

实现要求：

此接口对实现的可变性没有任何限制，但是强烈建议不变性。

从以下版本开始：

1.8

方法摘要

Modifier and Type	Method and Description
Temporal	addTo(Temporal temporal) 添加到指定的时间对象。
long	get(TemporalUnit unit) 返回请求的单位的值。
List<TemporalUnit>	getUnits() 返回唯一定义此TemporalAmount值的单位列表。
Temporal	subtractFrom(Temporal temporal) 从指定的时间对象中减去此对象。

方法详细信息

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 - 将时间对象添加到金额，而不是null

结果

具有相同可观察类型的对象与添加，而不是null

异常

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 - 从时间对象中减去金额，而不是null

结果

相同可观察类型的对象与减法而不是null

异常

DateTimeException - 如果不能减去

ArithmeticException - 如果发生数字溢出