Duration (ThreeTen backport 0.7.2 API)

java.lang.Object
- org.threeten.bp.Duration

All Implemented Interfaces:

Serializable, Comparable<Duration>, TemporalAdder, TemporalSubtractor
```
public final class Duration
extends Object
implements TemporalAdder, TemporalSubtractor, Comparable<Duration>, Serializable
```
A duration between two instants on the time-line.
This class models a duration of time and is not tied to any instant. The model is of a directed duration, meaning that the duration may be negative.
A physical duration could be of infinite length. For practicality, the duration is stored with constraints similar to Instant. The duration uses nanosecond resolution with a maximum value of the seconds that can be held in a long. This is greater than the current estimated age of the universe.
The range of a duration requires the storage of a number larger than a long. To achieve this, the class stores a long representing seconds and an int representing nanosecond-of-second, which will always be between 0 and 999,999,999.
The duration is measured in "seconds", but these are not necessarily identical to the scientific "SI second" definition based on atomic clocks. This difference only impacts durations measured near a leap-second and should not affect most applications. See Instant for a discussion as to the meaning of the second and time-scales.
Specification for implementors
This class is immutable and thread-safe.

See Also:
Serialized Form

Field Summary

Fields
Modifier and Type Field and Description

static Duration ZERO
Constant for a duration of zero.

Fields
Modifier and Type	Field and Description
`static Duration`	`ZERO` Constant for a duration of zero.

Method Summary

Methods
Modifier and Type	Method and Description
`Duration`	`abs()` Returns a copy of this duration with a positive length.
`Temporal`	`addTo(Temporal temporal)` Adds this duration to the specified temporal object.
`static Duration`	`between(TemporalAccessor startInclusive, TemporalAccessor endExclusive)` Obtains an instance of `Duration` representing the duration between two instants.
`int`	`compareTo(Duration otherDuration)` Compares this duration to the specified `Duration`.
`Duration`	`dividedBy(long divisor)` Returns a copy of this duration divided by the specified value.
`boolean`	`equals(Object otherDuration)` Checks if this duration is equal to the specified `Duration`.
`int`	`getNano()` Gets the number of nanoseconds within the second in this duration.
`long`	`getSeconds()` Gets the number of seconds in this duration.
`int`	`hashCode()` A hash code for this duration.
`boolean`	`isGreaterThan(Duration otherDuration)` Checks if this duration is greater than the specified `Duration`.
`boolean`	`isLessThan(Duration otherDuration)` Checks if this duration is less than the specified `Duration`.
`boolean`	`isNegative()` Checks if this duration is negative, excluding zero.
`boolean`	`isPositive()` Checks if this duration is positive, excluding zero.
`boolean`	`isZero()` Checks if this duration is zero length.
`Duration`	`minus(Duration duration)` Returns a copy of this duration with the specified duration subtracted.
`Duration`	`minus(long amountToSubtract, TemporalUnit unit)` Returns a copy of this duration with the specified duration subtracted.
`Duration`	`minusMillis(long millisToSubtract)` Returns a copy of this duration with the specified duration in milliseconds subtracted.
`Duration`	`minusNanos(long nanosToSubtract)` Returns a copy of this duration with the specified duration in nanoseconds subtracted.
`Duration`	`minusSeconds(long secondsToSubtract)` Returns a copy of this duration with the specified duration in seconds subtracted.
`Duration`	`multipliedBy(long multiplicand)` Returns a copy of this duration multiplied by the scalar.
`Duration`	`negated()` Returns a copy of this duration with the length negated.
`static Duration`	`of(long amount, TemporalUnit unit)` Obtains an instance of `Duration` from a duration in the specified unit.
`static Duration`	`ofDays(long days)` Obtains an instance of `Duration` from a number of standard 24 hour days.
`static Duration`	`ofHours(long hours)` Obtains an instance of `Duration` from a number of standard length hours.
`static Duration`	`ofMillis(long millis)` Obtains an instance of `Duration` from a number of milliseconds.
`static Duration`	`ofMinutes(long minutes)` Obtains an instance of `Duration` from a number of standard length minutes.
`static Duration`	`ofNanos(long nanos)` Obtains an instance of `Duration` from a number of nanoseconds.
`static Duration`	`ofSeconds(long seconds)` Obtains an instance of `Duration` from a number of seconds.
`static Duration`	`ofSeconds(long seconds, long nanoAdjustment)` Obtains an instance of `Duration` from a number of seconds and an adjustment in nanoseconds.
`static Duration`	`parse(CharSequence text)` Obtains an instance of `Duration` by parsing a text string.
`Duration`	`plus(Duration duration)` Returns a copy of this duration with the specified duration added.
`Duration`	`plus(long amountToAdd, TemporalUnit unit)` Returns a copy of this duration with the specified duration added.
`Duration`	`plusMillis(long millisToAdd)` Returns a copy of this duration with the specified duration in milliseconds added.
`Duration`	`plusNanos(long nanosToAdd)` Returns a copy of this duration with the specified duration in nanoseconds added.
`Duration`	`plusSeconds(long secondsToAdd)` Returns a copy of this duration with the specified duration in seconds added.
`Temporal`	`subtractFrom(Temporal temporal)` Subtracts this duration from the specified temporal object.
`long`	`toMillis()` Converts this duration to the total length in milliseconds.
`long`	`toNanos()` Converts this duration to the total length in nanoseconds expressed as a `long`.
`String`	`toString()` A string representation of this duration using ISO-8601 seconds based representation, such as `PT12.345S`.

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

