Class Duration<U extends IsoUnit>
 Type Parameters:
U
 generic type of time units
 All Implemented Interfaces:
Serializable
,TimeSpan<U>
ISO8601compatible duration between two time points.
Instances can be created by following factory methods:
of(long, U)
ofCalendarUnits(int, int, int)
ofClockUnits(int, int, int)
ofPositive()
(builderpattern)ofNegative()
(builderpattern)parsePeriod(String)
parseCalendarPeriod(String)
parseClockPeriod(String)
parseWeekBasedPeriod(String)
All instances are immutable, but changed copies can be created
by using the methods plus()
, with()
, union()
,
multipliedBy()
, abs()
and inverse()
. The time
units ClockUnit.MILLIS
and ClockUnit.MICROS
will
automatically normalized to nanoseconds. In every other case a normalization
must be explicitly triggered by with(Normalizer)
.
Note: The definition of an optional negative sign is not part of
ISO8061, but part of the XMLschemaspecification and defines the
position of two time points relative to each other. A manipulation of
the sign is possible with the method inverse()
.
The time arithmetic handles the addition of a duration to a time point and the subtraction of a duration from a time point as dependent on the sign of the duration as described in the standard algorithm of the super class.
 Author:
 Meno Hochschild
 See Also:
 Serialized Form

Nested Class Summary
Modifier and TypeClassDescriptionstatic class
Builder class for constructing a duration conforming to ISO8601 which consists of years, months, days and any wall time units.static class
Duration.Formatter<U extends IsoUnit>
Nonlocalized and userdefined format for durations based on a pattern containing some standard symbols and literals.Nested classes/interfaces inherited from interface net.time4j.engine.TimeSpan
TimeSpan.Item<U>

Field Summary
Modifier and TypeFieldDescriptionstatic Normalizer<CalendarUnit>
Normalizes the calendrical items of a duration on the base1 year = 12 months
 without converting the days to months.static Normalizer<ClockUnit>
Normalizes the wall time items of a duration on the base1 day = 24 hours
und1 hour = 60 minutes
and1 minute = 60 seconds
.static Normalizer<IsoUnit>
Normalizes the duration items on the base of1 year = 12 months
and1 day = 24 hours
and1 hour = 60 minutes
and1 minute = 60 seconds
 without converting days to months. 
