Duration (Time4J-Core 2.0 API)

java.lang.Object
- net.time4j.engine.AbstractDuration
- - net.time4j.Duration

Type Parameters:
U - generic type of time units

All Implemented Interfaces:

Serializable, TimeSpan
```
public final class Duration
extends AbstractDuration
implements Serializable
```
ISO-8601-compatible 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() (builder-pattern)
- ofNegative() (builder-pattern)
- parsePeriod(String)
- parseCalendarPeriod(String)
- parseClockPeriod(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 ISO-8061, but part of the XML-schema-specification and defines the position of two time point 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

Nested Classes
Modifier and Type	Class and Description
`static class`	`Duration.Builder` Builder class for constructing a duration conforming to ISO-8601 which consists of years, months, days and any wall time units.
`static class`	`Duration.Formatter<U extends IsoUnit>` Non-localized and user-defined 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

Field Summary

Fields
Modifier and Type	Field and Description
`static Normalizer<CalendarUnit>`	`STD_CALENDAR_PERIOD` Normalizes the calendrical items of a duration on the base `1 year = 12 months` - without converting the days to months.
`static Normalizer<ClockUnit>`	`STD_CLOCK_PERIOD` Normalizes the wall time items of a duration on the base `1 day = 24 hours` und `1 hour = 60 minutes` and `1 minute = 60 seconds`.
`static Normalizer<IsoUnit>`	`STD_PERIOD` Normalizes the duration items on the base of `1 year = 12 months` and `1 day = 24 hours` and `1 hour = 60 minutes` and `1 minute = 60 seconds` - without converting days to months.

Method Summary

Methods
Modifier and Type	Method and Description
`Duration<U>`	`abs()` Gets the absolute always non-negative 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>`	`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<? super U,T>> Comparator<Duration<U>>`	`comparator(T base)` Creates a `Comparator` which compares durations based on their lengths.
`boolean`	`contains(IsoUnit unit)` Queries if this duration contains given time unit.
`boolean`	`equals(Object obj)` Based on all stored duration items and the sign.
`long`	`getPartialAmount(IsoUnit unit)` Gets the partial amount associated with given time unit.
`List<TimeSpan.Item<U>>`	`getTotalLength()` 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 TimeMetric<IsoUnit,Duration<IsoUnit>>`	`in(Timezone tz, IsoUnit... units)` 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>>`	`inClockUnits()` Constructs a metric in hours, minutes, seconds and nanoseconds.
`Duration<U>`	`inverse()` Gets a copy of this duration with reversed sign.
`static TimeMetric<CalendarUnit,Duration<CalendarUnit>>`	`inYearsMonthsDays()` Constructs a metric in years, months and days.
`boolean`	`isNegative()` Queries if this time span is negative.
`Duration<U>`	`multipliedBy(int factor)` Multiplies all partial amounts of this duration by given factor.
`static <U extends IsoUnit> Duration<U>`	`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.
`static Duration<ClockUnit>`	`ofClockUnits(int hours, int minutes, int seconds)` Creates a positive duratioon in hours, minutes and seconds.
`static Duration.Builder`	`ofNegative()` Konstructs a new negative duration for combined date- and time items by applying the builder pattern.
`static Duration.Builder`	`ofPositive()` Konstructs a new positive duration for combined date- and time items by applying the builder pattern.
`static <U extends IsoUnit> Duration<U>`	`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.
`static Duration<ClockUnit>`	`parseClockPeriod(String period)` Parses a canonical representation with only wall time units to a time-only duration.
`static Duration<IsoUnit>`	`parsePeriod(String period)` Parses a canonical representation to a duration.
`Duration<U>`	`plus(long amount, U unit)` Gets a copy of this duration where given amount will be added to the partial amount of this duration in given unit.
`Duration<U>`	`plus(TimeSpan<? extends U> timespan)` Creates a duration as union of this instance and given timespan where partial amounts of equal units will be summed up.
`String`	`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 ISO-8601.
`String`	`toStringISO()` Gets a canonical representation which starts with the letter "P", followed by a sequence of alphanumerical chars as defined in ISO-8601.
`String`	`toStringXML()` Gets a canonical representation conforming to XML-schema 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 ISO-8601.
`List<Duration<U>>`	`union(TimeSpan<? extends U> timespan)` Creates a duration as union of this instance and given timespan where partial amounts of equal units will be summed up.
`Duration<U>`	`with(long amount, U unit)` Gets a copy of this duration where the partial amount associated with given time unit is changed.
`Duration<U>`	`with(Normalizer<U> normalizer)` Normalizes this duration by given normalizer.

Methods inherited from class net.time4j.engine.AbstractDuration
addTo, isEmpty, isPositive, subtractFrom

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Field Detail
 - STD_PERIOD
```
public static Normalizer<IsoUnit> STD_PERIOD
```
 Normalizes the duration items on the base of 1 year = 12 months and 1 day = 24 hours and 1 hour = 60 minutes and 1 minute = 60 seconds - without converting days to months.
 
 Attention: Timezone-dependent changes of length of day or leapseconds are ignored. That is why this normalization should only be applied on ISO-timestamps without timezone reference. Only time units of enum types CalendarUnit and ClockUnit 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
```
public static Normalizer<CalendarUnit> 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
```
public static Normalizer<ClockUnit> STD_CLOCK_PERIOD
```
 Normalizes the wall time items of a duration on the base 1 day = 24 hours und 1 hour = 60 minutes and 1 minute = 60 seconds.
 
 Attention: Timezone-dependent changes of length of day or leapseconds are ignored. That is why this normalization should only be applied on ISO-timestamps without timezone reference. Only time units of enum type ClockUnit will be normalized.
 
 See Also:
 PlainTime
- Method Detail
 - ofZero
```
public static  Duration 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
```
public static  Duration of(long amount,
 U unit)
```
 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 units
 unit - single time unit
 
 Returns:
 new duration
 - ofPositive
```
public static Duration.Builder 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
```
public static Duration.Builder 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
```
public static Duration<CalendarUnit> ofCalendarUnits(int years,
 int months,
 int days)
```
 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 call inverse() on the result.
 
 Parameters:
 years - amount in years
 months - amount in months
 days - amount in days
 
 Returns:
 new duration
 
 Throws:
 
 IllegalArgumentException - if any argument is negative
 See Also:
 inverse()
 - ofClockUnits
```
public static Duration<ClockUnit> ofClockUnits(int hours,
 int minutes,
 int seconds)
```
 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 call inverse() on the result.
 
 Parameters:
 hours - amount in hours
 minutes - amount in minutes
 seconds - amount in seconds
 
 Returns:
 new duration
 
 Throws:
 
 IllegalArgumentException - if any argument is negative
 See Also:
 inverse()
 - in
```
public static  TimeMetric<U,Duration> in(U... units)
```
 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:
 immutable metric for calculating a duration in given units
 
 Throws:
 
 IllegalArgumentException - if no time unit is given or if there are unit duplicates
 - inYearsMonthsDays
```
public static TimeMetric<CalendarUnit,Duration<CalendarUnit>> 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:
 immutable metric for calculating a duration in years, months and days
 See Also:
 in(U[]), CalendarUnit.YEARS, CalendarUnit.MONTHS, CalendarUnit.DAYS
 - inClockUnits
```
public static TimeMetric<ClockUnit,Duration<ClockUnit>> 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:
 immutable metric for calculating a duration in clock units
 See Also:
 in(U[]), ClockUnit.HOURS, ClockUnit.MINUTES, ClockUnit.SECONDS, ClockUnit.NANOS
 - in
```
public static TimeMetric<IsoUnit,Duration<IsoUnit>> in(Timezone tz,
 IsoUnit... units)
```
 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 - timezone
 units - time units to be used in calculation
 
 Returns:
 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
```
public List<TimeSpan.Item> 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 interface TimeSpan
 
 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 interface TimeSpan
 
 Returns:
 true if negative and not empty else false
 - contains
```
public boolean contains(IsoUnit unit)
```
 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 interface TimeSpan
 
 Overrides:
 
 contains in class AbstractDuration
 
 Parameters:
 unit - time unit to be checked (optional)
 
 Returns:
 true if this duration contains given unit else false
 See Also:
 getPartialAmount(U)
 - getPartialAmount
```
public long getPartialAmount(IsoUnit unit)
```
 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 factor 1000 and finally returned.
 
 Specified by:
 
 getPartialAmount in interface TimeSpan
 
 Overrides:
 
 getPartialAmount in class AbstractDuration
 
 Parameters:
 unit - time unit the amount is queried for (optional)
 
 Returns:
 non-negative amount associated with given unit (>= 0)
 - comparator
```
public static > Comparator<Duration> 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 type
 T - 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)
 - plus
