117 * <li>The combination day-of-week and day-of-month ("Friday the 13th") should not implement |
117 * <li>The combination day-of-week and day-of-month ("Friday the 13th") should not implement |
118 * this interface. It does not represent a contiguous set of fields, as days to weeks overlaps |
118 * this interface. It does not represent a contiguous set of fields, as days to weeks overlaps |
119 * days to months. |
119 * days to months. |
120 * </ul><p> |
120 * </ul><p> |
121 * |
121 * |
122 * <h3>Specification for implementors</h3> |
122 * @implSpec |
123 * This interface places no restrictions on the mutability of implementations, |
123 * This interface places no restrictions on the mutability of implementations, |
124 * however immutability is strongly recommended. |
124 * however immutability is strongly recommended. |
125 * All implementations must be {@link Comparable}. |
125 * All implementations must be {@link Comparable}. |
126 * |
126 * |
127 * @since 1.8 |
127 * @since 1.8 |
144 * date = date.with(Month.JULY); // most key classes implement TemporalAdjuster |
144 * date = date.with(Month.JULY); // most key classes implement TemporalAdjuster |
145 * date = date.with(lastDayOfMonth()); // static import from Adjusters |
145 * date = date.with(lastDayOfMonth()); // static import from Adjusters |
146 * date = date.with(next(WEDNESDAY)); // static import from Adjusters and DayOfWeek |
146 * date = date.with(next(WEDNESDAY)); // static import from Adjusters and DayOfWeek |
147 * </pre> |
147 * </pre> |
148 * |
148 * |
149 * <h3>Specification for implementors</h3> |
149 * @implSpec |
150 * Implementations must not alter either this object. |
150 * Implementations must not alter either this object. |
151 * Instead, an adjusted copy of the original must be returned. |
151 * Instead, an adjusted copy of the original must be returned. |
152 * This provides equivalent, safe behavior for immutable and mutable implementations. |
152 * This provides equivalent, safe behavior for immutable and mutable implementations. |
153 * <p> |
153 * <p> |
154 * The default implementation must behave equivalent to this code: |
154 * The default implementation must behave equivalent to this code: |
175 * In some cases, changing a field is not fully defined. For example, if the target object is |
175 * In some cases, changing a field is not fully defined. For example, if the target object is |
176 * a date representing the 31st January, then changing the month to February would be unclear. |
176 * a date representing the 31st January, then changing the month to February would be unclear. |
177 * In cases like this, the field is responsible for resolving the result. Typically it will choose |
177 * In cases like this, the field is responsible for resolving the result. Typically it will choose |
178 * the previous valid date, which would be the last valid day of February in this example. |
178 * the previous valid date, which would be the last valid day of February in this example. |
179 * |
179 * |
180 * <h3>Specification for implementors</h3> |
180 * @implSpec |
181 * Implementations must check and handle all fields defined in {@link ChronoField}. |
181 * Implementations must check and handle all fields defined in {@link ChronoField}. |
182 * If the field is supported, then the adjustment must be performed. |
182 * If the field is supported, then the adjustment must be performed. |
183 * If unsupported, then an {@code UnsupportedTemporalTypeException} must be thrown. |
183 * If unsupported, then an {@code UnsupportedTemporalTypeException} must be thrown. |
184 * <p> |
184 * <p> |
185 * If the field is not a {@code ChronoField}, then the result of this method |
185 * If the field is not a {@code ChronoField}, then the result of this method |
215 * </pre> |
215 * </pre> |
216 * <p> |
216 * <p> |
217 * Note that calling {@code plus} followed by {@code minus} is not guaranteed to |
217 * Note that calling {@code plus} followed by {@code minus} is not guaranteed to |
218 * return the same date-time. |
218 * return the same date-time. |
219 * |
219 * |
220 * <h3>Specification for implementors</h3> |
220 * @implSpec |
221 * Implementations must not alter either this object. |
221 * Implementations must not alter either this object. |
222 * Instead, an adjusted copy of the original must be returned. |
222 * Instead, an adjusted copy of the original must be returned. |
223 * This provides equivalent, safe behavior for immutable and mutable implementations. |
223 * This provides equivalent, safe behavior for immutable and mutable implementations. |
224 * <p> |
224 * <p> |
225 * The default implementation must behave equivalent to this code: |
225 * The default implementation must behave equivalent to this code: |
245 * <p> |
245 * <p> |
246 * In some cases, changing a field is not fully defined. For example, if the target object is |
246 * In some cases, changing a field is not fully defined. For example, if the target object is |
247 * a date representing the 31st January, then adding one month would be unclear. |
247 * a date representing the 31st January, then adding one month would be unclear. |
248 * In cases like this, the field is responsible for resolving the result. Typically it will choose |
248 * In cases like this, the field is responsible for resolving the result. Typically it will choose |
249 * the previous valid date, which would be the last valid day of February in this example. |
249 * the previous valid date, which would be the last valid day of February in this example. |
250 * <p> |
250 * |
251 * If the implementation represents a date-time that has boundaries, such as {@code LocalTime}, |
251 * @implSpec |
252 * then the permitted units must include the boundary unit, but no multiples of the boundary unit. |
|
253 * For example, {@code LocalTime} must accept {@code DAYS} but not {@code WEEKS} or {@code MONTHS}. |
|
254 * |
|
255 * <h3>Specification for implementors</h3> |
|
256 * Implementations must check and handle all units defined in {@link ChronoUnit}. |
252 * Implementations must check and handle all units defined in {@link ChronoUnit}. |
257 * If the unit is supported, then the addition must be performed. |
253 * If the unit is supported, then the addition must be performed. |
258 * If unsupported, then an {@code UnsupportedTemporalTypeException} must be thrown. |
254 * If unsupported, then an {@code UnsupportedTemporalTypeException} must be thrown. |
259 * <p> |
255 * <p> |
260 * If the unit is not a {@code ChronoUnit}, then the result of this method |
256 * If the unit is not a {@code ChronoUnit}, then the result of this method |
290 * </pre> |
286 * </pre> |
291 * <p> |
287 * <p> |
292 * Note that calling {@code plus} followed by {@code minus} is not guaranteed to |
288 * Note that calling {@code plus} followed by {@code minus} is not guaranteed to |
293 * return the same date-time. |
289 * return the same date-time. |
294 * |
290 * |
295 * <h3>Specification for implementors</h3> |
291 * @implSpec |
296 * Implementations must not alter either this object. |
292 * Implementations must not alter either this object. |
297 * Instead, an adjusted copy of the original must be returned. |
293 * Instead, an adjusted copy of the original must be returned. |
298 * This provides equivalent, safe behavior for immutable and mutable implementations. |
294 * This provides equivalent, safe behavior for immutable and mutable implementations. |
299 * <p> |
295 * <p> |
300 * The default implementation must behave equivalent to this code: |
296 * The default implementation must behave equivalent to this code: |
320 * <p> |
316 * <p> |
321 * In some cases, changing a field is not fully defined. For example, if the target object is |
317 * In some cases, changing a field is not fully defined. For example, if the target object is |
322 * a date representing the 31st March, then subtracting one month would be unclear. |
318 * a date representing the 31st March, then subtracting one month would be unclear. |
323 * In cases like this, the field is responsible for resolving the result. Typically it will choose |
319 * In cases like this, the field is responsible for resolving the result. Typically it will choose |
324 * the previous valid date, which would be the last valid day of February in this example. |
320 * the previous valid date, which would be the last valid day of February in this example. |
325 * <p> |
321 * |
326 * If the implementation represents a date-time that has boundaries, such as {@code LocalTime}, |
322 * @implSpec |
327 * then the permitted units must include the boundary unit, but no multiples of the boundary unit. |
|
328 * For example, {@code LocalTime} must accept {@code DAYS} but not {@code WEEKS} or {@code MONTHS}. |
|
329 * |
|
330 * <h3>Specification for implementors</h3> |
|
331 * Implementations must behave in a manor equivalent to the default method behavior. |
323 * Implementations must behave in a manor equivalent to the default method behavior. |
332 * <p> |
324 * <p> |
333 * Implementations must not alter either this object or the specified temporal object. |
325 * Implementations must not alter either this object or the specified temporal object. |
334 * Instead, an adjusted copy of the original must be returned. |
326 * Instead, an adjusted copy of the original must be returned. |
335 * This provides equivalent, safe behavior for immutable and mutable implementations. |
327 * This provides equivalent, safe behavior for immutable and mutable implementations. |
351 return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit)); |
343 return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit)); |
352 } |
344 } |
353 |
345 |
354 //----------------------------------------------------------------------- |
346 //----------------------------------------------------------------------- |
355 /** |
347 /** |
356 * Calculates the period between this temporal and another temporal in |
348 * Calculates the amount of time until another temporal in terms of the specified unit. |
357 * terms of the specified unit. |
349 * <p> |
358 * <p> |
350 * This calculates the amount of time between two temporal objects |
359 * This calculates the period between two temporals in terms of a single unit. |
351 * of the same type in terms of a single {@code TemporalUnit}. |
360 * The start and end points are {@code this} and the specified temporal. |
352 * The start and end points are {@code this} and the specified temporal. |
361 * The result will be negative if the end is before the start. |
353 * The result will be negative if the end is before the start. |
362 * For example, the period in hours between two temporal objects can be |
354 * For example, the period in hours between two temporal objects can be |
363 * calculated using {@code startTime.periodUntil(endTime, HOURS)}. |
355 * calculated using {@code startTime.periodUntil(endTime, HOURS)}. |
364 * <p> |
356 * <p> |
383 * long daysBetween = start.periodUntil(end, DAYS); |
375 * long daysBetween = start.periodUntil(end, DAYS); |
384 * // or alternatively |
376 * // or alternatively |
385 * long daysBetween = DAYS.between(start, end); |
377 * long daysBetween = DAYS.between(start, end); |
386 * </pre> |
378 * </pre> |
387 * |
379 * |
388 * <h3>Specification for implementors</h3> |
380 * @implSpec |
389 * Implementations must begin by checking to ensure that the input temporal |
381 * Implementations must begin by checking to ensure that the input temporal |
390 * object is of the same observable type as the implementation. |
382 * object is of the same observable type as the implementation. |
391 * They must then perform the calculation for all instances of {@link ChronoUnit}. |
383 * They must then perform the calculation for all instances of {@link ChronoUnit}. |
392 * An {@code UnsupportedTemporalTypeException} must be thrown for {@code ChronoUnit} |
384 * An {@code UnsupportedTemporalTypeException} must be thrown for {@code ChronoUnit} |
393 * instances that are unsupported. |
385 * instances that are unsupported. |
408 * </pre> |
400 * </pre> |
409 * <p> |
401 * <p> |
410 * Neither this object, nor the specified temporal, may be altered. |
402 * Neither this object, nor the specified temporal, may be altered. |
411 * |
403 * |
412 * @param endTemporal the end temporal, of the same type as this object, not null |
404 * @param endTemporal the end temporal, of the same type as this object, not null |
413 * @param unit the unit to measure the period in, not null |
405 * @param unit the unit to measure the amount in, not null |
414 * @return the period between this temporal object and the specified one in terms of |
406 * @return the amount of time between this temporal object and the specified one |
415 * the unit; positive if the specified object is later than this one, negative if |
407 * in terms of the unit; positive if the specified object is later than this one, |
416 * it is earlier than this one |
408 * negative if it is earlier than this one |
417 * @throws DateTimeException if the period cannot be calculated |
409 * @throws DateTimeException if the amount cannot be calculated |
418 * @throws UnsupportedTemporalTypeException if the unit is not supported |
410 * @throws UnsupportedTemporalTypeException if the unit is not supported |
419 * @throws ArithmeticException if numeric overflow occurs |
411 * @throws ArithmeticException if numeric overflow occurs |
420 */ |
412 */ |
421 long periodUntil(Temporal endTemporal, TemporalUnit unit); |
413 long periodUntil(Temporal endTemporal, TemporalUnit unit); |
422 |
414 |