Method Summary
Modifier and TypeMethodDescriptionabs()
Gets the absolute always nonnegative copy of this duration.static Normalizer<IsoUnit>
approximateHours(int steps)
Yields an approximate normalizer in steps of hours which finally uses years, months, days and rounded hours.static Normalizer<IsoUnit>
Creates a normalizer which yields an approximate duration based on the maximum relevant unit of the original duration (but not smaller than seconds).static Normalizer<IsoUnit>
LikeapproximateMaxUnitOnly()
but can create weekbased durations if the count of days is bigger than6
.static Normalizer<IsoUnit>
approximateMinutes(int steps)
Yields an approximate normalizer in steps of minutes which finally uses years, months, days, hours and rounded minutes.static Normalizer<IsoUnit>
approximateSeconds(int steps)
Yields an approximate normalizer in steps of seconds which finally uses years, months, days, hours, minutes and rounded seconds.static <U extends IsoUnit, T extends TimePoint<U, T>>
Comparator<Duration<? extends U>>comparator(T base)
Creates aComparator
which compares durations based on their lengths.static Comparator<Duration<ClockUnit>>
Obtains a comparator suitable for Durations based on clock units.compose(Duration<CalendarUnit> calendarPeriod, Duration<ClockUnit> clockPeriod)
Creates a composition of a calendar period and a clock period.boolean
Queries if this duration contains given time unit.boolean
Based on all stored duration items and the sign.static <U extends IsoUnit>
Duration.Formatter<U>Equivalent toDuration.Formatter.ofPattern(Class, String)
.static Duration.Formatter<IsoUnit>
Equivalent toDuration.Formatter.ofPattern(String)
.Short cut forTemporalType.THREETEN_DURATION.translate(threetenDuration)
.static Duration<CalendarUnit>
Short cut forTemporalType.THREETEN_PERIOD.translate(threetenPeriod)
.from(TemporalAmount threeten)
Tries to convert given temporal amount to a duration.long
getPartialAmount(IsoUnit unit)
Gets the partial amount associated with given time unit.Yields all containted time span items with amount and unit in the order from largest to smallest time units.int
hashCode()
Computes the hash code.static <U extends IsoUnit>
TimeMetric<U,Duration<U>>in(Collection<? extends U> units)
Constructs a metric for any kind of standard units in normalized form.static TimeMetric<IsoUnit,Duration<IsoUnit>>
Helps to evaluate the zonal duration between two timestamps and applies an offset correction if necessary.static <U extends IsoUnit>
TimeMetric<U,Duration<U>>in(U... units)
Constructs a metric for any kind of standard units in normalized form.static TimeMetric<ClockUnit,Duration<ClockUnit>>
Constructs a metric in hours, minutes, seconds and nanoseconds.inverse()
Gets a copy of this duration with reversed sign.static TimeMetric<IsoDateUnit,Duration<IsoDateUnit>>
Constructs a metric in weekbased years, weeks and days.static TimeMetric<CalendarUnit,Duration<CalendarUnit>>
Constructs a metric in years, months and days.boolean
Queries if this time span is negative.multipliedBy(int factor)
Multiplies all partial amounts of this duration by given factor.of(long amount, U unit)
Creates a new duration which only knows one unit.static Duration<CalendarUnit>
ofCalendarUnits(int years, int months, int days)
Creates a positive duration in years, months and days.ofClockUnits(int hours, int minutes, int seconds)
Creates a positive duratioon in hours, minutes and seconds.static Duration.Builder
Konstructs a new negative duration for combined date and time items by applying the builder pattern.static Duration.Builder
Konstructs a new positive duration for combined date and time items by applying the builder pattern.ofZero()
Gets an empty duration without units.static Duration<CalendarUnit>
parseCalendarPeriod(String period)
Parses a canonical representation with only date units to a calendrical duration.parseClockPeriod(String period)
Parses a canonical representation with only wall time units to a timeonly duration.parsePeriod(String period)
Parses a canonical representation to a duration.static Duration<IsoDateUnit>
parseWeekBasedPeriod(String period)
Parses a canonical representation with only weekbased units (Y, W and D) to a calendrical duration where years are interpreted as weekbased years with either 364 days (= 52 weeks) or 371 days (= 53 weeks).Gets a copy of this duration where given amount will be added to the partial amount of this duration in given unit.Creates a duration as union of this instance and given timespan where partial amounts of equal units will be summed up.Helps to sum up durations of a stream.Extracts a new duration with all contained calendar units only.Extracts a new duration with all contained clock units only.Extracts a new duration with all contained clock units only.toString()
Gets a canonical representation which optionally starts with a negative sign then continues with the letter "P", followed by a sequence of alphanumerical chars similar to the definition given in ISO8601.Gets a canonical representation which starts with the letter "P", followed by a sequence of alphanumerical chars as defined in ISO8601.Gets a canonical representation conforming to XMLschema which optionally starts with a negative sign then continues with the letter "P", followed by a sequence of alphanumerical chars similar to the definition given in ISO8601.Converts this duration to a general temporal amount compatible with JSR310spec.truncatedTo(U unit)
Sets all duration parts to zero whose unit has a smaller length than given unit.Creates a duration as union of this instance and given timespan where partial amounts of equal units will be summed up.Gets a copy of this duration where the partial amount associated with given time unit is changed.with(Normalizer<U> normalizer)
Normalizes this duration by given normalizer.Methods inherited from class net.time4j.engine.AbstractDuration
addTo, isEmpty, isPositive, subtractFrom

Field Details

STD_PERIOD
Normalizes the duration items on the base of
1 year = 12 months
and1 day = 24 hours
and1 hour = 60 minutes
and1 minute = 60 seconds
 without converting days to months.Attention: Timezonedependent changes of length of day or leapseconds are ignored. That is why this normalization should only be applied on ISOtimestamps without timezone reference. Only time units of enum types
CalendarUnit
andClockUnit
will be normalized.Weeks will be normalized to days if weeks do not represent the only calendrical duration items.
 See Also:
PlainTimestamp.normalize(TimeSpan)

STD_CALENDAR_PERIOD
Normalizes the calendrical items of a duration on the base
1 year = 12 months
 without converting the days to months.Weeks will be normalized to days if weeks do not represent the only calendrical duration items. Only time units of type
CalendarUnit
will be normalized. See Also:
PlainDate.normalize(TimeSpan)

STD_CLOCK_PERIOD
Normalizes the wall time items of a duration on the base
1 day = 24 hours
und1 hour = 60 minutes
and1 minute = 60 seconds
.Attention: Timezonedependent changes of length of day or leapseconds are ignored. That is why this normalization should only be applied on ISOtimestamps without timezone reference. Only time units of enum type
ClockUnit
will be normalized. See Also:
PlainTime


Method Details

ofZero
Gets an empty duration without units.
This method can also be used for generic upcasting of the type U to
IsoUnit
:Duration<CalendarUnit> dur = Duration.ofCalendarUnits(2, 5, 30); Duration<IsoUnit> upcasted = Duration.ofZero().plus(dur);
 Type Parameters:
U
 generic unit type Returns:
 empty duration

