Class Duration
- All Implemented Interfaces:
Serializable
,Comparable<Duration>
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.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final BigInteger
Constant for maximum long.private static final BigInteger
Constant for minimum long.private static final BigInteger
Constant for nanos per day.private static final BigInteger
Constant for nanos per hour.private static final BigInteger
Constant for nanos per microsecond.private static final BigInteger
Constant for nanos per millisecond.private static final BigInteger
Constant for nanos per minute.private static final BigInteger
Constant for nanos per second.private final int
The number of nanoseconds in the duration, expressed as a fraction of the number of seconds.private static final int
Constant for nanos per second.private final long
The number of seconds in the duration.private static final long
Serialization version.static final Duration
Constant for a duration of zero. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Duration
(long seconds, int nanos) Constructs an instance ofDuration
using seconds and nanoseconds. -
Method Summary
Modifier and TypeMethodDescriptionabs()
Returns a copy of this duration with a positive length.static Duration
between
(InstantProvider startInclusive, InstantProvider endExclusive) Obtains an instance ofDuration
representing the duration between two instants.int
Compares this duration to the specifiedDuration
.private static Duration
create
(long seconds, int nanoAdjustment) Obtains an instance ofDuration
using seconds and nanoseconds.dividedBy
(long divisor) Returns a copy of this duration divided by the specified value.boolean
Checks if this duration is equal to the specifiedDuration
.long
Gets the duration in terms of the specified unit.int
Gets the number of nanoseconds within the second in this duration.long
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 specifiedDuration
.boolean
isLessThan
(Duration otherDuration) Checks if this duration is less than the specifiedDuration
.boolean
Checks if this duration is negative, excluding zero.boolean
Checks if this duration is negative or zero.boolean
Checks if this duration is positive, excluding zero.boolean
Checks if this duration is positive or zero.boolean
isZero()
Checks if this duration is zero length.Returns a copy of this duration with the specified duration subtracted.Returns a copy of this duration with the specifiedDuration
subtracted.minusMillis
(long millisToSubtract) Returns a copy of this duration with the specified number of milliseconds subtracted.minusNanos
(long nanosToSubtract) Returns a copy of this duration with the specified number of nanoseconds subtracted.minusSeconds
(long secondsToSubtract) Returns a copy of this duration with the specified number of seconds subtracted.multipliedBy
(long multiplicand) Returns a copy of this duration multiplied by the scalar.negated()
Returns a copy of this duration with the length negated.static Duration
Obtains an instance ofDuration
from a duration in a specified time unit.static Duration
ofMillis
(long millis) Obtains an instance ofDuration
from a number of milliseconds.static Duration
ofNanos
(long nanos) Obtains an instance ofDuration
from a number of nanoseconds.static Duration
ofNanos
(BigInteger nanos) Obtains an instance ofDuration
from a number of nanoseconds.static Duration
ofSeconds
(long seconds) Obtains an instance ofDuration
from a number of seconds.static Duration
ofSeconds
(long seconds, long nanoAdjustment) Obtains an instance ofDuration
from a number of seconds and an adjustment in nanoseconds.static Duration
ofSeconds
(BigDecimal seconds) Obtains an instance ofDuration
from a number of seconds.static Duration
ofStandardDays
(long days) Obtains an instance ofDuration
from a number of standard length days.static Duration
ofStandardHours
(long hours) Obtains an instance ofDuration
from a number of standard length hours.static Duration
ofStandardMinutes
(long minutes) Obtains an instance ofDuration
from a number of standard length minutes.static Duration
Obtains an instance ofDuration
by parsing a string.Returns a copy of this duration with the specified duration added.Returns a copy of this duration with the specifiedDuration
added.plusMillis
(long millisToAdd) Returns a copy of this duration with the specified number of milliseconds added.plusNanos
(long nanosToAdd) Returns a copy of this duration with the specified number of nanoseconds added.plusSeconds
(long secondsToAdd) Returns a copy of this duration with the specified number of seconds added.private Object
Resolves singletons.long
Converts this duration to the total length in milliseconds.toNanos()
Converts this duration to the total length in nanoseconds expressed as aBigInteger
.long
Converts this duration to the total length in nanoseconds expressed as along
.Converts this duration to the total length in seconds and fractional nanoseconds expressed as aBigDecimal
.toString()
A string representation of this duration using ISO-8601 seconds based representation, such asPT12.345S
.
-
Field Details
-
ZERO
Constant for a duration of zero. -
serialVersionUID
private static final long serialVersionUIDSerialization version.- See Also:
-
NANOS_PER_SECOND
private static final int NANOS_PER_SECONDConstant for nanos per second.- See Also:
-
BI_NANOS_PER_MICRO
Constant for nanos per microsecond. -
BI_NANOS_PER_MILLI
Constant for nanos per millisecond. -
BI_NANOS_PER_SECOND
Constant for nanos per second. -
BI_NANOS_PER_MINUTE
Constant for nanos per minute. -
BI_NANOS_PER_HOUR
Constant for nanos per hour. -
BI_NANOS_PER_DAY
Constant for nanos per day. -
BI_MAX_LONG
Constant for maximum long. -
BI_MIN_LONG
Constant for minimum long. -
seconds
private final long secondsThe number of seconds in the duration. -
nanos
private final int nanosThe number of nanoseconds in the duration, expressed as a fraction of the number of seconds. This is always positive, and never exceeds 999,999,999.
-
-
Constructor Details
-
Duration
private Duration(long seconds, int nanos) Constructs an instance ofDuration
using seconds and nanoseconds.- Parameters:
seconds
- the length of the duration in seconds, positive or negativenanos
- the nanoseconds within the second, from 0 to 999,999,999
-
-
Method Details
-
ofSeconds
Obtains an instance ofDuration
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
, never null
-
ofSeconds
Obtains an instance ofDuration
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);
- Parameters:
seconds
- the number of seconds, positive or negativenanoAdjustment
- the nanosecond adjustment to the number of seconds, positive or negative- Returns:
- a
Duration
, never null - Throws:
ArithmeticException
- if the adjustment causes the seconds to exceed the capacity ofDuration
-
ofSeconds
Obtains an instance ofDuration
from a number of seconds.The seconds and nanoseconds are extracted from the specified
BigDecimal
. If the decimal is larger thanLong.MAX_VALUE
or has more than 9 decimal places then an exception is thrown.- Parameters:
seconds
- the number of seconds, up to scale 9, positive or negative- Returns:
- a
Duration
, never null - Throws:
ArithmeticException
- if the input seconds exceeds the capacity of aDuration
-
ofMillis
Obtains an instance ofDuration
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
, never null
-
ofNanos
Obtains an instance ofDuration
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
, never null
-
ofNanos
Obtains an instance ofDuration
from a number of nanoseconds.The seconds and nanoseconds are extracted from the specified
BigInteger
. If the resulting seconds value is larger thanLong.MAX_VALUE
then an exception is thrown.- Parameters:
nanos
- the number of nanoseconds, positive or negative, not null- Returns:
- a
Duration
, never null - Throws:
ArithmeticException
- if the input nanoseconds exceeds the capacity ofDuration
-
ofStandardMinutes
Obtains an instance ofDuration
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
, never null - Throws:
ArithmeticException
- if the input minutes exceeds the capacity ofDuration
-
ofStandardHours
Obtains an instance ofDuration
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
, never null - Throws:
ArithmeticException
- if the input hours exceeds the capacity ofDuration
-
ofStandardDays
Obtains an instance ofDuration
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.
- Parameters:
days
- the number of days, positive or negative- Returns:
- a
Duration
, never null - Throws:
ArithmeticException
- if the input days exceeds the capacity ofDuration
-
of
Obtains an instance ofDuration
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);
- Parameters:
amount
- the amount of the duration, positive or negativeunit
- the unit that the duration is measured in, not null- Returns:
- a
Duration
, never null - Throws:
ArithmeticException
- if the input amount exceeds the capacity ofDuration
which can only occur for units MINUTES, HOURS and DAYS
-
between
Obtains an instance ofDuration
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 callabs()
on the result of this factory.- Parameters:
startInclusive
- the start instant, inclusive, not nullendExclusive
- the end instant, exclusive, not null- Returns:
- a
Duration
, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
parse
Obtains an instance ofDuration
by parsing a string.This will parse the string produced by
toString()
which is the ISO-8601 formatPTnS
wheren
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
, never null - Throws:
CalendricalParseException
- if the text cannot be parsed to aDuration
-
create
Obtains an instance ofDuration
using seconds and nanoseconds.- Parameters:
seconds
- the length of the duration in seconds, positive or negativenanoAdjustment
- the nanosecond adjustment within the second, from 0 to 999,999,999
-
readResolve
Resolves singletons.- Returns:
- the resolved instance, never null
-
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
-
isPositiveOrZero
public boolean isPositiveOrZero()Checks if this duration is positive or 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 or equal to zero.- Returns:
- true if this duration has a total length greater than or equal 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
-
isNegativeOrZero
public boolean isNegativeOrZero()Checks if this duration is negative or 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 or equal to zero.- Returns:
- true if this duration has a total length less than or equal to 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
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.- Returns:
- the whole seconds part of the length of the duration, positive or negative
-
getNanoOfSecond
public int getNanoOfSecond()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
-
get
Gets the duration in terms of the specified 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
orLong.MIN_VALUE
.- Returns:
- the duration in the specified unit, saturated at
Long.MAX_VALUE
andLong.MIN_VALUE
, positive or negative
-
plus
Returns a copy of this duration with the specifiedDuration
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, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
plus
Returns a copy of this duration with the specified duration added.The duration to be added is measured in terms of the specified unit.
This instance is immutable and unaffected by this method call.
- Parameters:
amount
- the duration to add, positive or negativeunit
- the unit that the duration is measured in, not null- Returns:
- a
Duration
based on this duration with the specified duration added, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
plusSeconds
Returns a copy of this duration with the specified number of 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, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
plusMillis
Returns a copy of this duration with the specified number of 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, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
plusNanos
Returns a copy of this duration with the specified number of 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, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
minus
Returns a copy of this duration with the specifiedDuration
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, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
minus
Returns a copy of this duration with the specified duration subtracted.The duration to be subtracted is measured in terms of the specified unit.
This instance is immutable and unaffected by this method call.
- Parameters:
amount
- the duration to subtract, positive or negativeunit
- the unit that the duration is measured in, not null- Returns:
- a
Duration
based on this duration with the specified duration subtracted, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
minusSeconds
Returns a copy of this duration with the specified number of 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, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
minusMillis
Returns a copy of this duration with the specified number of 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, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
minusNanos
Returns a copy of this duration with the specified number of 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, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
multipliedBy
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, never null - Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
dividedBy
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, never null - Throws:
ArithmeticException
- if the divisor is zeroArithmeticException
- if the calculation exceeds the capacity ofDuration
-
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 asPT-1.3S
.This instance is immutable and unaffected by this method call.
- Returns:
- a
Duration
based on this period with the amount negated, never null - Throws:
ArithmeticException
- if the seconds part of the length isLong.MIN_VALUE
-
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 asPT1.3S
.This instance is immutable and unaffected by this method call.
- Returns:
- a
Duration
based on this period with an absolute length, never null - Throws:
ArithmeticException
- if the seconds part of the length isLong.MIN_VALUE
-
toSeconds
Converts this duration to the total length in seconds and fractional nanoseconds expressed as aBigDecimal
.- Returns:
- the total length of the duration in seconds, with a scale of 9, never null
-
toNanos
Converts this duration to the total length in nanoseconds expressed as aBigInteger
.- Returns:
- the total length of the duration in nanoseconds, never null
-
toNanosLong
public long toNanosLong()Converts this duration to the total length in nanoseconds expressed as along
.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 the length exceeds the capacity of along
-
toMillisLong
public long toMillisLong()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 the length exceeds the capacity of along
-
compareTo
Compares this duration to the specifiedDuration
.The comparison is based on the total length of the durations.
- Specified by:
compareTo
in interfaceComparable<Duration>
- Parameters:
otherDuration
- the other duration to compare to, not null- Returns:
- the comparator value, negative if less, positive if greater
-
isGreaterThan
Checks if this duration is greater than the specifiedDuration
.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
Checks if this duration is less than the specifiedDuration
.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
Checks if this duration is equal to the specifiedDuration
.The comparison is based on the total length of the durations.
-
hashCode
public int hashCode()A hash code for this duration. -
toString
A string representation of this duration using ISO-8601 seconds based representation, such asPT12.345S
.The format of the returned string will be
PTnS
where n is the seconds and fractional seconds of the duration.
-