Home Reference Source
public class | source

Duration

Extends:

TemporalAmount → Duration

A time-based amount of time, such as '34.5 seconds'.

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 ChronoUnit#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 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.

Static properties of Class Duration

Duration.ZERO

Constant for a duration of zero.

Static Method Summary

Static Public Methods
public static

between(startInclusive: Temporal, endExclusive: Temporal): Duration

Obtains an instance of Duration representing the duration between two instants.

public static

Obtains an instance of Duration from an amount.

public static

of(amount: Number, unit: TemporalUnit): Duration

Obtains an instance of Duration from a duration in the specified unit.

public static

ofDays(days: Number): Duration

Obtains an instance of Duration from a number of standard 24 hour days.

public static

ofHours(hours: Number): Duration

Obtains an instance of Duration from a number of standard hours.

public static

ofMillis(millis: Number): Duration

Obtains an instance of Duration from a number of milliseconds.

public static

ofMinutes(minutes: Number): Duration

Obtains an instance of Duration from a number of standard minutes.

public static

ofNanos(nanos: Number): Duration

Obtains an instance of Duration from a number of nanoseconds.

public static

ofSeconds(seconds: Number, nanoAdjustment: Number): Duration

Obtains an instance of Duration from a number of seconds and an adjustment in nanoseconds.

public static

parse(text: String): Duration

Obtains a Duration from a text string such as PnDTnHnMn.nS.

Method Summary

Public Methods
public

Returns a copy of this duration with a positive length.

public

addTo(temporal: Temporal): Temporal

Adds this duration to the specified temporal object.

public

compareTo(otherDuration: Duration): number

Compares this duration to the specified Duration.

public

dividedBy(divisor: Number): Duration

Returns a copy of this duration divided by the specified value.

public

equals(otherDuration: *): boolean

Checks if this duration is equal to the specified Duration.

public

get(unit: TemporalUnit): number

Gets the value of the requested unit.

public

isNegative(): boolean

Checks if this duration is negative, excluding zero.

public

isZero(): boolean

Checks if this duration is zero length.

public

minus(durationOrNumber: Duration | number, unit: TemporalUnit): Duration

function overloading for Duration.minus

public

minusAmountUnit(amountToSubtract: Number, unit: TemporalUnit): Duration

Returns a copy of this duration with the specified duration subtracted.

public

minusDays(daysToSubtract: Number): Duration

Returns a copy of this duration with the specified duration in 24 hour days subtracted.

public

Returns a copy of this duration with the specified duration subtracted.

public

minusHours(hoursToSubtract: Number): Duration

Returns a copy of this duration with the specified duration in hours subtracted.

public

minusMillis(millisToSubtract: Number): Duration

Returns a copy of this duration with the specified duration in milliseconds subtracted.

public

minusMinutes(minutesToSubtract: Number): Duration

Returns a copy of this duration with the specified duration in minutes subtracted.

public

minusNanos(nanosToSubtract: Number): Duration

Returns a copy of this duration with the specified duration in nanoseconds subtracted.

public

minusSeconds(secondsToSubtract: Number): Duration

Returns a copy of this duration with the specified duration in seconds subtracted.

public

multipliedBy(multiplicand: Number): Duration

Returns a copy of this duration multiplied by the scalar.

public

nano(): number

Gets the number of nanoseconds within the second in this duration.

public

Returns a copy of this duration with the length negated.

public

plus(durationOrNumber: Duration | number, unitOrNumber: TemporalUnit | number): Duration

function overloading for Duration.plus

public

plusAmountUnit(amountToAdd: Number, unit: TemporalUnit): Duration

Returns a copy of this duration with the specified duration added.

public

plusDays(daysToAdd: Number): Duration

Returns a copy of this duration with the specified duration in 24 hour days added.

public

Returns a copy of this duration with the specified duration added.

public

plusHours(hoursToAdd: Number): Duration

Returns a copy of this duration with the specified duration in hours added.

public

plusMillis(millisToAdd: Number): Duration

Returns a copy of this duration with the specified duration in milliseconds added.

public

plusMinutes(minutesToAdd: Number): Duration

Returns a copy of this duration with the specified duration in minutes added.

public

plusNanos(nanosToAdd: Number): Duration

Returns a copy of this duration with the specified duration in nanoseconds added.

public

plusSeconds(secondsToAdd: Number): Duration

