81 * The unit works using double dispatch. Client code calls methods on a date-time like |
81 * The unit works using double dispatch. Client code calls methods on a date-time like |
82 * {@code LocalDateTime} which check if the unit is a {@code ChronoUnit}. |
82 * {@code LocalDateTime} which check if the unit is a {@code ChronoUnit}. |
83 * If it is, then the date-time must handle it. |
83 * If it is, then the date-time must handle it. |
84 * Otherwise, the method call is re-dispatched to the matching method in this interface. |
84 * Otherwise, the method call is re-dispatched to the matching method in this interface. |
85 * |
85 * |
86 * <h3>Specification for implementors</h3> |
86 * @implSpec |
87 * This interface must be implemented with care to ensure other classes operate correctly. |
87 * This interface must be implemented with care to ensure other classes operate correctly. |
88 * All implementations that can be instantiated must be final, immutable and thread-safe. |
88 * All implementations that can be instantiated must be final, immutable and thread-safe. |
89 * It is recommended to use an enum where possible. |
89 * It is recommended to use an enum where possible. |
90 * |
90 * |
91 * @since 1.8 |
91 * @since 1.8 |
195 */ |
195 */ |
196 <R extends Temporal> R addTo(R temporal, long amount); |
196 <R extends Temporal> R addTo(R temporal, long amount); |
197 |
197 |
198 //----------------------------------------------------------------------- |
198 //----------------------------------------------------------------------- |
199 /** |
199 /** |
200 * Calculates the period in terms of this unit between two temporal objects |
200 * Calculates the amount of time between two temporal objects. |
201 * of the same type. |
201 * <p> |
202 * <p> |
202 * This calculates the amount in terms of this unit. The start and end |
203 * This calculates the period between two temporals in terms of this unit. |
203 * points are supplied as temporal objects and must be of the same type. |
204 * The start and end points are supplied as temporal objects and must be |
|
205 * of the same type. |
|
206 * The result will be negative if the end is before the start. |
204 * The result will be negative if the end is before the start. |
207 * For example, the period in hours between two temporal objects can be |
205 * For example, the amount in hours between two temporal objects can be |
208 * calculated using {@code HOURS.between(startTime, endTime)}. |
206 * calculated using {@code HOURS.between(startTime, endTime)}. |
209 * <p> |
207 * <p> |
210 * The calculation returns a whole number, representing the number of |
208 * The calculation returns a whole number, representing the number of |
211 * complete units between the two temporals. |
209 * complete units between the two temporals. |
212 * For example, the period in hours between the times 11:30 and 13:29 |
210 * For example, the amount in hours between the times 11:30 and 13:29 |
213 * will only be one hour as it is one minute short of two hours. |
211 * will only be one hour as it is one minute short of two hours. |
214 * <p> |
212 * <p> |
215 * There are two equivalent ways of using this method. |
213 * There are two equivalent ways of using this method. |
216 * The first is to invoke this method directly. |
214 * The first is to invoke this method directly. |
217 * The second is to use {@link Temporal#periodUntil(Temporal, TemporalUnit)}: |
215 * The second is to use {@link Temporal#periodUntil(Temporal, TemporalUnit)}: |
235 * If the unit is not supported an {@code UnsupportedTemporalTypeException} must be thrown. |
233 * If the unit is not supported an {@code UnsupportedTemporalTypeException} must be thrown. |
236 * Implementations must not alter the specified temporal objects. |
234 * Implementations must not alter the specified temporal objects. |
237 * |
235 * |
238 * @param temporal1 the base temporal object, not null |
236 * @param temporal1 the base temporal object, not null |
239 * @param temporal2 the other temporal object, not null |
237 * @param temporal2 the other temporal object, not null |
240 * @return the period between temporal1 and temporal2 in terms of this unit; |
238 * @return the amount of time between temporal1 and temporal2 in terms of this unit; |
241 * positive if temporal2 is later than temporal1, negative if earlier |
239 * positive if temporal2 is later than temporal1, negative if earlier |
242 * @throws DateTimeException if the period cannot be calculated |
240 * @throws DateTimeException if the amount cannot be calculated |
243 * @throws UnsupportedTemporalTypeException if the unit is not supported by the temporal |
241 * @throws UnsupportedTemporalTypeException if the unit is not supported by the temporal |
244 * @throws ArithmeticException if numeric overflow occurs |
242 * @throws ArithmeticException if numeric overflow occurs |
245 */ |
243 */ |
246 long between(Temporal temporal1, Temporal temporal2); |
244 long between(Temporal temporal1, Temporal temporal2); |
247 |
245 |