| 1 | /*
|
| 2 | * @copyright (c) 2016, Philipp Thürwächter & Pattrick Hüper
|
| 3 | * @copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos
|
| 4 | * @license BSD-3-Clause (see LICENSE in the root directory of this source tree)
|
| 5 | */
|
| 6 |
|
| 7 | import {abstractMethodFail} from '../assert';
|
| 8 |
|
| 9 | /**
|
| 10 | * Strategy for adjusting a temporal object.
|
| 11 | *
|
| 12 | * Adjusters are a key tool for modifying temporal objects.
|
| 13 | * They exist to externalize the process of adjustment, permitting different
|
| 14 | * approaches, as per the strategy design pattern.
|
| 15 | * Examples might be an adjuster that sets the date avoiding weekends, or one that
|
| 16 | * sets the date to the last day of the month.
|
| 17 | *
|
| 18 | * There are two equivalent ways of using a {@link TemporalAdjuster}.
|
| 19 | * The first is to invoke the method on this interface directly.
|
| 20 | * The second is to use {@link Temporal#with}:
|
| 21 | * <pre>
|
| 22 | * // these two lines are equivalent, but the second approach is recommended
|
| 23 | * temporal = thisAdjuster.adjustInto(temporal);
|
| 24 | * temporal = temporal.with(thisAdjuster);
|
| 25 | * </pre>
|
| 26 | * It is recommended to use the second approach, {@link with},
|
| 27 | * as it is a lot clearer to read in code.
|
| 28 | *
|
| 29 | * See {@link TemporalAdjusters} for a standard set of adjusters, including finding the
|
| 30 | * last day of the month.
|
| 31 | * Adjusters may also be defined by applications.
|
| 32 | *
|
| 33 | * ### Specification for implementors
|
| 34 | *
|
| 35 | * This interface places no restrictions on the mutability of implementations,
|
| 36 | * however immutability is strongly recommended.
|
| 37 | *
|
| 38 | * @interface
|
| 39 | */
|
| 40 | export class TemporalAdjuster {
|
| 41 |
|
| 42 | /**
|
| 43 | * Adjusts the specified temporal object.
|
| 44 | *
|
| 45 | * This adjusts the specified temporal object using the logic
|
| 46 | * encapsulated in the implementing class.
|
| 47 | * Examples might be an adjuster that sets the date avoiding weekends, or one that
|
| 48 | * sets the date to the last day of the month.
|
| 49 | *
|
| 50 | * There are two equivalent ways of using this method.
|
| 51 | * The first is to invoke this method directly.
|
| 52 | * The second is to use {@link Temporal#with}:
|
| 53 | * <pre>
|
| 54 | * // these two lines are equivalent, but the second approach is recommended
|
| 55 | * temporal = thisAdjuster.adjustInto(temporal);
|
| 56 | * temporal = temporal.with(thisAdjuster);
|
| 57 | * </pre>
|
| 58 | * It is recommended to use the second approach, {@link with},
|
| 59 | * as it is a lot clearer to read in code.
|
| 60 | *
|
| 61 | * ### Specification for implementors
|
| 62 | *
|
| 63 | * The implementation must take the input object and adjust it.
|
| 64 | * The implementation defines the logic of the adjustment and is responsible for
|
| 65 | * documenting that logic. It may use any method on {@link Temporal} to
|
| 66 | * query the temporal object and perform the adjustment.
|
| 67 | * The returned object must have the same observable type as the input object
|
| 68 | *
|
| 69 | * The input object must not be altered.
|
| 70 | * Instead, an adjusted copy of the original must be returned.
|
| 71 | * This provides equivalent, safe behavior for immutable and mutable temporal objects.
|
| 72 | *
|
| 73 | * The input temporal object may be in a calendar system other than ISO.
|
| 74 | * Implementations may choose to document compatibility with other calendar systems,
|
| 75 | * or reject non-ISO temporal objects by querying the chronology (see {@link TemporalQueries#chronology}).
|
| 76 | *
|
| 77 | * This method may be called from multiple threads in parallel.
|
| 78 | * It must be thread-safe when invoked.
|
| 79 | *
|
| 80 | * @param {Temporal} temporal the temporal object to adjust, not null
|
| 81 | * @return {Temporal} an object of the same observable type with the adjustment made, not null
|
| 82 | * @throws DateTimeException if unable to make the adjustment
|
| 83 | * @throws ArithmeticException if numeric overflow occurs
|
| 84 | *
|
| 85 | * @abstract
|
| 86 | */
|
| 87 | // eslint-disable-next-line no-unused-vars
|
| 88 | adjustInto(temporal){
|
| 89 | abstractMethodFail('adjustInto');
|
| 90 | }
|
| 91 |
|
| 92 | }
|