Returns a copy of this duration with the specified duration in seconds added.

public

plusSecondsNanos(secondsToAdd: Number, nanosToAdd: Number): Duration

Returns a copy of this duration with the specified duration added.

public

seconds(): number

Gets the number of seconds in this duration.

public

Subtracts this duration from the specified temporal object.

public

toDays(): number

Gets the number of days in this duration.

public

toHours(): number

Gets the number of hours in this duration.

public

toJSON(): string

public

toMillis(): number

Converts this duration to the total length in milliseconds.

public

toMinutes(): number

Gets the number of minutes in this duration.

public

toNanos(): number

Converts this duration to the total length in nanoseconds expressed as a long.

public

toString(): string

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

public

units(): undefined[]

public

withNanos(nanoOfSecond: Number): Duration

Returns a copy of this duration with the specified nano-of-second.

public

withSeconds(seconds: Number): Duration

Returns a copy of this duration with the specified amount of seconds.

Inherited Summary

From class TemporalAmount
public

addTo(temporal: Temporal): Temporal

Adds to the specified temporal object.

public

get(unit: TemporalUnit): number

Returns the value of the requested unit.

public

Subtracts this object from the specified temporal object.

public

Returns the list of units uniquely defining the value of this TemporalAmount.

Static Public Methods

public static between(startInclusive: Temporal, endExclusive: Temporal): Duration source

Obtains an instance of Duration representing the duration between two instants.

Obtains a Duration representing the duration between two instants. This calculates the duration between two temporal objects of the same type. The difference in seconds is calculated using Temporal#until. The difference in nanoseconds is calculated using by querying the ChronoField#NANO_OF_SECOND field.

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.

Params:

NameTypeAttributeDescription
startInclusive Temporal

the start instant, inclusive, not null

endExclusive Temporal

the end instant, exclusive, not null

Return:

Duration (nullable: false)

Throw:

*

DateTimeException if the seconds between the temporals cannot be obtained

*

ArithmeticException if the calculation exceeds the capacity of Duration

public static from(amount: TemporalAmount): Duration source

Obtains an instance of Duration from an amount.

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.

Params:

NameTypeAttributeDescription
amount TemporalAmount

the temporal amount to convert, not null

Return:

Duration

the resulting duration, not null

Throw:

*

DateTimeException if the amount cannot be converted

*

ArithmeticException if a numeric overflow occurs

public static of(amount: Number, unit: TemporalUnit): Duration source

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 (see TemporalUnit#isDurationEstimated) or be ChronoUnit#DAYS which is treated as 24 hours. Other units throw an exception.

Params:

NameTypeAttributeDescription
amount Number

the amount of the duration, measured in terms of the unit, positive or negative

unit TemporalUnit

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

Return:

Duration (nullable: false)

Throw:

*

DateTimeException if the period unit has an estimated duration

*

ArithmeticException if a numeric overflow occurs

public static ofDays(days: Number): Duration source

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.

Params:

NameTypeAttributeDescription
days Number

the number of days, positive or negative

Return:

Duration (nullable: false)

Throw:

*

ArithmeticException if the input days exceeds the capacity of Duration

public static ofHours(hours: Number): Duration source

Obtains an instance of Duration from a number of standard 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.

Params:

NameTypeAttributeDescription
hours Number

the number of hours, positive or negative

Return:

Duration (nullable: false)

Throw:

*

ArithmeticException if the input hours exceeds the capacity of Duration

public static ofMillis(millis: Number): Duration source

Obtains an instance of Duration from a number of milliseconds.

The seconds and nanoseconds are extracted from the specified milliseconds.

Params:

NameTypeAttributeDescription
millis Number

the number of milliseconds, positive or negative

Return:

Duration (nullable: false)

public static ofMinutes(minutes: Number): Duration source

Obtains an instance of Duration from a number of standard 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.

Params:

NameTypeAttributeDescription
minutes Number

the number of minutes, positive or negative

Return:

Duration (nullable: false)

Throw:

*

ArithmeticException if the input minutes exceeds the capacity of Duration

public static ofNanos(nanos: Number): Duration source

Obtains an instance of Duration from a number of nanoseconds.

The seconds and nanoseconds are extracted from the specified nanoseconds.

Params:

NameTypeAttributeDescription
nanos Number

the number of nanoseconds, positive or negative

Return:

Duration (nullable: false)

public static ofSeconds(seconds: Number, nanoAdjustment: Number): Duration source

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);

