public final class Duration extends Object implements Comparable<Duration>, Serializable
The Time Framework for Java models time as a series of instantaneous events,
known as instants
, along a single time-line.
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 PT-0.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 simplified UTC time scale used by Instant
ignores leap seconds,
which alters the effective length of a second. By comparison, the TAI time scale follows
the international scientific definition of a second exactly.
For most applications, this subtlety will be irrelevant.
Duration is immutable and thread-safe.
Modifier and Type | Field and Description |
---|---|
static Duration |
ZERO
Constant for a duration of zero.
|
Modifier and Type | Method and Description |
---|---|
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(Object otherDuration)
Checks if this duration is equal to the specified
Duration . |
long |
get(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,
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,
TimeUnit unit)
Obtains an instance of
Duration from a duration in a specified time unit. |
static Duration |
ofMillis(long millis)
Obtains an instance of
Duration from a number of milliseconds. |
static Duration |
ofNanos(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(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 |
ofStandardDays(long days)
Obtains an instance of
Duration from a number of standard length days. |
static Duration |
ofStandardHours(long hours)
Obtains an instance of
Duration from a number of standard length hours. |
static Duration |
ofStandardMinutes(long minutes)
Obtains an instance of
Duration from a number of standard length minutes. |
static Duration |
parse(String text)
Obtains an instance of
Duration by parsing a string. |
Duration |
plus(Duration duration)
Returns a copy of this duration with the specified
Duration added. |
Duration |
plus(long amount,
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.
|
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 . |
BigDecimal |
toSeconds()
Converts this duration to the total length in seconds and
fractional nanoseconds expressed as a
BigDecimal . |
String |
toString()
A string representation of this duration using ISO-8601 seconds
based representation, such as
PT12.345S . |
public static final Duration ZERO
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 negativeDuration
, never 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 negativeDuration
, never nullArithmeticException
- if the adjustment causes the seconds to exceed the capacity of Duration
public static Duration ofSeconds(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 negativeDuration
, never nullArithmeticException
- 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 negativeDuration
, never 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 negativeDuration
, never nullpublic static Duration ofNanos(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 nullDuration
, never nullArithmeticException
- if the input nanoseconds exceeds the capacity of Duration
public static Duration ofStandardMinutes(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 negativeDuration
, never nullArithmeticException
- if the input minutes exceeds the capacity of Duration
public static Duration ofStandardHours(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 negativeDuration
, never nullArithmeticException
- if the input hours exceeds the capacity of Duration
public static Duration ofStandardDays(long days)
Duration
from a number of standard length 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 negativeDuration
, never nullArithmeticException
- if the input days exceeds the capacity of Duration
public static Duration of(long amount, 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 nullDuration
, never nullArithmeticException
- 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 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.
startInclusive
- the start instant, inclusive, not nullendExclusive
- the end instant, exclusive, not nullDuration
, never nullArithmeticException
- if the calculation exceeds the capacity of Duration
public static Duration parse(String text)
Duration
by parsing a 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.
text
- the text to parse, not nullDuration
, never nullCalendricalParseException
- if the text cannot be parsed to a Duration
public boolean isZero()
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.
public boolean isPositive()
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.
public boolean isPositiveOrZero()
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 or equal to zero.
public boolean isNegative()
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.
public boolean isNegativeOrZero()
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 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 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.
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 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.
public long get(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 nullDuration
based on this duration with the specified duration added, never nullArithmeticException
- if the calculation exceeds the capacity of Duration
public Duration plus(long amount, 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 nullDuration
based on this duration with the specified duration added, never nullArithmeticException
- 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 negativeDuration
based on this duration with the specified seconds added, never nullArithmeticException
- 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 negativeDuration
based on this duration with the specified milliseconds added, never nullArithmeticException
- 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 negativeDuration
based on this duration with the specified nanoseconds added, never nullArithmeticException
- 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 nullDuration
based on this duration with the specified duration subtracted, never nullArithmeticException
- if the calculation exceeds the capacity of Duration
public Duration minus(long amount, 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 nullDuration
based on this duration with the specified duration subtracted, never nullArithmeticException
- 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 negativeDuration
based on this duration with the specified seconds subtracted, never nullArithmeticException
- 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 negativeDuration
based on this duration with the specified milliseconds subtracted, never nullArithmeticException
- 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 negativeDuration
based on this duration with the specified nanoseconds subtracted, never nullArithmeticException
- 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 negativeDuration
based on this duration multiplied by the specified scalar, never nullArithmeticException
- 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 zeroDuration
based on this duration divided by the specified divisor, never nullArithmeticException
- if the divisor is zeroArithmeticException
- 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 PT-1.3S
.
This instance is immutable and unaffected by this method call.
Duration
based on this period with the amount negated, never nullArithmeticException
- 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, PT-1.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, never nullArithmeticException
- if the seconds part of the length is Long.MIN_VALUE
public BigDecimal toSeconds()
BigDecimal
.public BigInteger toNanos()
BigInteger
.public long toNanosLong()
long
.
If this duration is too large to fit in a long
nanoseconds, then an
exception is thrown.
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.
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 Comparable<Duration>
otherDuration
- the other duration to compare to, not nullpublic boolean isGreaterThan(Duration otherDuration)
Duration
.
The comparison is based on the total length of the durations.
otherDuration
- the other duration to compare to, not nullpublic boolean isLessThan(Duration otherDuration)
Duration
.
The comparison is based on the total length of the durations.
otherDuration
- the other duration to compare to, not nullpublic boolean equals(Object otherDuration)
Duration
.
The comparison is based on the total length of the durations.
public int hashCode()
public String toString()
PT12.345S
.
The format of the returned string will be PTnS
where n is
the seconds and fractional seconds of the duration.
Copyright © 2014. All rights reserved.