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
Following condition only holds if either the dayofmonth 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} = {[20110331], [20110701]} => P3M1D (using the standard metric) because of [20110701]  P3M1D = [20110330]. 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 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:
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 in case of factorycreated 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 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–2020. All rights reserved.