public abstract class AbstractDuration<U extends ChronoUnit> extends Object implements TimeSpan<U>
Defines a timespan using the default algorithm of Time4J.
Dependent on the sign of the duration there are three cases:
addTo() just yields
a given time point unaffected. Usually possible element overflows will be truncated such that the last valid time point will be determined. The rest of the discussion is about the gregorian calendar system and the addition of months and days, but is also applicable on other calendar systems. Examples in pseudo-code:
If the smallest existing time unit is used then following
invariants hold for the addition of a duration and the delta
between two time points. Let t1 and t2 be two time points with
t1 <= t2:
t1.plus(t1.until(t2)).equals(t2) == true
t2.until(t1).equals(t1.until(t2).inverse()) == true
Following condition only holds if either the day-of-month of any involved date is smaller than 28 or if a reversible metric is used:
t2.minus(t1.until(t2)).equals(t1) == true
Note: Usually the third invariance is NOT valid. A counter example is given with following dates: {t1, t2} = {[2011-03-31], [2011-07-01]} => P3M1D (using the standard metric) because of [2011-07-01] - P3M1D = [2011-03-30]. Example for using a reversible metric:
PlainDate d1 = PlainDate.of(2011, 3, 31);
PlainDate d2 = PlainDate.of(2011, 7, 1);
TimeMetric<CalendarUnit, Duration<CalendarUnit>> metric =
Duration.inYearsMonthsDays().reversible();
Duration<CalendarUnit> duration =
metric.between(d1, d2); // P2M31D
Duration<CalendarUnit> invDur =
metric.between(d2, d1); // -P2M31D
boolean firstInvariance = d1.plus(duration).equals(d2); // true
boolean secondInvariance = invDur.equals(duration.inverse()); // true
boolean thirdInvariance = d2.minus(duration).equals(d1); // true
About the mathematical background of specified algorithm: Note that the addition is not commutative, hence the order of addition steps will impact the result. For example a two-step-addition looks like:
In this context it is understandable that the order of addition steps is dependent on the sign of the duration. If the addition of a negative duration is interpreted as the reversal of the addition of a positive duration then following equivalent relation holds (paying attention to non-commutativity and given the side conditions to compute the duration without remainder completely and to consider a minus-operation as equalizing a plus-operation:
The permutation of addition steps is obvious. If Time4J had tried the alternative to first add the months and then the days even in case of a negative duration then we would have with
the situation that the mentioned third invariance would be violated even if the day of month is the first day of month: t2.minus(P1M30D) would not yield t1 but [2013-01-29]. Surely, the sign-dependent execution of addition steps cannot completely guarantee the third invariance in case of factory-created durations but it can guarantee it at least for all days in original date until the 28th of month.
Furthermore the specified algorithm ensures the second invariance
Duration([t1, t2]) = -Duration([t2, t1]) which expresses
a physical property of any duration as a directed temporal amount.
The second invariance means that the sign of a duration can only
qualify if the first time point is before the second time point or
other way around. The sign must not qualify the always positive length
of a duration itself however.
AbstractMetric,
addTo(TimePoint),
subtractFrom(TimePoint)TimeSpan.Item<U>| Constructor and Description |
|---|
AbstractDuration() |
| Modifier and Type | Method and Description |
|---|---|
<T extends TimePoint<? super U,T>> |
addTo(T time)
Adds this duration to given time point using the
default algorithm.
|
boolean |
contains(U unit)
Queries if given time unit is part of this time span.
|
long |
getPartialAmount(U unit)
Yields the partial amount associated with given time unit.
|
abstract AbstractDuration<U> |
inverse()
Creates a copy of this duration with the same amounts and
units but the inversed sign.
|
boolean |
isEmpty()
Queries if this time span is empty.
|
boolean |
isPositive()
Queries if this time span is positive.
|
<T extends TimePoint<? super U,T>> |
subtractFrom(T time)
Subtracts this duration from given time point using the
default algorithm.
|
String |
toString()
Yields a canonical representation which optionally starts with
the sign then continues with the letter "P" followed
by a comma-separated sequence of duration items.
|
equals, getClass, hashCode, notify, notifyAll, wait, wait, waitgetTotalLength, isNegativepublic boolean contains(U unit)
TimeSpanQueries if given time unit is part of this time span.
By default the implementation uses following expression:
for (Item<?> item : getTotalLength()) {
if (item.getUnit().equals(unit)) {
return (item.getAmount() > 0);
}
}
return false;
contains in interface TimeSpan<U extends ChronoUnit>unit - time unit to be asked (optional)true if exists else falsegetPartialAmount(U)public long getPartialAmount(U unit)
TimeSpanYields the partial amount associated with given time unit.
The method returns 0 if this time span does not contain
given time unit. In order to get the total length/amount of this
time span users have to evaluate the method TimeSpan.getTotalLength()
instead.
getPartialAmount in interface TimeSpan<U extends ChronoUnit>unit - time unit (optional)>= 0)public abstract AbstractDuration<U> inverse()
Creates a copy of this duration with the same amounts and units but the inversed sign.
public boolean isPositive()
TimeSpanQueries if this time span is positive.
A time span is positive if it is neither empty nor negative.
isPositive in interface TimeSpan<U extends ChronoUnit>true if positive and not empty else falseTimeSpan.isEmpty(),
TimeSpan.isNegative()public boolean isEmpty()
TimeSpanQueries if this time span is empty.
Per definition an empty time span has no items with a partial
amount different from 0.
isEmpty in interface TimeSpan<U extends ChronoUnit>true if empty else falsepublic String toString()
Yields a canonical representation which optionally starts with the sign then continues with the letter "P" followed by a comma-separated sequence of duration items.
public final <T extends TimePoint<? super U,T>> T addTo(T time)
Adds this duration to given time point using the default algorithm.
addTo in interface TimeSpan<U extends ChronoUnit>T - generic type of time pointtime - reference time point to add this time span toTimeSpan.subtractFrom(TimePoint)public final <T extends TimePoint<? super U,T>> T subtractFrom(T time)
Subtracts this duration from given time point using the default algorithm.
subtractFrom in interface TimeSpan<U extends ChronoUnit>T - generic type of time pointtime - reference time point to subtract this time span fromTimeSpan.addTo(TimePoint)Copyright © 2014–2021. All rights reserved.