- Field Detail
  - ZERO
```
public static final Duration ZERO
```
    Constant for a duration of zero.
- Method Detail
  - ofSeconds
```
public static Duration ofSeconds(long seconds)
```
    Obtains an instance of Duration from a number of seconds.
    The nanosecond in second field is set to zero.
    
    Parameters:
    seconds - the number of seconds, positive or negative
    
    Returns:
    a Duration, not null
  - ofSeconds
```
public static Duration ofSeconds(long seconds,
                 long nanoAdjustment)
```
    Obtains an instance of Duration from a number of seconds and an adjustment in nanoseconds.
    This method allows an arbitrary number of nanoseconds to be passed in. The factory will alter the values of the second and nanosecond in order to ensure that the stored nanosecond is in the range 0 to 999,999,999. For example, the following will result in the exactly the same duration:
```
  Duration.ofSeconds(3, 1);
  Duration.ofSeconds(4, -999_999_999);
  Duration.ofSeconds(2, 1000_000_001);
 
```
    Parameters:
    seconds - the number of seconds, positive or negative
    nanoAdjustment - the nanosecond adjustment to the number of seconds, positive or negative
    
    Returns:
    a Duration, not null
    
    Throws:
    
    ArithmeticException - if the adjustment causes the seconds to exceed the capacity of Duration
  - ofMillis
```
public static Duration ofMillis(long millis)
```
    Obtains an instance of Duration from a number of milliseconds.
    The seconds and nanoseconds are extracted from the specified milliseconds.
    
    Parameters:
    millis - the number of milliseconds, positive or negative
    
    Returns:
    a Duration, not null
  - ofNanos
```
public static Duration ofNanos(long nanos)
```
    Obtains an instance of Duration from a number of nanoseconds.
    The seconds and nanoseconds are extracted from the specified nanoseconds.
    
    Parameters:
    nanos - the number of nanoseconds, positive or negative
    
    Returns:
    a Duration, not null
  - ofMinutes
```
public static Duration ofMinutes(long minutes)
```
    Obtains an instance of Duration from a number of standard length minutes.
    The seconds are calculated based on the standard definition of a minute, where each minute is 60 seconds. The nanosecond in second field is set to zero.
    
    Parameters:
    minutes - the number of minutes, positive or negative
    
    Returns:
    a Duration, not null
    
    Throws:
    
    ArithmeticException - if the input minutes exceeds the capacity of Duration
  - ofHours
```
public static Duration ofHours(long hours)
```
    Obtains an instance of Duration from a number of standard length hours.
    The seconds are calculated based on the standard definition of an hour, where each hour is 3600 seconds. The nanosecond in second field is set to zero.
    
    Parameters:
    hours - the number of hours, positive or negative
    
    Returns:
    a Duration, not null
    
    Throws:
    
    ArithmeticException - if the input hours exceeds the capacity of Duration
  - ofDays
```
public static Duration ofDays(long days)
```
    Obtains an instance of Duration from a number of standard 24 hour days.
    The seconds are calculated based on the standard definition of a day, where each day is 86400 seconds which implies a 24 hour day. The nanosecond in second field is set to zero.
    
    Parameters:
    days - the number of days, positive or negative
    
    Returns:
    a Duration, not null
    
    Throws:
    
    ArithmeticException - if the input days exceeds the capacity of Duration
  - of
