

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object javax.time.Duration
public final class Duration
A duration between two instants on the timeline.
The Time Framework for Java models time as a series of instantaneous events,
known as instants
, along a single timeline.
This class represents the duration between two of those instants.
The model is of a directed duration, meaning that the duration may be negative.
A physical instant is an instantaneous event. However, for practicality the API and this class uses a precision of nanoseconds.
A physical duration could be of infinite length.
However, for practicality the API and this class limits the length to the
number of seconds that can be held in a long
.
In order to represent the data a 96 bit number is required. To achieve this the
data is stored as seconds, measured using a long
, and nanoseconds,
measured using an int
. The nanosecond part will always be between
0 and 999,999,999 representing the nanosecond part of the second.
For example, the negative duration of PT0.1S
is represented as
1 second and 900,000,000 nanoseconds.
In this API, the unit of "seconds" only has a precise meaning when applied to an instant.
This is because it is the instant that defines the time scale used, not the duration.
For example, the timescale used by Instant
uses a variable length second to
avoid exposing leap seconds. By comparison, the TAI time scale follows the international
scientific definition of a second exactly. For most applications, this subtlety will be irrelevant.
This class is immutable and threadsafe.
Field Summary  

static Duration 
ZERO
Constant for a duration of zero. 
Method Summary  

Duration 
abs()
Returns a copy of this duration with a positive length. 
static Duration 
between(InstantProvider startInclusive,
InstantProvider 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(java.lang.Object otherDuration)
Checks if this duration is equal to the specified Duration . 
long 
get(java.util.concurrent.TimeUnit unit)
Gets the duration in terms of the specified unit. 
int 
getNanoOfSecond()
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 
isNegativeOrZero()
Checks if this duration is negative or zero. 
boolean 
isPositive()
Checks if this duration is positive, excluding zero. 
boolean 
isPositiveOrZero()
Checks if this duration is positive or 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 amount,
java.util.concurrent.TimeUnit 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 number of milliseconds subtracted. 
Duration 
minusNanos(long nanosToSubtract)
Returns a copy of this duration with the specified number of nanoseconds subtracted. 
Duration 
minusSeconds(long secondsToSubtract)
Returns a copy of this duration with the specified number of 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,
java.util.concurrent.TimeUnit unit)
Obtains an instance of Duration from a duration in a specified time 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(java.math.BigInteger nanos)
Obtains an instance of Duration from a number of nanoseconds. 
static Duration 
ofNanos(long nanos)
Obtains an instance of Duration from a number of nanoseconds. 
static Duration 
ofSeconds(java.math.BigDecimal seconds)
Obtains an instance of Duration from a number of seconds. 
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(java.lang.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 amount,
java.util.concurrent.TimeUnit 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 number of milliseconds added. 
Duration 
plusNanos(long nanosToAdd)
Returns a copy of this duration with the specified number of nanoseconds added. 
Duration 
plusSeconds(long secondsToAdd)
Returns a copy of this duration with the specified number of seconds added. 
long 
toMillisLong()
Converts this duration to the total length in milliseconds. 
java.math.BigInteger 
toNanos()
Converts this duration to the total length in nanoseconds expressed as a BigInteger . 
long 
toNanosLong()
Converts this duration to the total length in nanoseconds expressed as a long . 
java.math.BigDecimal 
toSeconds()
Converts this duration to the total length in seconds and fractional nanoseconds expressed as a BigDecimal . 
java.lang.String 
toString()
A string representation of this duration using ISO8601 seconds based representation, such as PT12.345S . 
Methods inherited from class java.lang.Object 

clone, finalize, getClass, notify, notifyAll, wait, wait, wait 
Field Detail 

public static final Duration ZERO
Method Detail 

public static Duration ofSeconds(long seconds)
Duration
from a number of seconds.
The nanosecond in second field is set to zero.
seconds
 the number of seconds, positive or negative
Duration
, not nullpublic static Duration ofSeconds(long seconds, long nanoAdjustment)
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, 999999999); Duration.ofSeconds(2, 1000000001);
seconds
 the number of seconds, positive or negativenanoAdjustment
 the nanosecond adjustment to the number of seconds, positive or negative
Duration
, not null
java.lang.ArithmeticException
 if the adjustment causes the seconds to exceed the capacity of Duration