of
Creates a new duration which only knows one unit.
Is the given amount is negative then the duration will be negative, too. Is the amount equal to
0
then an empty duration will be returned. Milliseconds or microseconds will be automatically normalized to nanoseconds. Type Parameters:
U
 generic unit type Parameters:
amount
 amount as count of unitsunit
 single time unit Returns:
 new duration

ofPositive
Konstructs a new positive duration for combined date and time items by applying the builder pattern.
 Returns:
 help object for building a positive
Duration

ofNegative
Konstructs a new negative duration for combined date and time items by applying the builder pattern.
 Returns:
 help object for building a negative
Duration

ofCalendarUnits
Creates a positive duration in years, months and days.
All arguments must not be negative. Is any argument equal to
0
then it will be ignored. If a negative duration is needed then an application can simply callinverse()
on the result. Parameters:
years
 amount in yearsmonths
 amount in monthsdays
 amount in days Returns:
 new duration
 Throws:
IllegalArgumentException
 if any argument is negative See Also:
inverse()

ofClockUnits
Creates a positive duratioon in hours, minutes and seconds.
All arguments must not be negative. Is any argument equal to
0
then it will be ignored. If a negative duration is needed then an application can simply callinverse()
on the result. Parameters:
hours
 amount in hoursminutes
 amount in minutesseconds
 amount in seconds Returns:
 new duration
 Throws:
IllegalArgumentException
 if any argument is negative See Also:
inverse()

from
Tries to convert given temporal amount to a duration.
Note that the arithmetic of given amount is probably different from that of the result. Every unit compatible with
java.time.temporal.ChronoUnit
with exception ofERAS
andFOREVER
can be processed. Also the unitsIsoFields.QUARTER_YEARS
andIsoFields.WEEK_BASED_YEARS
are accepted. Parameters:
threeten
 temporal amount Returns:
 normalized duration
 Throws:
IllegalArgumentException
 if the argument contains a nonmappable temporal unit or has mixed signs Since:
 4.0
 See Also:
from(java.time.Duration)
,from(java.time.Period)
,STD_PERIOD

from
Short cut for
TemporalType.THREETEN_DURATION.translate(threetenDuration)
. Parameters:
threetenDuration
 Threetenequivalent of a clock duration Returns:
 normalized clock duration
 Since:
 4.0
 See Also:
TemporalType.THREETEN_DURATION
,STD_CLOCK_PERIOD

from
Short cut for
TemporalType.THREETEN_PERIOD.translate(threetenPeriod)
.Note that the arithmetic of given period is slightly different from that of the result when it comes to handling negative durations:
System.out.println( LocalDate.of(2015, 7, 1).minus(Period.of(0, 1, 1))); // 20150531 System.out.println( PlainDate.of(2015, 7, 1).minus(Duration.ofCalendarUnits(0, 1, 1))); // 20150530
 Parameters:
threetenPeriod
 Threetenequivalent of a calendar duration Returns:
 normalized calendar duration
 Throws:
ChronoException
 if conversion fails due to mixed signs Since:
 4.0
 See Also:
TemporalType.THREETEN_PERIOD
,STD_CALENDAR_PERIOD

in
Constructs a metric for any kind of standard units in normalized form.
Important: If the smallest unit is missing which fits the precision of timepoints to be compared then a remainder of subtraction will exist. The result of distance calculation will not express the full temporal distance in this case. For the completeness of calculation, the day unit is required if the distance between two dates is needed.
Example with different unit types: If this method is called with different unit types then it is strongly recommended to first assign the units to static constants of type
IsoUnit
in order to avoid compiler problems with generics. This practice also helps to improve the readability of code.private static final IsoUnit DAYS = CalendarUnit.DAYS; private static final IsoUnit HOURS = ClockUnit.HOURS; private static final IsoUnit MINUTES = ClockUnit.MINUTES; PlainTimestamp start = PlainTimestamp.of(2014, 3, 28, 0, 30); PlainTimestamp end = PlainTimestamp.of(2014, 4, 5, 14, 15); Duration<IsoUnit> duration = Duration.in(DAYS, HOURS, MINUTES).between(start, end); System.out.println(duration); // output: P8DT13H45M
 Type Parameters:
U
 generic unit type Parameters:
units
 time units to be used in calculation Returns:
 reversible immutable metric for calculating a duration in given units
 Throws:
IllegalArgumentException
 if no time unit is given or if there are unit duplicates See Also:
AbstractMetric

in
Constructs a metric for any kind of standard units in normalized form.
 Type Parameters:
U
 generic unit type Parameters:
units
 time units to be used in calculation Returns:
 reversible immutable metric for calculating a duration in given units
 Throws:
IllegalArgumentException
 if no time unit is given or if there are unit duplicates Since:
 5.6
 See Also:
AbstractMetric
,in(IsoUnit[])

inYearsMonthsDays
Constructs a metric in years, months and days.
Finally the resulting duration will be normalized such that smaller units will be converted to bigger units if possible.
 Returns:
 reversible immutable metric for calculating a duration in years, months and days
 See Also:
in(U[])
,CalendarUnit.YEARS
,CalendarUnit.MONTHS
,CalendarUnit.DAYS
,AbstractMetric

inClockUnits
Constructs a metric in hours, minutes, seconds and nanoseconds.
Finally the resulting duration will be normalized such that smaller units will be converted to bigger units if possible.
 Returns:
 reversible immutable metric for calculating a duration in clock units
 See Also:
in(U[])
,ClockUnit.HOURS
,ClockUnit.MINUTES
,ClockUnit.SECONDS
,ClockUnit.NANOS
,AbstractMetric

inWeekBasedUnits
Constructs a metric in weekbased years, weeks and days.
Finally the resulting duration will be normalized such that smaller units will be converted to bigger units if possible.
 Returns:
 reversible immutable metric for calculating a duration in weekbased years, weeks and days
 Since:
 3.21/4.17
 See Also:
in(U[])
,CalendarUnit.weekBasedYears()
,CalendarUnit.WEEKS
,CalendarUnit.DAYS
,AbstractMetric

in
Helps to evaluate the zonal duration between two timestamps and applies an offset correction if necessary.
Following example handles the change from winter time to summer time in Germany causing 4 instead of 5 hours difference:
PlainTimestamp start = PlainTimestamp.of(2014, 3, 30, 0, 0); PlainTimestamp end = PlainTimestamp.of(2014, 3, 30, 5, 0); IsoUnit hours = ClockUnit.HOURS; System.out.println( Duration.in(Timezone.of("Europe/Berlin"), hours) .between(start, end).toString()); // output: PT4H
 Parameters:
tz
 timezoneunits
 time units to be used in calculation Returns:
 nonreversible zonal metric for calculating a duration in given units
 Throws:
IllegalArgumentException
 if no time unit is given or if there are unit duplicates Since:
 1.2

getTotalLength
Description copied from interface:TimeSpan
Yields all containted time span items with amount and unit in the order from largest to smallest time units.
 Specified by:
getTotalLength
in interfaceTimeSpan<U extends IsoUnit>
 Returns:
 unmodifiable list sorted by precision of units in ascending order where every time unit exists at most once

isNegative
public boolean isNegative()Description copied from interface:TimeSpan
Queries if this time span is negative.
A negative time span relates to the subtraction of two time points where first one is after second one. The partial amounts of every time span are never negative. Hence this attribute is not associated with the partial amounts but only with the time span itself.
Note: An empty time span itself is never negative in agreement with the mathematical relation
(1) * 0 = 0
. Specified by:
isNegative
in interfaceTimeSpan<U extends IsoUnit>
 Returns:
true
if negative and not empty elsefalse

contains
Queries if this duration contains given time unit.
Any time unit is also part of this duration if it is a fractional part of a second (digit symbol) which is to be converted first.
 Specified by:
contains
in interfaceTimeSpan<U extends IsoUnit>
 Overrides:
contains
in classAbstractDuration<U extends IsoUnit>
 Parameters:
unit
 time unit to be checked (optional) Returns:
true
if this duration contains given unit elsefalse
 See Also:
getPartialAmount(U)

getPartialAmount
Gets the partial amount associated with given time unit.
If this duration does not contain given time unit then this method will yield the value
0
. Fractional parts of seconds which are known by their numerical symbols will automatically be converted. That means if a duration stores nanoseconds, but is queried for microseconds then the nanosecond amount will be multiplied by factor1000
and finally returned. Specified by:
getPartialAmount
in interfaceTimeSpan<U extends IsoUnit>
 Overrides:
getPartialAmount
in classAbstractDuration<U extends IsoUnit>
 Parameters:
unit
 time unit the amount is queried for (optional) Returns:
 nonnegative amount associated with given unit (
>= 0
)

comparator
public static <U extends IsoUnit, T extends TimePoint<U, T>> Comparator<Duration<? extends U>> comparator(T base)Creates a
Comparator
which compares durations based on their lengths.Internally, the comparing algorithm uses the expression
base.plus(duration1).compareTo(base.plus(duration2))
. The given basis time point is necessary because some durations with flexible units like months have else no fixed length. Type Parameters:
U
 generic unit typeT
 generic type of time point Parameters:
base
 base time point which durations will use for comparison Returns:
Comparator
for plain durations See Also:
TimePoint.compareTo(T)