```
public Duration plus(long amount,
 U unit)
```
 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 amounts
 
 IllegalArgumentException - if different units of same length exist
 
 ArithmeticException - in case of long overflow
 See Also:
 with(long, U)
 - plus
```
public Duration plus(TimeSpan<? extends U> timespan)
```
 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 amounts
 
 IllegalArgumentException - if different units of same length exist
 
 ArithmeticException - in case of long overflow
 See Also:
 union(TimeSpan)
 - with
```
public Duration with(long amount,
 U unit)
```
 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 amounts
 
 IllegalArgumentException - if different units of same length exist
 
 ArithmeticException - in case of long overflow
 See Also:
 plus(long, U)
 - abs
```
public Duration abs()
```
 Gets the absolute always non-negative 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
```
public Duration 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 class AbstractDuration
 
 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
```
public Duration multipliedBy(int factor)
```
 Multiplies all partial amounts of this duration by given factor.
 
 Is the factor equal to 0 then the new duration is empty. If the factor 1 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
```
public List<Duration> union(TimeSpan<? extends U> timespan)
```
 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); // 2016-08-11T00: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 exist
 
 ArithmeticException - in case of long overflow
 See Also:
 plus(TimeSpan)
 - with
```
public Duration with(Normalizer normalizer)
```
 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()
 - approximateHours
```
public static Normalizer<IsoUnit> approximateHours(int steps)
```
 Yields an approximate normalizer in steps of hours which finally uses years, months, days and rounded hours.
 
 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
 
```
 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