```
public static Duration of(long amount,
          TemporalUnit unit)
```
    Obtains an instance of Duration from a duration in the specified unit.
    The parameters represent the two parts of a phrase like '6 Hours'. For example:
```
  Duration.of(3, SECONDS);
  Duration.of(465, HOURS);
 
```
    Only a subset of units are accepted by this method. The unit must either have an exact duration or be ChronoUnit.DAYS which is treated as 24 hours. Other units throw an exception.
    Parameters:
    amount - the amount of the duration, measured in terms of the unit, positive or negative
    unit - the unit that the duration is measured in, must have an exact duration, not null
    
    Returns:
    a Duration, not null
    
    Throws:
    
    DateTimeException - if the period unit has an estimated duration
    
    ArithmeticException - if a numeric overflow occurs
  - between
```
public static Duration between(TemporalAccessor startInclusive,
               TemporalAccessor endExclusive)
```
    Obtains an instance of Duration representing the duration between two instants.
    A Duration represents a directed distance between two points on the time-line. As such, this method will return a negative duration if the end is before the start. To guarantee to obtain a positive duration call abs() on the result of this factory.
    
    Parameters:
    startInclusive - the start instant, inclusive, not null
    endExclusive - the end instant, exclusive, not null
    
    Returns:
    a Duration, not null
    
    Throws:
    
    ArithmeticException - if the calculation exceeds the capacity of Duration
  - parse
```
public static Duration parse(CharSequence text)
```
    Obtains an instance of Duration by parsing a text string.
    This will parse the string produced by toString() which is the ISO-8601 format PTnS where n is the number of seconds with optional decimal part. The number must consist of ASCII numerals. There must only be a negative sign at the start of the number and it can only be present if the value is less than zero. There must be at least one digit before any decimal point. There must be between 1 and 9 inclusive digits after any decimal point. The letters (P, T and S) will be accepted in upper or lower case. The decimal point may be either a dot or a comma.
    
    Parameters:
    text - the text to parse, not null
    
    Returns:
    a Duration, not null
    
    Throws:
    
    DateTimeParseException - if the text cannot be parsed to a Duration
  - isZero
```
public boolean isZero()
```
    Checks if this duration is zero length.
    A Duration represents a directed distance between two points on the time-line and can therefore be positive, zero or negative. This method checks whether the length is zero.
    
    Returns:
    true if this duration has a total length equal to zero
  - isPositive
```
public boolean isPositive()
```
    Checks if this duration is positive, excluding zero.
    A Duration represents a directed distance between two points on the time-line and can therefore be positive, zero or negative. This method checks whether the length is greater than zero.
    
    Returns:
    true if this duration has a total length greater than zero
  - isNegative
```
public boolean isNegative()
```
    Checks if this duration is negative, excluding zero.
    A Duration represents a directed distance between two points on the time-line and can therefore be positive, zero or negative. This method checks whether the length is less than zero.
    
    Returns:
    true if this duration has a total length less than zero
  - getSeconds
```
public long getSeconds()
```
    Gets the number of seconds in this duration.
    The length of the duration is stored using two fields - seconds and nanoseconds. The nanoseconds part is a value from 0 to 999,999,999 that is an adjustment to the length in seconds. The total duration is defined by calling this method and getNano().
    A Duration represents a directed distance between two points on the time-line. A negative duration is expressed by the negative sign of the seconds part. A duration of -1 nanosecond is stored as -1 seconds plus 999,999,999 nanoseconds.
    
    Returns:
    the whole seconds part of the length of the duration, positive or negative
  - getNano
```
public int getNano()
```
    Gets the number of nanoseconds within the second in this duration.
    The length of the duration is stored using two fields - seconds and nanoseconds. The nanoseconds part is a value from 0 to 999,999,999 that is an adjustment to the length in seconds. The total duration is defined by calling this method and getSeconds().
    A Duration represents a directed distance between two points on the time-line. A negative duration is expressed by the negative sign of the seconds part. A duration of -1 nanosecond is stored as -1 seconds plus 999,999,999 nanoseconds.
    
    Returns:
    the nanoseconds within the second part of the length of the duration, from 0 to 999,999,999
  - plus
```
public Duration plus(Duration duration)
```
    Returns a copy of this duration with the specified duration added.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    duration - the duration to add, positive or negative, not null
    
    Returns:
    a Duration based on this duration with the specified duration added, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - plus
