155 * Returns an adjusted object of the same type as this object with the adjustment made. |
155 * Returns an adjusted object of the same type as this object with the adjustment made. |
156 * <p> |
156 * <p> |
157 * This adjusts this date-time according to the rules of the specified adjuster. |
157 * This adjusts this date-time according to the rules of the specified adjuster. |
158 * A simple adjuster might simply set the one of the fields, such as the year field. |
158 * A simple adjuster might simply set the one of the fields, such as the year field. |
159 * A more complex adjuster might set the date to the last day of the month. |
159 * A more complex adjuster might set the date to the last day of the month. |
160 * A selection of common adjustments is provided in {@link TemporalAdjuster}. |
160 * A selection of common adjustments is provided in |
|
161 * {@link java.time.temporal.TemporalAdjusters TemporalAdjusters}. |
161 * These include finding the "last day of the month" and "next Wednesday". |
162 * These include finding the "last day of the month" and "next Wednesday". |
162 * The adjuster is responsible for handling special cases, such as the varying |
163 * The adjuster is responsible for handling special cases, such as the varying |
163 * lengths of month and leap years. |
164 * lengths of month and leap years. |
164 * <p> |
165 * <p> |
165 * Some example code indicating how and why this method is used: |
166 * Some example code indicating how and why this method is used: |
285 * Implementations must not alter this object. |
286 * Implementations must not alter this object. |
286 * Instead, an adjusted copy of the original must be returned. |
287 * Instead, an adjusted copy of the original must be returned. |
287 * This provides equivalent, safe behavior for immutable and mutable implementations. |
288 * This provides equivalent, safe behavior for immutable and mutable implementations. |
288 * |
289 * |
289 * @param amountToAdd the amount of the specified unit to add, may be negative |
290 * @param amountToAdd the amount of the specified unit to add, may be negative |
290 * @param unit the unit of the period to add, not null |
291 * @param unit the unit of the amount to add, not null |
291 * @return an object of the same type with the specified period added, not null |
292 * @return an object of the same type with the specified period added, not null |
292 * @throws DateTimeException if the unit cannot be added |
293 * @throws DateTimeException if the unit cannot be added |
293 * @throws UnsupportedTemporalTypeException if the unit is not supported |
294 * @throws UnsupportedTemporalTypeException if the unit is not supported |
294 * @throws ArithmeticException if numeric overflow occurs |
295 * @throws ArithmeticException if numeric overflow occurs |
295 */ |
296 */ |
357 * return (amountToSubtract == Long.MIN_VALUE ? |
358 * return (amountToSubtract == Long.MIN_VALUE ? |
358 * plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit)); |
359 * plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit)); |
359 * </pre> |
360 * </pre> |
360 * |
361 * |
361 * @param amountToSubtract the amount of the specified unit to subtract, may be negative |
362 * @param amountToSubtract the amount of the specified unit to subtract, may be negative |
362 * @param unit the unit of the period to subtract, not null |
363 * @param unit the unit of the amount to subtract, not null |
363 * @return an object of the same type with the specified period subtracted, not null |
364 * @return an object of the same type with the specified period subtracted, not null |
364 * @throws DateTimeException if the unit cannot be subtracted |
365 * @throws DateTimeException if the unit cannot be subtracted |
365 * @throws UnsupportedTemporalTypeException if the unit is not supported |
366 * @throws UnsupportedTemporalTypeException if the unit is not supported |
366 * @throws ArithmeticException if numeric overflow occurs |
367 * @throws ArithmeticException if numeric overflow occurs |
367 */ |
368 */ |
376 * This calculates the amount of time between two temporal objects |
377 * This calculates the amount of time between two temporal objects |
377 * in terms of a single {@code TemporalUnit}. |
378 * in terms of a single {@code TemporalUnit}. |
378 * The start and end points are {@code this} and the specified temporal. |
379 * The start and end points are {@code this} and the specified temporal. |
379 * The end point is converted to be of the same type as the start point if different. |
380 * The end point is converted to be of the same type as the start point if different. |
380 * The result will be negative if the end is before the start. |
381 * The result will be negative if the end is before the start. |
381 * For example, the period in hours between two temporal objects can be |
382 * For example, the amount in hours between two temporal objects can be |
382 * calculated using {@code startTime.until(endTime, HOURS)}. |
383 * calculated using {@code startTime.until(endTime, HOURS)}. |
383 * <p> |
384 * <p> |
384 * The calculation returns a whole number, representing the number of |
385 * The calculation returns a whole number, representing the number of |
385 * complete units between the two temporals. |
386 * complete units between the two temporals. |
386 * For example, the period in hours between the times 11:30 and 13:29 |
387 * For example, the amount in hours between the times 11:30 and 13:29 |
387 * will only be one hour as it is one minute short of two hours. |
388 * will only be one hour as it is one minute short of two hours. |
388 * <p> |
389 * <p> |
389 * There are two equivalent ways of using this method. |
390 * There are two equivalent ways of using this method. |
390 * The first is to invoke this method directly. |
391 * The first is to invoke this method directly. |
391 * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}: |
392 * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}: |