Params:

NameTypeAttributeDescription
seconds Number

the number of seconds, positive or negative

nanoAdjustment Number

the nanosecond adjustment to the number of seconds, positive or negative

Return:

Duration (nullable: false)

Throw:

*

ArithmeticException if the adjustment causes the seconds to exceed the capacity of Duration

public static parse(text: String): Duration source

Obtains a Duration from a text string such as PnDTnHnMn.nS.

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 a long. The number of seconds must parse to a 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.

Examples:

   "PT20.345S" -> parses as "20.345 seconds"
   "PT15M"     -> parses as "15 minutes" (where a minute is 60 seconds)
   "PT10H"     -> parses as "10 hours" (where an hour is 3600 seconds)
   "P2D"       -> parses as "2 days" (where a day is 24 hours or 86400 seconds)
   "P2DT3H4M"  -> parses as "2 days, 3 hours and 4 minutes"
   "P-6H3M"    -> parses as "-6 hours and +3 minutes"
   "-P6H3M"    -> parses as "-6 hours and -3 minutes"
   "-P-6H+3M"  -> parses as "+6 hours and -3 minutes"

Params:

NameTypeAttributeDescription
text String

the text to parse, not null

Return:

Duration

the parsed duration, not null

Throw:

*

DateTimeParseException if the text cannot be parsed to a duration

Public Methods

public abs(): Duration source

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.

Return:

Duration

based on this duration with an absolute length, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public addTo(temporal: Temporal): Temporal source

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.

  // these two lines are equivalent, but the second approach is recommended
  dateTime = thisDuration.addTo(dateTime);
  dateTime = dateTime.plus(thisDuration);

The calculation will add the seconds, then nanos. Only non-zero amounts will be added.

This instance is immutable and unaffected by this method call.

Override:

TemporalAmount#addTo

Params:

NameTypeAttributeDescription
temporal Temporal

the temporal object to adjust, not null

Return:

Temporal

an object of the same type with the adjustment made, not null

Throw:

*

DateTimeException if unable to add

*

ArithmeticException if numeric overflow occurs

public compareTo(otherDuration: Duration): number source

Compares this duration to the specified Duration.

The comparison is based on the total length of the durations.

Params:

NameTypeAttributeDescription
otherDuration Duration

the other duration to compare to, not null

Return:

number

the comparator value, negative if less, positive if greater

public dividedBy(divisor: Number): Duration source

Returns a copy of this duration divided by the specified value.

In opposite to the threeten implementation the division is realized by floating point not by fixed point arithmetic. Expect floating point rounding errors for Duration.dividedBy.

Params:

NameTypeAttributeDescription
divisor Number

the value to divide the duration by, positive or negative, not zero

Return:

Duration

based on this duration divided by the specified divisor, not null

Throw:

*

ArithmeticException if the divisor is zero or if numeric overflow occurs

public equals(otherDuration: *): boolean source

Checks if this duration is equal to the specified Duration.

The comparison is based on the total length of the durations.

Params:

NameTypeAttributeDescription
otherDuration *

the other duration, null returns false

Return:

boolean

true if the other duration is equal to this one

public get(unit: TemporalUnit): number source

Gets the value of the requested unit.

This returns a value for each of the two supported units, ChronoUnit#SECONDS and ChronoUnit#NANOS. All other units throw an exception.

Override:

TemporalAmount#get

Params:

NameTypeAttributeDescription
unit TemporalUnit

the TemporalUnit for which to return the value

Return:

number

the const value of the unit

Throw:

*

DateTimeException if the unit is not supported

*

UnsupportedTemporalTypeException if the unit is not supported

public isNegative(): boolean source

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.

Return:

boolean

true if this duration has a total length less than zero

public isZero(): boolean source

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.

Return:

boolean

true if this duration has a total length equal to zero

public minus(durationOrNumber: Duration | number, unit: TemporalUnit): Duration source

function overloading for Duration.minus

if called with 1 arguments and first argument is an instance of Duration, then Duration.minusDuration is executed.

Otherwise Duration.minusAmountUnit is executed.

Params:

NameTypeAttributeDescription
durationOrNumber Duration | number
  • nullable: false
unit TemporalUnit
  • nullable: true

Return:

Duration

