* This is the base interface type for amounts of time. * An amount is distinct from a date or time-of-day in that it is not tied * to any specific point on the time-line. *
* The amount can be thought of as a Map of {@code TemporalUnit} to long, * exposed via {@link #getUnits()} and {@link #get(TemporalUnit)}. * A simple case might have a single unit-value pair, such as "6 hours". * A more complex case may have multiple unit-value pairs, such as "7 years, 3 months and 5 days". *
* There are two common implementations. * {@link Period} is a date-based implementation, storing years, months and days. * {@link Duration} is a time-based implementation, storing seconds and * nanoseconds, but providing some access using other duration based units * such as minutes, hours and fixed 24-hour days. *
* This interface is a framework-level interface that should not be widely used * in application code. Instead, applications should create and pass around * instances of concrete types, such as {@code Period} and {@code Duration}. * *
* This adds to the specified temporal object using the logic * encapsulated in the implementing class. *
* There are two equivalent ways of using this method. * The first is to invoke this method directly. * The second is to use {@link Temporal#plus(TemporalAmount)}: *
* // these two lines are equivalent, but the second approach is recommended
* dateTime = amount.addTo(dateTime);
* dateTime = dateTime.plus(amount);
*
* It is recommended to use the second approach, {@code plus(TemporalAmount)},
* as it is a lot clearer to read in code.
*
* * The input object must not be altered. * Instead, an adjusted copy of the original must be returned. * This provides equivalent, safe behavior for immutable and mutable temporal objects. *
* The input temporal object may be in a calendar system other than ISO. * Implementations may choose to document compatibility with other calendar systems, * or reject non-ISO temporal objects by {@link TemporalQueries#chronology() querying the chronology}. *
* This method may be called from multiple threads in parallel. * It must be thread-safe when invoked. * * @param temporal the temporal object to adjust, not null * @return an object of the same observable type with the addition made, not null * @throws DateTimeException if unable to add * @throws ArithmeticException if numeric overflow occurs */ Temporal addTo(Temporal temporal); /** * Subtracts this object from the specified temporal object. *
* This adds to the specified temporal object using the logic * encapsulated in the implementing class. *
* There are two equivalent ways of using this method. * The first is to invoke this method directly. * The second is to use {@link Temporal#minus(TemporalAmount)}: *
* // these two lines are equivalent, but the second approach is recommended
* dateTime = amount.subtractFrom(dateTime);
* dateTime = dateTime.minus(amount);
*
* It is recommended to use the second approach, {@code minus(TemporalAmount)},
* as it is a lot clearer to read in code.
*
* * The input object must not be altered. * Instead, an adjusted copy of the original must be returned. * This provides equivalent, safe behavior for immutable and mutable temporal objects. *
* The input temporal object may be in a calendar system other than ISO. * Implementations may choose to document compatibility with other calendar systems, * or reject non-ISO temporal objects by {@link TemporalQueries#chronology() querying the chronology}. *
* This method may be called from multiple threads in parallel. * It must be thread-safe when invoked. * * @param temporal the temporal object to adjust, not null * @return an object of the same observable type with the subtraction made, not null * @throws DateTimeException if unable to subtract * @throws ArithmeticException if numeric overflow occurs */ Temporal subtractFrom(Temporal temporal); }