This class models a quantity or amount of time in terms of seconds and nanoseconds.
It can be accessed using other duration-based units, such as minutes and hours.
In addition, the DAYS unit can be used and is treated as
exactly equal to 24 hours, thus ignoring daylight savings effects.
See Period for the date-based equivalent to this class.

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 model is of a directed duration, meaning that the duration may be negative.

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.

This is a value-based
class; use of identity-sensitive operations (including reference equality
(==), identity hash code, or synchronization) on instances of
Duration may have unpredictable results and should be avoided.
The equals method should be used for comparisons.

ofSeconds

Obtains a Duration representing 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:

from

This obtains a duration based on the specified amount.
A TemporalAmount represents an amount of time, which may be
date-based or time-based, which this factory extracts to a duration.

The conversion loops around the set of units from the amount and uses
the duration of the unit to
calculate the total Duration.
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.
If any other units are found then an exception is thrown.

parse

This will parse a textual representation of a duration, including the
string produced by toString(). The formats accepted are based
on the ISO-8601 duration format PnDTnHnMn.nS with days
considered to be exactly 24 hours.

The string starts with an optional sign, denoted by the ASCII negative
or positive symbol. If negative, the whole period is negated.
The ASCII letter "P" is next in upper or lower case.
There are then four sections, each consisting of a number and a suffix.
The sections have suffixes in ASCII of "D", "H", "M" and "S" for
days, hours, minutes and seconds, accepted in upper or lower case.
The suffixes must occur in order. The ASCII letter "T" must occur before
the first occurrence, if any, of an hour, minute or second section.
At least one of the four sections must be present, and if "T" is present
there must be at least one section after the "T".
The number part of each section must consist of one or more ASCII digits.
The number may be prefixed by the ASCII negative or positive symbol.
The number of days, hours and minutes must parse to an long.
The number of seconds must parse to an long with optional fraction.
The decimal point may be either a dot or a comma.
The fractional part may have from zero to 9 digits.

The leading plus/minus sign, and negative values for other units are
not part of the ISO-8601 standard.

between

Obtains a Duration representing the duration between two temporal objects.

This calculates the duration between two temporal objects. If the objects
are of different types, then the duration is calculated based on the type
of the first object. For example, if the first argument is a LocalTime
then the second argument is converted to a LocalTime.

The specified temporal objects must support the SECONDS unit.
For full accuracy, either the NANOS unit or the
NANO_OF_SECOND field should be supported.

The result of this method can be a negative period if the end is before the start.
To guarantee to obtain a positive duration call abs() on the result.

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.

Returns:

true if this duration has a total length equal to 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

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 to add, measured in terms of the unit, positive or negative

unit - the unit that the amount is measured in, must have an exact duration, not null

Returns:

a Duration based on this duration with the specified duration added, not null

minus

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 to subtract, measured in terms of the unit, positive or negative

unit - the unit that the amount is measured in, must have an exact duration, not null

Returns:

a Duration based on this duration with the specified duration subtracted, not null

toDays

This returns the total number of days in the duration by dividing the
number of seconds by 86400.
This is based on the standard definition of a day as 24 hours.

This instance is immutable and unaffected by this method call.

Returns:

the number of days in the duration, may be negative

toHours

public long toHours()

Gets the number of hours in this duration.

This returns the total number of hours in the duration by dividing the
number of seconds by 3600.

This instance is immutable and unaffected by this method call.

Returns:

the number of hours in the duration, may be negative

toMinutes

public long toMinutes()

Gets the number of minutes in this duration.

This returns the total number of minutes in the duration by dividing the
number of seconds by 60.

This instance is immutable and unaffected by this method call.

Returns:

the number of minutes in the duration, may be negative

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.

toString

A string representation of this duration using ISO-8601 seconds
based representation, such as PT8H6M12.345S.

The format of the returned string will be PTnHnMnS, where n is
the relevant hours, minutes or seconds part of the duration.
Any fractional seconds are placed after a decimal point i the seconds section.
If a section has a zero value, it is omitted.
The hours, minutes and seconds will all have the same sign.