comparatorOnClock
Obtains a comparator suitable for Durations based on clock units.
A negative duration is always smaller than a positive one. Example:
Duration<ClockUnit> d1 = Duration.parseClockPeriod("PT22M2.666S"); Duration<ClockUnit> d2 = Duration.parseClockPeriod("PT25M"); Duration<ClockUnit> d3 = Duration.parseClockPeriod("PT21M62.667S"); Duration<ClockUnit> d4 = Duration.parseClockPeriod("PT22M2.667S"); Stream<Duration<ClockUnit>> s = Stream.of(d1, d2, d3, d4); assertThat(s.max(Duration.comparatorOnClock()).get(), is(d3));
 Returns:
 Comparator for clockbased durations
 Since:
 5.0

plus
Gets a copy of this duration where given amount will be added to the partial amount of this duration in given unit.
The method also takes in account the sign of the duration. Example:
System.out.println(Duration.of(5, MONTHS).plus(6, MONTHS)); // output: P1M
Notes: Is the amount to be added equal to
0
then the method will simply yield this duration. Mixed signs are not permitted and will be rejected by an exception. For example following expression is not allowed:Duration.of(1, MONTHS).plus(30, DAYS); // throws IllegalStateException
 Parameters:
amount
 temporal amount to be added (maybe negative)unit
 associated time unit Returns:
 new changed duration while this duration remains unaffected
 Throws:
IllegalStateException
 if the result gets mixed signs by adding the partial amountsIllegalArgumentException
 if different units of same length existArithmeticException
 in case of long overflow See Also:
with(long, U)

plus
Creates a duration as union of this instance and given timespan where partial amounts of equal units will be summed up.
In order to sum up timespans with different unit types, following trick can be applied:
Duration<IsoUnit> zero = Duration.ofZero(); Duration<IsoUnit> result = zero.plus(this).plus(timespan);
Note about sign handling: If this duration and given timespan have different signs then Time4J tries to apply a normalization in the hope the mixed signs disappear. Otherwise this method will throw an exception in case of mixed signs for different duration items. So it is strongly recommended only to merge durations with equal signs.
 Parameters:
timespan
 other time span this duration will be merged with by adding the partial amounts Returns:
 new merged duration
 Throws:
IllegalStateException
 if the result gets mixed signs by adding the partial amountsIllegalArgumentException
 if different units of same length existArithmeticException
 in case of long overflow See Also:
union(TimeSpan)

with
Gets a copy of this duration where the partial amount associated with given time unit is changed.
Equivalent to
plus(amount  getAmount(unit), unit)
. Parameters:
amount
 temporal amount to be set (maybe negative)unit
 associated time unit Returns:
 new changed duration while this duration remains unaffected
 Throws:
IllegalStateException
 if the result gets mixed signs by setting the partial amountsIllegalArgumentException
 if different units of same length existArithmeticException
 in case of long overflow See Also:
plus(long, U)

abs
Gets the absolute always nonnegative copy of this duration.
Example:
System.out.println(Duration.of(5, MONTHS).abs()); // output: P5M
 Returns:
 new positive duration if this duration is negative else this duration unchanged
 See Also:
isNegative()
,inverse()

inverse
Gets a copy of this duration with reversed sign.
A double call of this method will yield an equal duration so following invariant holds:
System.out.println(this.inverse().inverse().equals(this)); // output: true
For the special case of an empty duration, this method has no effect and just returns the same instance. The method is equivalent to the expression
multipliedBy(1)
.Example:
System.out.println(Duration.of(5, MONTHS).inverse()); // output: P5M
 Specified by:
inverse
in classAbstractDuration<U extends IsoUnit>
 Returns:
 new negative duration if this duration is positive else a new positive duration with the same partial amounts and units
 See Also:
isNegative()
,multipliedBy(int)

multipliedBy
Multiplies all partial amounts of this duration by given factor.
Is the factor equal to
0
then the new duration is empty. If the factor1
is specified then the method will just yield this instance unaffected. In the case of a negative factor the sign will also be inverted. Parameters:
factor
 multiplication factor Returns:
 new duration with all amounts multiplied while this duration remains unaffected
 Throws:
ArithmeticException
 in case of long overflow

union
Creates a duration as union of this instance and given timespan where partial amounts of equal units will be summed up.
The list result of this method can be used in time arithmetic as follows:
Duration<CalendarUnit> dateDur = Duration.ofCalendarUnits(2, 7, 10); Duration<ClockUnit> timeDur = Duration.ofClockUnits(0, 30, 0); PlainTimestamp tsp = PlainTimestamp.of(2014, 1, 1, 0, 0); for (Duration<?> dur : Duration.ofZero().plus(dateDur).union(timeDur)) { tsp = tsp.plus(dur); } System.out.println(tsp); // 20160811T00:30
Note that this example will even work in case of mixed signs. No exception will be thrown. Instead this duration and the other one would just be added to the timestamp within a loop  step by step. In contrast to
plus(TimeSpan)
, Time4J does not try to normalize the durations in order to produce a unique sign (on best effort base) in case of mixed signs. Parameters:
timespan
 other time span this duration is to be merged with Returns:
 unmodifiable list with one new merged duration or two unmerged durations in case of mixed signs
 Throws:
IllegalArgumentException
 if different units of same length existArithmeticException
 in case of long overflow See Also:
plus(TimeSpan)

compose
public static Duration<IsoUnit> compose(Duration<CalendarUnit> calendarPeriod, Duration<ClockUnit> clockPeriod)Creates a composition of a calendar period and a clock period.
 Parameters:
calendarPeriod
 calendrical durationclockPeriod
 duration with clock units Returns:
 composite duration
 Since:
 3.0
 See Also:
toCalendarPeriod()
,toClockPeriod()

toCalendarPeriod
Extracts a new duration with all contained calendar units only.
The clock time part will be removed.
 Returns:
 new duration with calendar units only
 Since:
 3.0
 See Also:
compose(Duration, Duration)
,toClockPeriod()

toClockPeriod
Extracts a new duration with all contained clock units only.
The calendrical part will be removed.
 Returns:
 new duration with clock units only
 Since:
 3.0
 See Also:
compose(Duration, Duration)
,toCalendarPeriod()
,toClockPeriodWithDaysAs24Hours()

toClockPeriodWithDaysAs24Hours
Extracts a new duration with all contained clock units only.
The calendrical part will be removed with the exception of the days which will be converted into hours (on the base 1 day = 24 hours).
 Returns:
 new duration with clock units only
 Since:
 3.28/4.24
 See Also:
compose(Duration, Duration)
,toCalendarPeriod()

toTemporalAmount
Converts this duration to a general temporal amount compatible with JSR310spec.
The conversion is possible if and only if following units are part of this duration:
 CalendarUnit.MILLENNIA
 CalendarUnit.CENTURIES
 CalendarUnit.DECADES
 CalendarUnit.YEARS
 CalendarUnit.QUARTERS
 CalendarUnit.MONTHS
 CalendarUnit.WEEKS
 CalendarUnit.DAYS
 ClockUnit.HOURS
 ClockUnit.MINUTES
 ClockUnit.SECONDS
 ClockUnit.MILLIS
 ClockUnit.MICROS
 ClockUnit.NANOS
 CalendarUnit.weekBasedYears()
The resulting temporal amount is preferred to be applied on the local types of JSR310 for the sake of conceptual clarity so the general mapping using this method looks like:
Duration<IsoUnit>
can be applied onLocalDateTime
Duration<CalendarUnit>
can be applied onLocalDate
Duration<ClockUnit>
can be applied onLocalTime
Other temporal types of JSR310 might be supported, too (like
YearMonth
orZonedDateTime
). Note that using this method cannot be typesafe due to the design of JSR310 (possibly throwing an exception at runtime) and includes some performance penalty because of the costs of conversion. Users should rather use Time4Jtypes for achieving best results. Returns:
 temporal amount applicable on JSR310types if they support all units of this duration
 Throws:
UnsupportedOperationException
 if this duration contains any unit not listed above Since:
 4.17

with
Normalizes this duration by given normalizer.
 Parameters:
normalizer
 help object for normalizing this duration Returns:
 new normalized duration while this duration remains unaffected
 See Also:
STD_PERIOD
,STD_CALENDAR_PERIOD
,STD_CLOCK_PERIOD
,approximateHours(int)
,approximateMinutes(int)
,approximateSeconds(int)
,ClockUnit.only()

truncatedTo
Sets all duration parts to zero whose unit has a smaller length than given unit.
 Parameters:
unit
 the minimum unit whose associated amount might still be nonzero Returns:
 truncated duration
 Since:
 5.2

approximateHours
Yields an approximate normalizer in steps of hours which finally uses years, months, days and rounded hours.
The rounding algorithm consists of a combination of integer division and multiplication using the given step width. Example for suppressing hours (and all smaller units) by mean of an extra big step width of 24 hours (= 1 day):
Duration<IsoUnit> dur = Duration.ofPositive().years(2).months(13).days(35) .minutes(132).build() .with(Duration.approximateHours(24)); System.out.println(dur); // output: P3Y2M4D
Another example for rounded hours using static imports:
System.out.println(Duration.<IsoUnit>of(7, HOURS).with(approximateHours(3))); // output: PT6H
 Parameters:
steps
 rounding step width Returns:
 new normalizer for fuzzy and approximate durations
 Throws:
IllegalArgumentException
 if the argument is not positive Since:
 2.0