```
public Duration plus(long amountToAdd,
            TemporalUnit unit)
```
    Returns a copy of this duration with the specified duration added.
    The duration amount is measured in terms of the specified unit. Only a subset of units are accepted by this method. The unit must either have an exact duration or be ChronoUnit.DAYS which is treated as 24 hours. Other units throw an exception.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    amountToAdd - the amount of the period, measured in terms of the unit, positive or negative
    unit - the unit that the period is measured in, must have an exact duration, not null
    
    Returns:
    a Duration based on this duration with the specified duration added, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - plusSeconds
```
public Duration plusSeconds(long secondsToAdd)
```
    Returns a copy of this duration with the specified duration in seconds added.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    secondsToAdd - the seconds to add, positive or negative
    
    Returns:
    a Duration based on this duration with the specified seconds added, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - plusMillis
```
public Duration plusMillis(long millisToAdd)
```
    Returns a copy of this duration with the specified duration in milliseconds added.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    millisToAdd - the milliseconds to add, positive or negative
    
    Returns:
    a Duration based on this duration with the specified milliseconds added, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - plusNanos
```
public Duration plusNanos(long nanosToAdd)
```
    Returns a copy of this duration with the specified duration in nanoseconds added.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    nanosToAdd - the nanoseconds to add, positive or negative
    
    Returns:
    a Duration based on this duration with the specified nanoseconds added, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - minus
```
public Duration minus(Duration duration)
```
    Returns a copy of this duration with the specified duration subtracted.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    duration - the duration to subtract, positive or negative, not null
    
    Returns:
    a Duration based on this duration with the specified duration subtracted, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - minus
```
public Duration minus(long amountToSubtract,
             TemporalUnit unit)
```
    Returns a copy of this duration with the specified duration subtracted.
    The duration amount is measured in terms of the specified unit. Only a subset of units are accepted by this method. The unit must either have an exact duration or be ChronoUnit.DAYS which is treated as 24 hours. Other units throw an exception.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    amountToSubtract - the amount of the period, measured in terms of the unit, positive or negative
    unit - the unit that the period is measured in, must have an exact duration, not null
    
    Returns:
    a Duration based on this duration with the specified duration subtracted, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - minusSeconds
```
public Duration minusSeconds(long secondsToSubtract)
```
    Returns a copy of this duration with the specified duration in seconds subtracted.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    secondsToSubtract - the seconds to subtract, positive or negative
    
    Returns:
    a Duration based on this duration with the specified seconds subtracted, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - minusMillis
```
public Duration minusMillis(long millisToSubtract)
```
    Returns a copy of this duration with the specified duration in milliseconds subtracted.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    millisToSubtract - the milliseconds to subtract, positive or negative
    
    Returns:
    a Duration based on this duration with the specified milliseconds subtracted, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - minusNanos
```
public Duration minusNanos(long nanosToSubtract)
```
    Returns a copy of this duration with the specified duration in nanoseconds subtracted.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    nanosToSubtract - the nanoseconds to subtract, positive or negative
    
    Returns:
    a Duration based on this duration with the specified nanoseconds subtracted, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - multipliedBy
```
public Duration multipliedBy(long multiplicand)
```
    Returns a copy of this duration multiplied by the scalar.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    multiplicand - the value to multiply the duration by, positive or negative
    
    Returns:
    a Duration based on this duration multiplied by the specified scalar, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - dividedBy
```
public Duration dividedBy(long divisor)
```
    Returns a copy of this duration divided by the specified value.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    divisor - the value to divide the duration by, positive or negative, not zero
    
    Returns:
    a Duration based on this duration divided by the specified divisor, not null
    
    Throws:
    
    ArithmeticException - if the divisor is zero
    
    ArithmeticException - if numeric overflow occurs
  - negated
```
public Duration negated()
```
    Returns a copy of this duration with the length negated.
    This method swaps the sign of the total length of this duration. For example, PT1.3S will be returned as PT-1.3S.
    This instance is immutable and unaffected by this method call.
    
    Returns:
    a Duration based on this duration with the amount negated, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - abs
```
public Duration abs()
```
    Returns a copy of this duration with a positive length.
    This method returns a positive duration by effectively removing the sign from any negative total length. For example, PT-1.3S will be returned as PT1.3S.
    This instance is immutable and unaffected by this method call.
    
    Returns:
    a Duration based on this duration with an absolute length, not null
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - addTo
```
public Temporal addTo(Temporal temporal)
```
    Adds this duration to the specified temporal object.
    This returns a temporal object of the same observable type as the input with this duration added.
    In most cases, it is clearer to reverse the calling pattern by using Temporal.plus(TemporalAdder).
