public abstract class AbstractDuration<U extends ChronoUnit> extends java.lang.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
Note: The THIRD INVARIANCE
t1.plus(t1.until(t2)).minus(t1.until(t2)).equals(t1) == true
is often INVALID. A counter example where this invariance is
violated is given with following dates:
{t1, t2} = {[2011-05-31], [2011-07-01]}. But if the additional
condition is required that the day of month is never after 28th
of a month then this third invariance can be guaranteed.
Therefore it is recommended to avoid dates near the end of
month in addition.
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 (with t1-day-of-month <= 28):
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 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. 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.
|
java.lang.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 java.lang.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.
toString in class java.lang.Objectpublic 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)