TemporalAmount

TemporalAmount is an interface in the java.time.temporal package that models an amount of time or date that can be added to or subtracted from temporal objects. It represents a quantity expressed in one or more units, such as years, months, days, seconds, or nanos, and is implemented by the standard classes Duration and Period. Duration covers time-based amounts (seconds and nanoseconds), while Period covers date-based amounts (years, months, and days). TemporalAmount is immutable and describes a fixed amount that can be applied to temporal instances.

Key aspects of TemporalAmount include its ability to express complex quantities and to be used with various Temporal types. Its API provides:

- getUnits(), which returns the list of TemporalUnit values that can express this amount.

- get(TemporalUnit), which returns the amount expressed in a particular unit.

- addTo(Temporal temporal) and subtractFrom(Temporal temporal), which apply the amount to a Temporal object and return a new Temporal result.

Usage examples are common in date-time arithmetic. For instance, a LocalDate can be advanced by a Period or a combination of Period and Duration by calling methods like plus(TemporalAmount). Since Period and Duration implement TemporalAmount, they can be composed or used directly to modify temporal values.

TemporalAmount serves as a core abstraction for arithmetic on temporal objects, decoupling the representation of an amount from the specific temporal type. It enables flexible and consistent manipulation of dates and times across the Java time API. See also Period, Duration, and ChronoUnit.