approximateMinutes
Yields an approximate normalizer in steps of minutes which finally uses years, months, days, hours and rounded minutes.
 Parameters:
steps
 rounding step width Returns:
 new normalizer for fuzzy and approximate durations
 Throws:
IllegalArgumentException
 if the argument is not positive Since:
 2.0
 See Also:
approximateHours(int)

approximateSeconds
Yields an approximate normalizer in steps of seconds which finally uses years, months, days, hours, minutes and rounded seconds.
 Parameters:
steps
 rounding step width Returns:
 new normalizer for fuzzy and approximate durations
 Throws:
IllegalArgumentException
 if the argument is not positive Since:
 2.0
 See Also:
approximateHours(int)

approximateMaxUnitOnly
Creates a normalizer which yields an approximate duration based on the maximum relevant unit of the original duration (but not smaller than seconds).
Example:
assertThat( Duration.<IsoUnit>of(60 * 60 * 24 * 365, ClockUnit.SECONDS) .with(Duration.approximateMaxUnitOnly()), is(Duration.of(1, YEARS)));
Note: Due to the nature of this approximationbased normalization, exact results cannot be expected. Subsecond components are ignored.
 Returns:
 new normalizer for fuzzy and approximate durations of only one unit (either years, months, days, hours, minutes or seconds)
 Since:
 3.14/4.11
 See Also:
approximateHours(int)
,approximateMinutes(int)
,approximateSeconds(int)

approximateMaxUnitOrWeeks
Like
approximateMaxUnitOnly()
but can create weekbased durations if the count of days is bigger than6
. Returns:
 new normalizer for fuzzy and approximate durations of only one unit (either years, months, weeks/days, hours, minutes or seconds)
 Since:
 3.14/4.11
 See Also:
approximateMaxUnitOnly()

summingUp
Helps to sum up durations of a stream.
Note: A normalization of the result is not yet done.
Example for summing up a list of durations and final normalization:
List<Duration<ClockUnit>> list = new ArrayList<>(); list.add(Duration.of(11, ClockUnit.HOURS)); list.add(Duration.ofClockUnits(4, 35, 121)); list.add(Duration.of(10, ClockUnit.MINUTES)); Duration<ClockUnit> expected = Duration.ofClockUnits(15, 47, 1); assertThat( list.stream().collect(Duration.summingUp()).with(Duration.STD_CLOCK_PERIOD), is(expected));
 Type Parameters:
U
 generic type of time units Returns:
 Collector for summing up durations in a stream
 Since:
 5.0

equals
Based on all stored duration items and the sign.
 Overrides:
equals
in classObject
 Returns:
true
ifobj
is also aDuration
, has the same units and amounts, the same sign and the same calendrical status elsefalse
 See Also:
getTotalLength()
,isNegative()

hashCode
public int hashCode()Computes the hash code.

toString
Gets a canonical representation which optionally starts with a negative sign then continues with the letter "P", followed by a sequence of alphanumerical chars similar to the definition given in ISO8601.
Example: In ISO8601 a duration of one month, three days and four hours is described as "P1M3DT4H". The special char "T" separates date and time part. Units are normally printed using their symbols, as second alternative using the output of their
toString()
method within curly brackets.Is the duration negative then the representation will have a preceding minus sign as specified by XMLschema (for example "P2D") while an empty duration will always have the format "PT0S" (second as universal unit). If the second part is also fractional then this method will use the comma as decimal separator char as recommended by ISO8601.
Note: The latter ISOrecommendation to use the comma as decimal separator char can be overriden by setting the system property "net.time4j.format.iso.decimal.dot" to "true" so that the english variation of a dot will be choosen instead.
 Overrides:
toString
in classAbstractDuration<U extends IsoUnit>
 Returns:
 String
 See Also:
toStringISO()
,toStringXML()
,parsePeriod(String)

toStringISO
Gets a canonical representation which starts with the letter "P", followed by a sequence of alphanumerical chars as defined in ISO8601.
A negative sign is not defined in ISO8601 and will be rejected by this method with an exception. An empty duration will always have the format "PT0S" (second as universal unit). If the second part is also fractional then this method will use the comma as decimal separator char as recommended by ISO8601.
Note: The latter ISOrecommendation to use the comma as decimal separator char can be overriden by setting the system property "net.time4j.format.iso.decimal.dot" to "true" so that the english variation of a dot will be choosen instead. Furthermore, weeks are normalized to days if there are other calendrical units like years or months.
Only units of types
CalendarUnit
orClockUnit
can be printed. Returns:
 String
 Throws:
ChronoException
 if this duration is negative or if any special units shall be output, but units of typeCalendarUnit
will be translated to isocompatible units if necessary See Also:
parsePeriod(String)
,IsoUnit.getSymbol()

