126 * This method returns true if the duration is an estimate and false if it is
127 * accurate. Note that accurate/estimated ignores leap seconds.
128 *
129 * @return true if the duration is estimated, false if accurate
130 */
131 boolean isDurationEstimated();
132
133 //-----------------------------------------------------------------------
134 /**
135 * Checks if this unit is supported by the specified temporal object.
136 * <p>
137 * This checks that the implementing date-time can add/subtract this unit.
138 * This can be used to avoid throwing an exception.
139 * <p>
140 * This default implementation derives the value using
141 * {@link Temporal#plus(long, TemporalUnit)}.
142 *
143 * @param temporal the temporal object to check, not null
144 * @return true if the unit is supported
145 */
146 public default boolean isSupportedBy(Temporal temporal) {
147 try {
148 temporal.plus(1, this);
149 return true;
150 } catch (RuntimeException ex) {
151 try {
152 temporal.plus(-1, this);
153 return true;
154 } catch (RuntimeException ex2) {
155 return false;
156 }
157 }
158 }
159
160 /**
161 * Returns a copy of the specified temporal object with the specified period added.
162 * <p>
163 * The period added is a multiple of this unit. For example, this method
164 * could be used to add "3 days" to a date by calling this method on the
165 * instance representing "days", passing the date and the period "3".
166 * The period to be added may be negative, which is equivalent to subtraction.
167 * <p>
168 * There are two equivalent ways of using this method.
169 * The first is to invoke this method directly.
170 * The second is to use {@link Temporal#plus(long, TemporalUnit)}:
171 * <pre>
172 * // these two lines are equivalent, but the second approach is recommended
173 * temporal = thisUnit.addTo(temporal);
174 * temporal = temporal.plus(thisUnit);
175 * </pre>
176 * It is recommended to use the second approach, {@code plus(TemporalUnit)},
177 * as it is a lot clearer to read in code.
178 * <p>
179 * Implementations should perform any queries or calculations using the units
180 * available in {@link ChronoUnit} or the fields available in {@link ChronoField}.
181 * If the unit is not supported a {@code DateTimeException} must be thrown.
182 * <p>
183 * Implementations must not alter the specified temporal object.
184 * Instead, an adjusted copy of the original must be returned.
185 * This provides equivalent, safe behavior for immutable and mutable implementations.
186 *
187 * @param <R> the type of the Temporal object
188 * @param temporal the temporal object to adjust, not null
189 * @param amount the amount of this unit to add, positive or negative
190 * @return the adjusted temporal object, not null
191 * @throws DateTimeException if the period cannot be added
192 */
193 <R extends Temporal> R addTo(R temporal, long amount);
194
195 //-----------------------------------------------------------------------
196 /**
197 * Calculates the period in terms of this unit between two temporal objects
198 * of the same type.
199 * <p>
200 * This calculates the period between two temporals in terms of this unit.
201 * The start and end points are supplied as temporal objects and must be
202 * of the same type.
203 * The result will be negative if the end is before the start.
204 * For example, the period in hours between two temporal objects can be
205 * calculated using {@code HOURS.between(startTime, endTime)}.
206 * <p>
207 * The calculation returns a whole number, representing the number of
208 * complete units between the two temporals.
209 * For example, the period in hours between the times 11:30 and 13:29
210 * will only be one hour as it is one minute short of two hours.
211 * <p>
212 * There are two equivalent ways of using this method.
213 * The first is to invoke this method directly.
214 * The second is to use {@link Temporal#periodUntil(Temporal, TemporalUnit)}:
215 * <pre>
216 * // these two lines are equivalent
217 * temporal = thisUnit.between(start, end);
218 * temporal = start.periodUntil(end, thisUnit);
219 * </pre>
220 * The choice should be made based on which makes the code more readable.
221 * <p>
222 * For example, this method allows the number of days between two dates to
223 * be calculated:
224 * <pre>
225 * long daysBetween = DAYS.between(start, end);
226 * // or alternatively
227 * long daysBetween = start.periodUntil(end, DAYS);
228 * </pre>
229 * <p>
230 * Implementations should perform any queries or calculations using the units
231 * available in {@link ChronoUnit} or the fields available in {@link ChronoField}.
232 * If the unit is not supported a {@code DateTimeException} must be thrown.
233 * Implementations must not alter the specified temporal objects.
234 *
235 * @param temporal1 the base temporal object, not null
236 * @param temporal2 the other temporal object, not null
237 * @return the period between datetime1 and datetime2 in terms of this unit;
238 * positive if datetime2 is later than datetime1, negative if earlier
239 * @throws DateTimeException if the period cannot be calculated
240 * @throws ArithmeticException if numeric overflow occurs
241 */
242 long between(Temporal temporal1, Temporal temporal2);
243
244 //-----------------------------------------------------------------------
245 /**
246 * Outputs this unit as a {@code String} using the name.
247 *
248 * @return the name of this unit, not null
249 */
250 @Override
251 String toString();
252
253 }
|
126 * This method returns true if the duration is an estimate and false if it is
127 * accurate. Note that accurate/estimated ignores leap seconds.
128 *
129 * @return true if the duration is estimated, false if accurate
130 */
131 boolean isDurationEstimated();
132
133 //-----------------------------------------------------------------------
134 /**
135 * Checks if this unit is supported by the specified temporal object.
136 * <p>
137 * This checks that the implementing date-time can add/subtract this unit.
138 * This can be used to avoid throwing an exception.
139 * <p>
140 * This default implementation derives the value using
141 * {@link Temporal#plus(long, TemporalUnit)}.
142 *
143 * @param temporal the temporal object to check, not null
144 * @return true if the unit is supported
145 */
146 default boolean isSupportedBy(Temporal temporal) {
147 try {
148 temporal.plus(1, this);
149 return true;
150 } catch (UnsupportedTemporalTypeException ex) {
151 return false;
152 } catch (RuntimeException ex) {
153 try {
154 temporal.plus(-1, this);
155 return true;
156 } catch (RuntimeException ex2) {
157 return false;
158 }
159 }
160 }
161
162 /**
163 * Returns a copy of the specified temporal object with the specified period added.
164 * <p>
165 * The period added is a multiple of this unit. For example, this method
166 * could be used to add "3 days" to a date by calling this method on the
167 * instance representing "days", passing the date and the period "3".
168 * The period to be added may be negative, which is equivalent to subtraction.
169 * <p>
170 * There are two equivalent ways of using this method.
171 * The first is to invoke this method directly.
172 * The second is to use {@link Temporal#plus(long, TemporalUnit)}:
173 * <pre>
174 * // these two lines are equivalent, but the second approach is recommended
175 * temporal = thisUnit.addTo(temporal);
176 * temporal = temporal.plus(thisUnit);
177 * </pre>
178 * It is recommended to use the second approach, {@code plus(TemporalUnit)},
179 * as it is a lot clearer to read in code.
180 * <p>
181 * Implementations should perform any queries or calculations using the units
182 * available in {@link ChronoUnit} or the fields available in {@link ChronoField}.
183 * If the unit is not supported an {@code UnsupportedTemporalTypeException} must be thrown.
184 * <p>
185 * Implementations must not alter the specified temporal object.
186 * Instead, an adjusted copy of the original must be returned.
187 * This provides equivalent, safe behavior for immutable and mutable implementations.
188 *
189 * @param <R> the type of the Temporal object
190 * @param temporal the temporal object to adjust, not null
191 * @param amount the amount of this unit to add, positive or negative
192 * @return the adjusted temporal object, not null
193 * @throws DateTimeException if the period cannot be added
194 * @throws UnsupportedTemporalTypeException if the unit is not supported by the temporal
195 */
196 <R extends Temporal> R addTo(R temporal, long amount);
197
198 //-----------------------------------------------------------------------
199 /**
200 * Calculates the period in terms of this unit between two temporal objects
201 * of the same type.
202 * <p>
203 * This calculates the period between two temporals in terms of this unit.
204 * The start and end points are supplied as temporal objects and must be
205 * of the same type.
206 * The result will be negative if the end is before the start.
207 * For example, the period in hours between two temporal objects can be
208 * calculated using {@code HOURS.between(startTime, endTime)}.
209 * <p>
210 * The calculation returns a whole number, representing the number of
211 * complete units between the two temporals.
212 * For example, the period in hours between the times 11:30 and 13:29
213 * will only be one hour as it is one minute short of two hours.
214 * <p>
215 * There are two equivalent ways of using this method.
216 * The first is to invoke this method directly.
217 * The second is to use {@link Temporal#periodUntil(Temporal, TemporalUnit)}:
218 * <pre>
219 * // these two lines are equivalent
220 * between = thisUnit.between(start, end);
221 * between = start.periodUntil(end, thisUnit);
222 * </pre>
223 * The choice should be made based on which makes the code more readable.
224 * <p>
225 * For example, this method allows the number of days between two dates to
226 * be calculated:
227 * <pre>
228 * long daysBetween = DAYS.between(start, end);
229 * // or alternatively
230 * long daysBetween = start.periodUntil(end, DAYS);
231 * </pre>
232 * <p>
233 * Implementations should perform any queries or calculations using the units
234 * available in {@link ChronoUnit} or the fields available in {@link ChronoField}.
235 * If the unit is not supported an {@code UnsupportedTemporalTypeException} must be thrown.
236 * Implementations must not alter the specified temporal objects.
237 *
238 * @param temporal1 the base temporal object, not null
239 * @param temporal2 the other temporal object, not null
240 * @return the period between temporal1 and temporal2 in terms of this unit;
241 * positive if temporal2 is later than temporal1, negative if earlier
242 * @throws DateTimeException if the period cannot be calculated
243 * @throws UnsupportedTemporalTypeException if the unit is not supported by the temporal
244 * @throws ArithmeticException if numeric overflow occurs
245 */
246 long between(Temporal temporal1, Temporal temporal2);
247
248 //-----------------------------------------------------------------------
249 /**
250 * Outputs this unit as a {@code String} using the name.
251 *
252 * @return the name of this unit, not null
253 */
254 @Override
255 String toString();
256
257 }
|