public static Duration ofSeconds(java.math.BigDecimal seconds)
Duration
from a number of seconds.
The seconds and nanoseconds are extracted from the specified BigDecimal
.
If the decimal is larger than Long.MAX_VALUE
or has more than 9 decimal
places then an exception is thrown.
seconds
 the number of seconds, up to scale 9, positive or negative
Duration
, not null
java.lang.ArithmeticException
 if the input seconds exceeds the capacity of a Duration
public static Duration ofMillis(long millis)
Duration
from a number of milliseconds.
The seconds and nanoseconds are extracted from the specified milliseconds.
millis
 the number of milliseconds, positive or negative
Duration
, not nullpublic static Duration ofNanos(long nanos)
Duration
from a number of nanoseconds.
The seconds and nanoseconds are extracted from the specified nanoseconds.
nanos
 the number of nanoseconds, positive or negative
Duration
, not nullpublic static Duration ofNanos(java.math.BigInteger nanos)
Duration
from a number of nanoseconds.
The seconds and nanoseconds are extracted from the specified BigInteger
.
If the resulting seconds value is larger than Long.MAX_VALUE
then an
exception is thrown.
nanos
 the number of nanoseconds, positive or negative, not null
Duration
, not null
java.lang.ArithmeticException
 if the input nanoseconds exceeds the capacity of Duration
public static Duration ofMinutes(long minutes)
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.
minutes
 the number of minutes, positive or negative
Duration
, not null
java.lang.ArithmeticException
 if the input minutes exceeds the capacity of Duration
public static Duration ofHours(long hours)
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.
hours
 the number of hours, positive or negative
Duration
, not null
java.lang.ArithmeticException
 if the input hours exceeds the capacity of Duration
public static Duration ofDays(long days)
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.
days
 the number of days, positive or negative
Duration
, not null
java.lang.ArithmeticException
 if the input days exceeds the capacity of Duration
public static Duration of(long amount, java.util.concurrent.TimeUnit unit)
Duration
from a duration in a specified time unit.
The duration amount is measured in terms of the specified unit. For example:
Duration.of(3, TimeUnit.SECONDS); Duration.of(465, TimeUnit.MICROSECONDS);
amount
 the amount of the duration, positive or negativeunit
 the unit that the duration is measured in, not null
Duration
, not null
java.lang.ArithmeticException
 if the input amount exceeds the capacity of Duration
which can only occur for units MINUTES, HOURS and DAYSpublic static Duration between(InstantProvider startInclusive, InstantProvider endExclusive)
Duration
representing the duration between two instants.
A Duration
represents a directed distance between two points on the timeline.
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.
startInclusive
 the start instant, inclusive, not nullendExclusive
 the end instant, exclusive, not null
Duration
, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public static Duration parse(java.lang.CharSequence text)
Duration
by parsing a text string.
This will parse the string produced by toString()
which is
the ISO8601 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.
text
 the text to parse, not null
Duration
, not null
CalendricalParseException
 if the text cannot be parsed to a Duration
public boolean isZero()
A Duration
represents a directed distance between two points on
the timeline and can therefore be positive, zero or negative.
This method checks whether the length is zero.
public boolean isPositive()
A Duration
represents a directed distance between two points on
the timeline and can therefore be positive, zero or negative.
This method checks whether the length is greater than zero.
public boolean isPositiveOrZero()
A Duration
represents a directed distance between two points on
the timeline and can therefore be positive, zero or negative.
This method checks whether the length is greater than or equal to zero.
public boolean isNegative()
A Duration
represents a directed distance between two points on
the timeline and can therefore be positive, zero or negative.
This method checks whether the length is less than zero.
public boolean isNegativeOrZero()
A Duration
represents a directed distance between two points on
the timeline and can therefore be positive, zero or negative.
This method checks whether the length is less than or equal to zero.
public long getSeconds()
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 getNanoOfSecond()
.
A Duration
represents a directed distance between two points on the timeline.
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.
public int getNanoOfSecond()
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 timeline.
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.
public long get(java.util.concurrent.TimeUnit unit)
This method returns the duration converted to the unit, truncating
excess precision.
If the conversion would overflow, the result will saturate to
Long.MAX_VALUE
or Long.MIN_VALUE
.
Long.MAX_VALUE
and Long.MIN_VALUE
, positive or negativepublic Duration plus(Duration duration)
Duration
added.
This instance is immutable and unaffected by this method call.
duration
 the duration to add, positive or negative, not null