toStringXML
Gets a canonical representation conforming to XMLschema which optionally starts with a negative sign then continues with the letter "P", followed by a sequence of alphanumerical chars similar to the definition given in ISO8601.
Is the duration negative then the representation will have a preceding minus sign as specified by XMLschema (for example "P2D") while an empty duration will always have the format "PT0S" (second as universal unit). If the second part is also fractional then this method will use the dot as decimal separator char (deviating specification in XMLschema). Weeks will always be normalized to days.
Only units of types
CalendarUnit
orClockUnit
can be printed. Returns:
 String
 Throws:
ChronoException
 if any special units shall be output, but units of typeCalendarUnit
will be translated to xmlcompatible units if necessary See Also:
parsePeriod(String)
,IsoUnit.getSymbol()

parsePeriod
Parses a canonical representation to a duration.
Canonical representations which start with the literal P are also called "period" in Time4J (Pstring). This format is strongly recommended for storage in databases or XML. Syntax in a notation similar to regular expressions:
sign := []? amount := [09]+ fraction := [,\.]{amount} yearsmonthsdays := ({amount}Y)?({amount}M)?({amount}D)? weeks := ({amount}W)? date := {yearsmonthsdays}  {weeks} time := ({amount}H)?({amount}M)?({amount}{fraction}?S)? period := {sign}P{date}(T{time})?  PT{time}
The units MILLENNIA, CENTURIES, DECADES and QUARTERS defined in
CalendarUnit
are supported but not special units likeCalendarUnit.weekBasedYears()
.Furthermore there is the constraint that the symbols P and T must be followed by at least one duration item of amount and unit. All items with zero amount will be ignored however. The only item which is allowed to have a fractional part is SECONDS and can contain a comma as well as a dot as decimal separator. In ISO8601 the comma is the preferred char, in XMLschema only the dot is allowed. If this parser is used in context of XMLschema (type xs:duration) it must be stated that week items are missing in contrast to ISO8601. The method
toStringXML()
takes into account these characteristics of XMLschema (leaving aside the fact that XMLschema is potentially designed for unlimited big amounts but Time4J can define durations only in long range with nanosecond precision at best).Note: The alternative ISOformats PYYYYMMDDThh:mm:ss and PYYYYDDDThh:mm:ss and their basic variants are supported since version v2.0.
Examples for supported formats:
date := P7Y4M3D (negative: 7 years, 4 months, 3 days) time := PT3H2M1,4S (positive: 3 hours, 2 minutes, 1400 milliseconds) datetime := P1Y1M5DT15H59M10.400S (dot as decimal separator) alternative := P00000215T17:45
 Parameters:
period
 duration in canonical, ISO8601compatible or XMLschemacompatible format (Pstring) Returns:
 parsed duration in all possible standard units of date and time
 Throws:
ParseException
 if parsing fails Since:
 1.2.1
 See Also:
parseCalendarPeriod(String)
,parseClockPeriod(String)
,toString()
,toStringISO()
,toStringXML()

parseCalendarPeriod
Parses a canonical representation with only date units to a calendrical duration.
 Parameters:
period
 duration in canonical, ISO8601compatible or XMLschemacompatible format (Pstring) Returns:
 parsed calendrical duration
 Throws:
ParseException
 if parsing fails See Also:
parsePeriod(String)
,parseClockPeriod(String)

parseClockPeriod
Parses a canonical representation with only wall time units to a timeonly duration.
 Parameters:
period
 duration in canonical, ISO8601compatible or XMLschemacompatible format (Pstring) Returns:
 parsed timeonly duration
 Throws:
ParseException
 if parsing fails See Also:
parsePeriod(String)
,parseCalendarPeriod(String)

parseWeekBasedPeriod
Parses a canonical representation with only weekbased units (Y, W and D) to a calendrical duration where years are interpreted as weekbased years with either 364 days (= 52 weeks) or 371 days (= 53 weeks).
 Parameters:
period
 duration in canonical or ISO8601compatible format (Pstring) Returns:
 parsed calendrical duration
 Throws:
ParseException
 if parsing fails Since:
 3.21/4.17
 See Also:
parsePeriod(String)
,CalendarUnit.weekBasedYears()

formatter
Equivalent to
Duration.Formatter.ofPattern(String)
. Parameters:
pattern
 format pattern Returns:
 new formatter instance
 Throws:
IllegalArgumentException
 in any case of pattern inconsistencies or failures Since:
 3.0

formatter
Equivalent to
Duration.Formatter.ofPattern(Class, String)
. Type Parameters:
U
 generic unit type Parameters:
type
 reified unit typepattern
 format pattern Returns:
 new formatter instance
 Throws:
IllegalArgumentException
 in any case of pattern inconsistencies or failures Since:
 3.0
