229 //----------------------------------------------------------------------- |
229 //----------------------------------------------------------------------- |
230 /** |
230 /** |
231 * Calculates the amount of time between two temporal objects. |
231 * Calculates the amount of time between two temporal objects. |
232 * <p> |
232 * <p> |
233 * This calculates the amount in terms of this unit. The start and end |
233 * This calculates the amount in terms of this unit. The start and end |
234 * points are supplied as temporal objects and must be of the same type. |
234 * points are supplied as temporal objects and must be of compatible types. |
|
235 * The implementation will convert the second type to be an instance of the |
|
236 * first type before the calculating the amount. |
235 * The result will be negative if the end is before the start. |
237 * The result will be negative if the end is before the start. |
236 * For example, the amount in hours between two temporal objects can be |
238 * For example, the amount in hours between two temporal objects can be |
237 * calculated using {@code HOURS.between(startTime, endTime)}. |
239 * calculated using {@code HOURS.between(startTime, endTime)}. |
238 * <p> |
240 * <p> |
239 * The calculation returns a whole number, representing the number of |
241 * The calculation returns a whole number, representing the number of |
262 * Implementations should perform any queries or calculations using the units |
264 * Implementations should perform any queries or calculations using the units |
263 * available in {@link ChronoUnit} or the fields available in {@link ChronoField}. |
265 * available in {@link ChronoUnit} or the fields available in {@link ChronoField}. |
264 * If the unit is not supported an {@code UnsupportedTemporalTypeException} must be thrown. |
266 * If the unit is not supported an {@code UnsupportedTemporalTypeException} must be thrown. |
265 * Implementations must not alter the specified temporal objects. |
267 * Implementations must not alter the specified temporal objects. |
266 * |
268 * |
267 * @param temporal1 the base temporal object, not null |
269 * @implSpec |
268 * @param temporal2 the other temporal object, not null |
270 * Implementations must begin by checking to if the two temporals have the |
269 * @return the amount of time between temporal1 and temporal2 in terms of this unit; |
271 * same type using {@code getClass()}. If they do not, then the result must be |
270 * positive if temporal2 is later than temporal1, negative if earlier |
272 * obtained by calling {@code temporal1Inclusive.until(temporal2Exclusive, this)}. |
271 * @throws DateTimeException if the amount cannot be calculated |
273 * |
|
274 * @param temporal1Inclusive the base temporal object, not null |
|
275 * @param temporal2Exclusive the other temporal object, exclusive, not null |
|
276 * @return the amount of time between temporal1Inclusive and temporal2Exclusive |
|
277 * in terms of this unit; positive if temporal2Exclusive is later than |
|
278 * temporal1Inclusive, negative if earlier |
|
279 * @throws DateTimeException if the amount cannot be calculated, or the end |
|
280 * temporal cannot be converted to the same type as the start temporal |
272 * @throws UnsupportedTemporalTypeException if the unit is not supported by the temporal |
281 * @throws UnsupportedTemporalTypeException if the unit is not supported by the temporal |
273 * @throws ArithmeticException if numeric overflow occurs |
282 * @throws ArithmeticException if numeric overflow occurs |
274 */ |
283 */ |
275 long between(Temporal temporal1, Temporal temporal2); |
284 long between(Temporal temporal1Inclusive, Temporal temporal2Exclusive); |
276 |
285 |
277 //----------------------------------------------------------------------- |
286 //----------------------------------------------------------------------- |
278 /** |
287 /** |
279 * Gets a descriptive name for the unit. |
288 * Gets a descriptive name for the unit. |
280 * <p> |
289 * <p> |