Duration
based on this duration with the specified duration added, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration plus(long amount, java.util.concurrent.TimeUnit unit)
The duration to be added is measured in terms of the specified unit.
This instance is immutable and unaffected by this method call.
amount
 the duration to add, positive or negativeunit
 the unit that the duration is measured in, not null
Duration
based on this duration with the specified duration added, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration plusSeconds(long secondsToAdd)
This instance is immutable and unaffected by this method call.
secondsToAdd
 the seconds to add, positive or negative
Duration
based on this duration with the specified seconds added, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration plusMillis(long millisToAdd)
This instance is immutable and unaffected by this method call.
millisToAdd
 the milliseconds to add, positive or negative
Duration
based on this duration with the specified milliseconds added, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration plusNanos(long nanosToAdd)
This instance is immutable and unaffected by this method call.
nanosToAdd
 the nanoseconds to add, positive or negative
Duration
based on this duration with the specified nanoseconds added, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration minus(Duration duration)
Duration
subtracted.
This instance is immutable and unaffected by this method call.
duration
 the duration to subtract, positive or negative, not null
Duration
based on this duration with the specified duration subtracted, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration minus(long amount, java.util.concurrent.TimeUnit unit)
The duration to be subtracted is measured in terms of the specified unit.
This instance is immutable and unaffected by this method call.
amount
 the duration to subtract, positive or negativeunit
 the unit that the duration is measured in, not null
Duration
based on this duration with the specified duration subtracted, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration minusSeconds(long secondsToSubtract)
This instance is immutable and unaffected by this method call.
secondsToSubtract
 the seconds to subtract, positive or negative
Duration
based on this duration with the specified seconds subtracted, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration minusMillis(long millisToSubtract)
This instance is immutable and unaffected by this method call.
millisToSubtract
 the milliseconds to subtract, positive or negative
Duration
based on this duration with the specified milliseconds subtracted, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration minusNanos(long nanosToSubtract)
This instance is immutable and unaffected by this method call.
nanosToSubtract
 the nanoseconds to subtract, positive or negative
Duration
based on this duration with the specified nanoseconds subtracted, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration multipliedBy(long multiplicand)
This instance is immutable and unaffected by this method call.
multiplicand
 the value to multiply the duration by, positive or negative
Duration
based on this duration multiplied by the specified scalar, not null
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration dividedBy(long divisor)
This instance is immutable and unaffected by this method call.
divisor
 the value to divide the duration by, positive or negative, not zero
Duration
based on this duration divided by the specified divisor, not null
java.lang.ArithmeticException
 if the divisor is zero
java.lang.ArithmeticException
 if the calculation exceeds the capacity of Duration
public Duration negated()
This method swaps the sign of the total length of this duration.
For example, PT1.3S
will be returned as PT1.3S
.
This instance is immutable and unaffected by this method call.
Duration
based on this period with the amount negated, not null
java.lang.ArithmeticException
 if the seconds part of the length is Long.MIN_VALUE
public Duration abs()
This method returns a positive duration by effectively removing the sign from any negative total length.
For example, PT1.3S
will be returned as PT1.3S
.
This instance is immutable and unaffected by this method call.
Duration
based on this period with an absolute length, not null
java.lang.ArithmeticException
 if the seconds part of the length is Long.MIN_VALUE
public java.math.BigDecimal toSeconds()
BigDecimal
.
public java.math.BigInteger toNanos()
BigInteger
.
public long toNanosLong()
long
.
If this duration is too large to fit in a long
nanoseconds, then an
exception is thrown.
java.lang.ArithmeticException
 if the length exceeds the capacity of a long
public long toMillisLong()
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.
java.lang.ArithmeticException
 if the length exceeds the capacity of a long
public int compareTo(Duration otherDuration)
Duration
.
The comparison is based on the total length of the durations.
compareTo
in interface java.lang.Comparable<Duration>
otherDuration
 the other duration to compare to, not null
public boolean isGreaterThan(Duration otherDuration)
Duration
.
The comparison is based on the total length of the durations.
otherDuration
 the other duration to compare to, not null
public boolean isLessThan(Duration otherDuration)
Duration
.
The comparison is based on the total length of the durations.
otherDuration
 the other duration to compare to, not null
public boolean equals(java.lang.Object otherDuration)
Duration
.
The comparison is based on the total length of the durations.
equals
in class java.lang.Object
otherDuration
 the other duration, null returns false
public int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
PT12.345S
.
The format of the returned string will be PTnS
where n is
the seconds and fractional seconds of the duration.
toString
in class java.lang.Object


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 