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 | * Framework-level interface defining an amount of time, such as
|
11 | * "6 hours", "8 days" or "2 years and 3 months".
|
12 | *
|
13 | * This is the base interface type for amounts of time.
|
14 | * An amount is distinct from a date or time-of-day in that it is not tied
|
15 | * to any specific point on the time-line.
|
16 | *
|
17 | * The amount can be thought of as a {@link Map} of {@link TemporalUnit} to
|
18 | * `long`, exposed via {@link getUnits} and {@link get}.
|
19 | * A simple case might have a single unit-value pair, such as "6 hours".
|
20 | * A more complex case may have multiple unit-value pairs, such as
|
21 | * "7 years, 3 months and 5 days".
|
22 | *
|
23 | * There are two common implementations.
|
24 | * {@link Period} is a date-based implementation, storing years, months and days.
|
25 | * {@link Duration} is a time-based implementation, storing seconds and nanoseconds,
|
26 | * but providing some access using other duration based units such as minutes,
|
27 | * hours and fixed 24-hour days.
|
28 | *
|
29 | * This interface is a framework-level interface that should not be widely
|
30 | * used in application code. Instead, applications should create and pass
|
31 | * around instances of concrete types, such as {@link Period} and {@link Duration}.
|
32 | *
|
33 | * @interface
|
34 | */
|
35 | export class TemporalAmount {
|
36 | /**
|
37 | * Returns the value of the requested unit.
|
38 | * The units returned from {@link getUnits} uniquely define the
|
39 | * value of the {@link TemporalAmount}. A value must be returned
|
40 | * for each unit listed in {@link getUnits}.
|
41 | *
|
42 | * @implSpec
|
43 | * Implementations may declare support for units not listed by {@link getUnits}.
|
44 | * Typically, the implementation would define additional units
|
45 | * as conversions for the convenience of developers.
|
46 | *
|
47 | * @param {TemporalUnit} unit - the {@link TemporalUnit} for which to return the value
|
48 | * @return {number} the long value of the unit
|
49 | * @throws DateTimeException if a value for the unit cannot be obtained
|
50 | * @throws UnsupportedTemporalTypeException if the {@link unit} is not supported
|
51 | */
|
52 | // eslint-disable-next-line no-unused-vars
|
53 | get(unit) {
|
54 | abstractMethodFail('get');
|
55 | }
|
56 |
|
57 | /**
|
58 | * Returns the list of units uniquely defining the value of this TemporalAmount.
|
59 | * The list of {@link TemporalUnits} is defined by the implementation class.
|
60 | * The list is a snapshot of the units at the time {@link getUnits}
|
61 | * is called and is not mutable.
|
62 | * The units are ordered from longest duration to the shortest duration
|
63 | * of the unit.
|
64 | *
|
65 | * @implSpec
|
66 | * The list of units completely and uniquely represents the
|
67 | * state of the object without omissions, overlaps or duplication.
|
68 | * The units are in order from longest duration to shortest.
|
69 | *
|
70 | * @return {TemporalUnit[]} the List of {@link TemporalUnits}; not null
|
71 | */
|
72 | units() {
|
73 | abstractMethodFail('units');
|
74 | }
|
75 |
|
76 | /**
|
77 | * Adds to the specified temporal object.
|
78 | *
|
79 | * Adds the amount to the specified temporal object using the logic
|
80 | * encapsulated in the implementing class.
|
81 | *
|
82 | * There are two equivalent ways of using this method.
|
83 | * The first is to invoke this method directly.
|
84 | * The second is to use {@link Temporal#plus}:
|
85 | * <pre>
|
86 | * // These two lines are equivalent, but the second approach is recommended
|
87 | * dateTime = amount.addTo(dateTime);
|
88 | * dateTime = dateTime.plus(adder);
|
89 | * </pre>
|
90 | * It is recommended to use the second approach, {@link plus},
|
91 | * as it is a lot clearer to read in code.
|
92 | *
|
93 | * @implSpec
|
94 | * The implementation must take the input object and add to it.
|
95 | * The implementation defines the logic of the addition and is responsible for
|
96 | * documenting that logic. It may use any method on {@link Temporal} to
|
97 | * query the temporal object and perform the addition.
|
98 | * The returned object must have the same observable type as the input object
|
99 | *
|
100 | * The input object must not be altered.
|
101 | * Instead, an adjusted copy of the original must be returned.
|
102 | * This provides equivalent, safe behavior for immutable and mutable temporal objects.
|
103 | *
|
104 | * The input temporal object may be in a calendar system other than ISO.
|
105 | * Implementations may choose to document compatibility with other calendar systems,
|
106 | * or reject non-ISO temporal objects by querying the chronology (see {@link TemporalQueries#chronology}).
|
107 | *
|
108 | * This method may be called from multiple threads in parallel.
|
109 | * It must be thread-safe when invoked.
|
110 | *
|
111 | * @param {Temporal} temporal - the temporal object to add the amount to, not null
|
112 | * @return {Temporal} an object of the same observable type with the addition made, not null
|
113 | * @throws DateTimeException if unable to add
|
114 | * @throws ArithmeticException if numeric overflow occurs
|
115 | */
|
116 | // eslint-disable-next-line no-unused-vars
|
117 | addTo(temporal) {
|
118 | abstractMethodFail('addTo');
|
119 | }
|
120 |
|
121 | /**
|
122 | * Subtracts this object from the specified temporal object.
|
123 | *
|
124 | * Subtracts the amount from the specified temporal object using the logic
|
125 | * encapsulated in the implementing class.
|
126 | *
|
127 | * There are two equivalent ways of using this method.
|
128 | * The first is to invoke this method directly.
|
129 | * The second is to use {@link Temporal#minus}:
|
130 | * <pre>
|
131 | * // these two lines are equivalent, but the second approach is recommended
|
132 | * dateTime = amount.subtractFrom(dateTime);
|
133 | * dateTime = dateTime.minus(amount);
|
134 | * </pre>
|
135 | * It is recommended to use the second approach, {@link minus},
|
136 | * as it is a lot clearer to read in code.
|
137 | *
|
138 | * @implSpec
|
139 | * The implementation must take the input object and subtract from it.
|
140 | * The implementation defines the logic of the subtraction and is responsible for
|
141 | * documenting that logic. It may use any method on {@link Temporal} to
|
142 | * query the temporal object and perform the subtraction.
|
143 | * The returned object must have the same observable type as the input object
|
144 | *
|
145 | * The input object must not be altered.
|
146 | * Instead, an adjusted copy of the original must be returned.
|
147 | * This provides equivalent, safe behavior for immutable and mutable temporal objects.
|
148 | *
|
149 | * The input temporal object may be in a calendar system other than ISO.
|
150 | * Implementations may choose to document compatibility with other calendar systems,
|
151 | * or reject non-ISO temporal objects by querying the chronology (see {@link TemporalQueries#chronology}).
|
152 | *
|
153 | * This method may be called from multiple threads in parallel.
|
154 | * It must be thread-safe when invoked.
|
155 | *
|
156 | * @param {Temporal} temporal - the temporal object to subtract the amount from, not null
|
157 | * @return {Temporal} an object of the same observable type with the subtraction made, not null
|
158 | * @throws DateTimeException if unable to subtract
|
159 | * @throws ArithmeticException if numeric overflow occurs
|
160 | */
|
161 | // eslint-disable-next-line no-unused-vars
|
162 | subtractFrom(temporal) {
|
163 | abstractMethodFail('subtractFrom');
|
164 | }
|
165 |
|
166 | }
|