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 pseudocode:
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} = {[20110531], [20110701]}. 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 twostepaddition 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 noncommutativity and given the side conditions to compute the duration without remainder completely and to consider a minusoperation as equalizing a plusoperation (with t1dayofmonth <= 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 [20130129]. Surely, the signdependent 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.

String 
toString()
Yields a canonical representation which optionally starts with
the sign then continues with the letter "P" followed
by a commaseparated sequence of duration items.

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
getTotalLength, isNegative
public boolean contains(U unit)
TimeSpan
Queries 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 false
getPartialAmount(U)
public long getPartialAmount(U unit)
TimeSpan
Yields 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()
TimeSpan
Queries 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 false
TimeSpan.isEmpty()
,
TimeSpan.isNegative()
public boolean isEmpty()
TimeSpan
Queries 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 false
public String toString()
Yields a canonical representation which optionally starts with the sign then continues with the letter "P" followed by a commaseparated 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–2018. All rights reserved.