public minusAmountUnit(amountToSubtract: Number, unit: TemporalUnit): Duration source

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 (see TemporalUnit#isDurationEstimated) 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.

Params:

NameTypeAttributeDescription
amountToSubtract Number

the amount to subtract, measured in terms of the unit, positive or negative

unit TemporalUnit

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

Return:

Duration

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

Throw:

*

ArithmeticException if numeric overflow occurs

public minusDays(daysToSubtract: Number): Duration source

Returns a copy of this duration with the specified duration in 24 hour days subtracted.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
daysToSubtract Number

the days to subtract, positive or negative

Return:

Duration

based on this duration with the specified days subtracted, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public minusDuration(duration: Duration): Duration source

Returns a copy of this duration with the specified duration subtracted.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
duration Duration

the duration to subtract, positive or negative, not null

Return:

Duration

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

Throw:

*

ArithmeticException if numeric overflow occurs

public minusHours(hoursToSubtract: Number): Duration source

Returns a copy of this duration with the specified duration in hours subtracted.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
hoursToSubtract Number

the hours to subtract, positive or negative

Return:

Duration

based on this duration with the specified hours subtracted, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public minusMillis(millisToSubtract: Number): Duration source

Returns a copy of this duration with the specified duration in milliseconds subtracted.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
millisToSubtract Number

the milliseconds to subtract, positive or negative

Return:

Duration

based on this duration with the specified milliseconds subtracted, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public minusMinutes(minutesToSubtract: Number): Duration source

Returns a copy of this duration with the specified duration in minutes subtracted.

The number of hours is multiplied by 60 to obtain the number of seconds to subtract.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
minutesToSubtract Number

the minutes to subtract, positive or negative

Return:

Duration

based on this duration with the specified minutes subtracted, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public minusNanos(nanosToSubtract: Number): Duration source

Returns a copy of this duration with the specified duration in nanoseconds subtracted.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
nanosToSubtract Number

the nanoseconds to subtract, positive or negative

Return:

Duration

based on this duration with the specified nanoseconds subtracted, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public minusSeconds(secondsToSubtract: Number): Duration source

Returns a copy of this duration with the specified duration in seconds subtracted.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
secondsToSubtract Number

the seconds to subtract, positive or negative

Return:

Duration

based on this duration with the specified seconds subtracted, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public multipliedBy(multiplicand: Number): Duration source

Returns a copy of this duration multiplied by the scalar.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
multiplicand Number

the value to multiply the duration by, positive or negative

Return:

Duration

based on this duration multiplied by the specified scalar, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public nano(): number source

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.

Return:

number

the nanoseconds within the second part of the length of the duration, from 0 to 999,999,999

public negated(): Duration source

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.

Return:

Duration

based on this duration with the amount negated, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public plus(durationOrNumber: Duration | number, unitOrNumber: TemporalUnit | number): Duration source

function overloading for Duration.plus

if called with 1 arguments, then Duration.plusDuration is executed.

if called with 2 arguments and second argument is an instance of TemporalUnit, then Duration.plusAmountUnit is executed.

Otherwise Duration.plusSecondsNanos is executed.

Params:

NameTypeAttributeDescription
durationOrNumber Duration | number
  • nullable: false
unitOrNumber TemporalUnit | number
  • nullable: false

Return:

Duration

public plusAmountUnit(amountToAdd: Number, unit: TemporalUnit): Duration source

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 (see TemporalUnit#isDurationEstimated) 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.

Params:

NameTypeAttributeDescription
amountToAdd Number

the amount to add, measured in terms of the unit, positive or negative

unit TemporalUnit

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

Return:

Duration

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

Throw:

*

UnsupportedTemporalTypeException if the unit is not supported

*

ArithmeticException if numeric overflow occurs

public plusDays(daysToAdd: Number): Duration source

Returns a copy of this duration with the specified duration in 24 hour days added.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
daysToAdd Number

the days to add, positive or negative

Return:

Duration

based on this duration with the specified days added, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public plusDuration(duration: Duration): Duration source

Returns a copy of this duration with the specified duration added.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
duration Duration

the duration to add, positive or negative, not null

Return:

Duration

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

Throw:

*

ArithmeticException if numeric overflow occurs

public plusHours(hoursToAdd: Number): Duration source

Returns a copy of this duration with the specified duration in hours added.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
hoursToAdd Number

the hours to add, positive or negative

Return:

Duration

based on this duration with the specified hours added, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public plusMillis(millisToAdd: Number): Duration source

Returns a copy of this duration with the specified duration in milliseconds added.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
millisToAdd Number

the milliseconds to add, positive or negative

Return:

Duration

based on this duration with the specified milliseconds added, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public plusMinutes(minutesToAdd: Number): Duration source

Returns a copy of this duration with the specified duration in minutes added.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
minutesToAdd Number

the minutes to add, positive or negative

Return:

Duration

based on this duration with the specified minutes added, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public plusNanos(nanosToAdd: Number): Duration source

Returns a copy of this duration with the specified duration in nanoseconds added.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
nanosToAdd Number

the nanoseconds to add, positive or negative

Return:

Duration

based on this duration with the specified nanoseconds added, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public plusSeconds(secondsToAdd: Number): Duration source

Returns a copy of this duration with the specified duration in seconds added.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
secondsToAdd Number

the seconds to add, positive or negative

Return:

Duration

based on this duration with the specified seconds added, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public plusSecondsNanos(secondsToAdd: Number, nanosToAdd: Number): Duration source

Returns a copy of this duration with the specified duration added.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
secondsToAdd Number

the seconds to add, positive or negative

nanosToAdd Number

the nanos to add, positive or negative

Return:

Duration

based on this duration with the specified seconds added, not null

Throw:

*

ArithmeticException if numeric overflow occurs

public seconds(): number source

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.

Return:

number

the whole seconds part of the length of the duration, positive or negative

public subtractFrom(temporal: Temporal): Temporal source

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.

  // these two lines are equivalent, but the second approach is recommended
  dateTime = thisDuration.subtractFrom(dateTime);
  dateTime = dateTime.minus(thisDuration);

The calculation will subtract the seconds, then nanos. Only non-zero amounts will be added.

This instance is immutable and unaffected by this method call.

Override:

TemporalAmount#subtractFrom

Params:

NameTypeAttributeDescription
temporal Temporal

the temporal object to adjust, not null

Return:

Temporal

an object of the same type with the adjustment made, not null

Throw:

*

DateTimeException if unable to subtract

*

ArithmeticException if numeric overflow occurs

public toDays(): number source

Gets the number of days in this duration.

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.

Return:

number

the number of days in the duration, may be negative

public toHours(): number source

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.

Return:

number

the number of hours in the duration, may be negative

public toJSON(): string source

Return:

string

same as Duration.toString

public toMillis(): number source

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.

Return:

number

the total length of the duration in milliseconds

Throw:

*

ArithmeticException if numeric overflow occurs

public toMinutes(): number source

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.

Return:

number

the number of minutes in the duration, may be negative

public toNanos(): number source

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.

Return:

number

the total length of the duration in nanoseconds

Throw:

*

ArithmeticException if numeric overflow occurs

public toString(): string source

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 in the seconds section. If a section has a zero value, it is omitted. The hours, minutes and seconds will all have the same sign.

Examples:

   "20.345 seconds"                 -> "PT20.345S
   "15 minutes" (15  60 seconds)   -> "PT15M"
   "10 hours" (10  3600 seconds)   -> "PT10H"
   "2 days" (2 * 86400 seconds)     -> "PT48H"
Note that multiples of 24 hours are not output as days to avoid confusion with Period.

Return:

string

an ISO-8601 representation of this duration, not null

public units(): undefined[] source

Returns the list of units uniquely defining the value of this TemporalAmount. The list of TemporalUnits is defined by the implementation class. The list is a snapshot of the units at the time getUnits is called and is not mutable. The units are ordered from longest duration to the shortest duration of the unit.

Override:

TemporalAmount#units

Return:

undefined[]

public withNanos(nanoOfSecond: Number): Duration source

Returns a copy of this duration with the specified nano-of-second.

This returns a duration with the specified nano-of-second, retaining the seconds part of this duration.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
nanoOfSecond Number

the nano-of-second to represent, from 0 to 999,999,999

Return:

Duration

based on this period with the requested nano-of-second, not null

Throw:

*

DateTimeException if the nano-of-second is invalid

public withSeconds(seconds: Number): Duration source

Returns a copy of this duration with the specified amount of seconds.

This returns a duration with the specified seconds, retaining the nano-of-second part of this duration.

This instance is immutable and unaffected by this method call.

Params:

NameTypeAttributeDescription
seconds Number

the seconds to represent, may be negative

Return:

Duration

based on this period with the requested seconds, not null