```
public static Normalizer<IsoUnit> approximateMinutes(int steps)
```
 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
 - approximateSeconds
```
public 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.
 
 Parameters:
 steps - rounding step width
 
 Returns:
 new normalizer for fuzzy and approximate durations
 
 Throws:
 
 IllegalArgumentException - if the argument is not positive
 Since:
 
 2.0
 - equals
```
public boolean equals(Object obj)
```
 Based on all stored duration items and the sign.
 
 Overrides:
 
 equals in class Object
 
 Returns:
 true if obj is also a Duration, has the same units and amounts, the same sign and the same calendrical status else false
 See Also:
 getTotalLength(), isNegative()
 - hashCode
```
public int hashCode()
```
 Computes the hash code.
 
 Overrides:
 
 hashCode in class Object
 - toString
```
public String 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 ISO-8601.
 
 Example: In ISO-8601 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 XML-schema (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 ISO-8601.
 
 Note: The latter ISO-recommendation 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 class AbstractDuration
 
 Returns:
 String
 See Also:
 toStringISO(), toStringXML(), parsePeriod(String)
 - toStringISO
```
public String toStringISO()
```
 Gets a canonical representation which starts with the letter "P", followed by a sequence of alphanumerical chars as defined in ISO-8601.
 
 A negative sign is not defined in ISO-8601 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 ISO-8601.
 
 Note: The latter ISO-recommendation 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 or ClockUnit can be printed.
 
 Returns:
 String
 
 Throws:
 
 ChronoException - if this duration is negative or if any special units shall be output, but units of type CalendarUnit will be translated to iso-compatible units if necessary
 See Also:
 parsePeriod(String), IsoUnit.getSymbol()
 - toStringXML
```
public String toStringXML()
```
 Gets a canonical representation conforming to XML-schema 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 ISO-8601.
 
 Is the duration negative then the representation will have a preceding minus sign as specified by XML-schema (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 XML-schema). Weeks will always be normalized to days.
 
 Only units of types CalendarUnit or ClockUnit can be printed.
 
 Returns:
 String
 
 Throws:
 
 ChronoException - if any special units shall be output, but units of type CalendarUnit will be translated to xml-compatible units if necessary
 See Also:
 parsePeriod(String), IsoUnit.getSymbol()
 - parsePeriod
```
public static Duration<IsoUnit> parsePeriod(String period)
 throws ParseException
```
 Parses a canonical representation to a duration.
 
 Canonical representations which start with the literal P are also called "period" in Time4J (P-string). This format is strongly recommended for storage in databases or XML. Syntax in a notation similar to regular expressions:
```
 sign := [-]?
 amount := [0-9]+
 fraction := [,\.]{amount}
 years-months-days := ({amount}Y)?({amount}M)?({amount}D)?
 weeks := ({amount}W)?
 date := {years-months-days} | {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 like CalendarUnit.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 ISO-8601 the comma is the preferred char, in XML-schema only the dot is allowed. If this parser is used in context of XML-schema (type xs:duration) it must be stated that week items are missing in contrast to ISO-8601. The method toStringXML() takes into account these characteristics of XML-schema (leaving aside the fact that XML-schema is potentially designed for unlimited big amounts but Time4J can define durations only in long range with nanosecond precision at best).
 
 Note: The alternative ISO-formats PYYYY-MM-DDThh:mm:ss and PYYYY-DDDThh: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)
 date-time := P1Y1M5DT15H59M10.400S (dot as decimal separator)
 
```
 Parameters:
 period - duration in canonical, ISO-8601-compatible or XML-schema-compatible format (P-string)
 
 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
```
public static Duration<CalendarUnit> parseCalendarPeriod(String period)
 throws ParseException
```
 Parses a canonical representation with only date units to a calendrical duration.
 
 Parameters:
 period - duration in canonical, ISO-8601-compatible or XML-schema-compatible format (P-string)
 
 Returns:
 parsed calendrical duration
 
 Throws:
 
 ParseException - if parsing fails
 See Also:
 parsePeriod(String), parseClockPeriod(String)
 - parseClockPeriod
```
public static Duration<ClockUnit> parseClockPeriod(String period)
 throws ParseException
```
 Parses a canonical representation with only wall time units to a time-only duration.
 
 Parameters:
 period - duration in canonical, ISO-8601-compatible or XML-schema-compatible format (P-string)
 
 Returns:
 parsed time-only duration
 
 Throws:
 
 ParseException - if parsing fails
 See Also:
 parsePeriod(String), parseCalendarPeriod(String)

Class Duration<U extends IsoUnit>

Nested Class Summary

Nested classes/interfaces inherited from interface net.time4j.engine.TimeSpan

Field Summary

Method Summary

Methods inherited from class net.time4j.engine.AbstractDuration

Methods inherited from class java.lang.Object

Field Detail

STD_PERIOD

STD_CALENDAR_PERIOD

STD_CLOCK_PERIOD

Method Detail

ofZero

of

ofPositive

ofNegative

ofCalendarUnits

ofClockUnits

in

inYearsMonthsDays

inClockUnits

in

getTotalLength

isNegative

contains

getPartialAmount

comparator

plus

plus

with

abs

inverse

multipliedBy

union

with

approximateHours

approximateMinutes

approximateSeconds

equals

hashCode

toString

toStringISO

toStringXML

parsePeriod

parseCalendarPeriod

parseClockPeriod