hunt.time.temporal.TemporalAdjuster source code

1 /*
2  * hunt-time: A time library for D programming language.
3  *
4  * Copyright (C) 2015-2018 HuntLabs
5  *
6  * Website: https://www.huntlabs.net/
7  *
8  * Licensed under the Apache-2.0 License.
9  *
10  */
11 
12 module hunt.time.temporal.TemporalAdjuster;
13 
14 import hunt.time.Exceptions;
15 import hunt.time.temporal.Temporal;
16 
17 
18 /**
19  * Strategy for adjusting a temporal object.
20  * !(p)
21  * Adjusters are a key tool for modifying temporal objects.
22  * They exist to externalize the process of adjustment, permitting different
23  * approaches, as per the strategy design pattern.
24  * Examples might be an adjuster that sets the date avoiding weekends, or one that
25  * sets the date to the last day of the month.
26  * !(p)
27  * There are two equivalent ways of using a {@code TemporalAdjuster}.
28  * The first is to invoke the method on this interface directly.
29  * The second is to use {@link Temporal#_with(TemporalAdjuster)}:
30  * !(pre)
31  *   // these two lines are equivalent, but the second approach is recommended
32  *   temporal = thisAdjuster.adjustInto(temporal);
33  *   temporal = temporal._with(thisAdjuster);
34  * </pre>
35  * It is recommended to use the second approach, {@code _with(TemporalAdjuster)},
36  * as it is a lot clearer to read _in code.
37  * !(p)
38  * The {@link TemporalAdjusters} class contains a standard set of adjusters,
39  * available as static methods.
40  * These include:
41  * !(ul)
42  * !(li)finding the first or last day of the month
43  * !(li)finding the first day of next month
44  * !(li)finding the first or last day of the year
45  * !(li)finding the first day of next year
46  * !(li)finding the first or last day-of-week within a month, such as "first Wednesday _in June"
47  * !(li)finding the next or previous day-of-week, such as "next Thursday"
48  * </ul>
49  *
50  * @implSpec
51  * This interface places no restrictions on the mutability of implementations,
52  * however immutability is strongly recommended.
53  *
54  * @see TemporalAdjusters
55  * @since 1.8
56  */
57 // @FunctionalInterface
58 public interface TemporalAdjuster {
59 
60     /**
61      * Adjusts the specified temporal object.
62      * !(p)
63      * This adjusts the specified temporal object using the logic
64      * encapsulated _in the implementing class.
65      * Examples might be an adjuster that sets the date avoiding weekends, or one that
66      * sets the date to the last day of the month.
67      * !(p)
68      * There are two equivalent ways of using this method.
69      * The first is to invoke this method directly.
70      * The second is to use {@link Temporal#_with(TemporalAdjuster)}:
71      * !(pre)
72      *   // these two lines are equivalent, but the second approach is recommended
73      *   temporal = thisAdjuster.adjustInto(temporal);
74      *   temporal = temporal._with(thisAdjuster);
75      * </pre>
76      * It is recommended to use the second approach, {@code _with(TemporalAdjuster)},
77      * as it is a lot clearer to read _in code.
78      *
79      * @implSpec
80      * The implementation must take the input object and adjust it.
81      * The implementation defines the logic of the adjustment and is responsible for
82      * documenting that logic. It may use any method on {@code Temporal} to
83      * query the temporal object and perform the adjustment.
84      * The returned object must have the same observable type as the input object
85      * !(p)
86      * The input object must not be altered.
87      * Instead, an adjusted copy of the original must be returned.
88      * This provides equivalent, safe behavior for immutable and mutable temporal objects.
89      * !(p)
90      * The input temporal object may be _in a calendar system other than ISO.
91      * Implementations may choose to document compatibility with other calendar systems,
92      * or reject non-ISO temporal objects by {@link TemporalQueries#chronology() querying the chronology}.
93      * !(p)
94      * This method may be called from multiple threads _in parallel.
95      * It must be thread-safe when invoked.
96      *
97      * @param temporal  the temporal object to adjust, not null
98      * @return an object of the same observable type with the adjustment made, not null
99      * @throws DateTimeException if unable to make the adjustment
100      * @throws ArithmeticException if numeric overflow occurs
101      */
102     Temporal adjustInto(Temporal temporal);
103 
104 }