```
   // these two lines are equivalent, but the second approach is recommended
   dateTime = thisDuration.addTo(dateTime);
   dateTime = dateTime.plus(thisDuration);
 
```
    A Duration can only be added to a Temporal that represents an instant and can supply ChronoField.INSTANT_SECONDS.
    This instance is immutable and unaffected by this method call.
    Specified by:
    
    addTo in interface TemporalAdder
    
    Parameters:
    temporal - the temporal object to adjust, not null
    
    Returns:
    an object of the same type with the adjustment made, not null
    
    Throws:
    
    DateTimeException - if unable to add
    
    ArithmeticException - if numeric overflow occurs
  - subtractFrom
```
public Temporal subtractFrom(Temporal temporal)
```
    Subtracts this duration from the specified temporal object.
    This returns a temporal object of the same observable type as the input with this duration subtracted.
    In most cases, it is clearer to reverse the calling pattern by using Temporal.minus(TemporalSubtractor).
```
   // these two lines are equivalent, but the second approach is recommended
   dateTime = thisDuration.subtractFrom(dateTime);
   dateTime = dateTime.minus(thisDuration);
 
```
    A Duration can only be subtracted from a Temporal that represents an instant and can supply ChronoField.INSTANT_SECONDS.
    This instance is immutable and unaffected by this method call.
    Specified by:
    
    subtractFrom in interface TemporalSubtractor
    
    Parameters:
    temporal - the temporal object to adjust, not null
    
    Returns:
    an object of the same type with the adjustment made, not null
    
    Throws:
    
    DateTimeException - if unable to subtract
    
    ArithmeticException - if numeric overflow occurs
  - toMillis
```
public long toMillis()
```
    Converts this duration to the total length in milliseconds.
    If this duration is too large to fit in a long milliseconds, then an exception is thrown.
    If this duration has greater than millisecond precision, then the conversion will drop any excess precision information as though the amount in nanoseconds was subject to integer division by one million.
    
    Returns:
    the total length of the duration in milliseconds
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - toNanos
```
public long toNanos()
```
    Converts this duration to the total length in nanoseconds expressed as a long.
    If this duration is too large to fit in a long nanoseconds, then an exception is thrown.
    
    Returns:
    the total length of the duration in nanoseconds
    
    Throws:
    
    ArithmeticException - if numeric overflow occurs
  - compareTo
```
public int compareTo(Duration otherDuration)
```
    Compares this duration to the specified Duration.
    The comparison is based on the total length of the durations. It is "consistent with equals", as defined by Comparable.
    
    Specified by:
    
    compareTo in interface Comparable<Duration>
    
    Parameters:
    otherDuration - the other duration to compare to, not null
    
    Returns:
    the comparator value, negative if less, positive if greater
  - isGreaterThan
```
public boolean isGreaterThan(Duration otherDuration)
```
    Checks if this duration is greater than the specified Duration.
    The comparison is based on the total length of the durations.
    
    Parameters:
    otherDuration - the other duration to compare to, not null
    
    Returns:
    true if this duration is greater than the specified duration
  - isLessThan
```
public boolean isLessThan(Duration otherDuration)
```
    Checks if this duration is less than the specified Duration.
    The comparison is based on the total length of the durations.
    
    Parameters:
    otherDuration - the other duration to compare to, not null
    
    Returns:
    true if this duration is less than the specified duration
  - equals
```
public boolean equals(Object otherDuration)
```
    Checks if this duration is equal to the specified Duration.
    The comparison is based on the total length of the durations.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    otherDuration - the other duration, null returns false
    
    Returns:
    true if the other duration is equal to this one
  - hashCode
```
public int hashCode()
```
    A hash code for this duration.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    a suitable hash code
  - toString
```
public String toString()
```
    A string representation of this duration using ISO-8601 seconds based representation, such as PT12.345S.
    The format of the returned string will be PTnS where n is the seconds and fractional seconds of the duration.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    an ISO-8601 representation of this duration, not null

Class Duration

Specification for implementors

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ZERO

Method Detail

ofSeconds

ofSeconds

ofMillis

ofNanos

ofMinutes

ofHours

ofDays

of

between

parse

isZero

isPositive

isNegative

getSeconds

getNano

plus

plus

plusSeconds

plusMillis

plusNanos

minus

minus

minusSeconds

minusMillis

minusNanos

multipliedBy

dividedBy

negated

abs

addTo

subtractFrom

toMillis

toNanos

compareTo

isGreaterThan

isLessThan

equals

hashCode

toString