Duration
Extends:
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 {@link ChronoUnit#DAYS 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 {@code 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 {@code long}. To achieve this, the class stores a {@code long} representing seconds and an {@code 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 |
Obtains an instance of Duration representing the duration between two instants. |
|
public static |
to handle function overriding this function accepts any number of arguments, checks their type and delegates to the appropriate function |
|
public static |
createNegateDaysHoursMinutesSecondsNanos(negate: *, daysAsSecs: *, hoursAsSecs: *, minsAsSecs: *, secs: *, nanos: *): * |
|
public static |
createSeconds(seconds: Number): Duration Creates an instance of Duration from a number of seconds. |
|
public static |
createSecondsNanos(seconds: Number, nanoAdjustment: Number): * Obtains an instance of Duration using seconds and nanoseconds. |
|
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 |
Obtains an instance of Duration from a number of standard 24 hour days. |
|
public static |
Obtains an instance of Duration from a number of standard hours. |
|
public static |
Obtains an instance of Duration from a number of milliseconds. |
|
public static |
Obtains an instance of Duration from a number of standard minutes. |
|
public static |
Obtains an instance of Duration from a number of nanoseconds. |
|
public static |
Obtains an instance of Duration from a number of seconds and an adjustment in nanoseconds. |
|
public static |
Obtains a Duration from a text string such as {@code PnDTnHnMn.nS}. |
Method Summary
Public Methods | ||
public |
Returns a copy of this duration with a positive length. |
|
public |
Adds this duration to the specified temporal object. |
|
public |
Compares this duration to the specified Duration. |
|
public |
Returns a copy of this duration divided by the specified value. |
|
public |
Checks if this duration is equal to the specified Duration. |
|
public |
get(unit: TemporalUnit): number Gets the value of the requested unit. |
|
public |
Checks if this duration is negative, excluding zero. |
|
public |
Checks if this duration is zero length. |
|
public |
to handle function overriding this function accepts two arguments, checks their type and delegates to the appropriate function |
|
public |
minusAmountUnit(amountToSubtract: Number, unit: TemporalUnit): Duration Returns a copy of this duration with the specified duration subtracted. |
|
public |
Returns a copy of this duration with the specified duration in 24 hour days subtracted. |
|
public |
minusDuration(duration: Duration): Duration 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 |
Gets the number of nanoseconds within the second in this duration. |
|
public |
Returns a copy of this duration with the length negated. |
|
public |
to handle function overriding this function accepts two arguments, checks their type and delegates to the appropriate function |
|
public |
plusAmountUnit(amountToAdd: Number, unit: TemporalUnit): Duration Returns a copy of this duration with the specified duration added. |
|
public |
Returns a copy of this duration with the specified duration in 24 hour days added. |
|
public |
plusDuration(duration: Duration): Duration Returns a copy of this duration with the specified duration added. |
|
public |
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 |
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 |
Gets the number of seconds in this duration. |
|
public |
subtractFrom(temporal: Temporal): Temporal Subtracts this duration from the specified temporal object. |
|
public |
Gets the number of days in this duration. |
|
public |
Gets the number of hours in this duration. |
|
public |
Converts this duration to the total length in milliseconds. |
|
public |
Gets the number of minutes in this duration. |
|
public |
Converts this duration to the total length in nanoseconds expressed as a {@code long}. |
|
public |
Converts this duration to the total length in seconds and fractional nanoseconds expressed as a {@code BigDecimal}. |
|
public |
A string representation of this duration using ISO-8601 seconds based representation, such as {@code PT8H6M12.345S}. |
|
public |
units(): * |
|
public |
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 |
Adds to the specified temporal object. |
|
public |
get(unit: TemporalUnit): number Returns the value of the requested unit. |
|
public |
getUnits(): TemporalUnit[] Returns the list of units uniquely defining the value of this TemporalAmount. |
|
public |
subtractFrom(temporal: Temporal): Temporal Subtracts this object from the specified temporal object. |
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 {@link Temporal#until(Temporal, TemporalUnit)}. The difference in nanoseconds is calculated using by querying the {@link ChronoField#NANO_OF_SECOND 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.
Throw:
* |
DateTimeException if the seconds between the temporals cannot be obtained |
* |
ArithmeticException if the calculation exceeds the capacity of Duration |
public static create(): Duration source
to handle function overriding this function accepts any number of arguments, checks their type and delegates to the appropriate function
public static createNegateDaysHoursMinutesSecondsNanos(negate: *, daysAsSecs: *, hoursAsSecs: *, minsAsSecs: *, secs: *, nanos: *): * source
Params:
Name | Type | Attribute | Description |
negate | * | ||
daysAsSecs | * | ||
hoursAsSecs | * | ||
minsAsSecs | * | ||
secs | * | ||
nanos | * |
Return:
* |
public static createSeconds(seconds: Number): Duration source
Creates an instance of Duration from a number of seconds.
Params:
Name | Type | Attribute | Description |
seconds | Number | the number of seconds, up to scale 9, positive or negative |
Throw:
* |
ArithmeticException if numeric overflow occurs |
public static createSecondsNanos(seconds: Number, nanoAdjustment: Number): * source
Obtains an instance of Duration using seconds and nanoseconds.
Return:
* |
public static from(amount: Number): 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:
Name | Type | Attribute | Description |
amount | Number | the temporal amount to convert, 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 {@link TemporalUnit#isDurationEstimated() exact duration} or be ChronoUnit#DAYS which is treated as 24 hours. Other units throw an exception.
Params:
Name | Type | Attribute | Description |
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 |
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:
Name | Type | Attribute | Description |
days | Number | the number of days, positive or negative |
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:
Name | Type | Attribute | Description |
hours | Number | the number of hours, positive or negative |
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:
Name | Type | Attribute | Description |
millis | Number | the number of milliseconds, positive or negative |
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:
Name | Type | Attribute | Description |
minutes | Number | the number of minutes, positive or negative |
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:
Name | Type | Attribute | Description |
nanos | Number | the number of nanoseconds, positive or negative |
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);
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 {@code PnDTnHnMn.nS}.
This will parse a textual representation of a duration, including the string produced by {@code toString()}. The formats accepted are based on the ISO-8601 duration format {@code 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 {@code long}. The number of seconds must parse to a {@code 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:
Name | Type | Attribute | Description |
text | String | the text to parse, 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, {@code PT-1.3S} will be returned as {@code PT1.3S}.
This instance is immutable and unaffected by this method call.
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 {@link Temporal#plus(TemporalAmount)}.
// 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#addToParams:
Name | Type | Attribute | Description |
temporal | Temporal | the temporal object to adjust, 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:
Name | Type | Attribute | Description |
otherDuration | Duration | the other duration to compare to, not null |
public dividedBy(divisor: Number): Duration source
Returns a copy of this duration divided by the specified value.
This instance is immutable and unaffected by this method call.
Params:
Name | Type | Attribute | Description |
divisor | Number | the value to divide the duration by, positive or negative, not zero |
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:
Name | Type | Attribute | Description |
otherDuration | * | the other duration, null returns false |
public get(unit: TemporalUnit): number source
Gets the value of the requested unit.
This returns a value for each of the two supported units, {@link ChronoUnit#SECONDS SECONDS} and {@link ChronoUnit#NANOS NANOS}. All other units throw an exception.
Override:
TemporalAmount#getParams:
Name | Type | Attribute | Description |
unit | TemporalUnit | the {@code TemporalUnit} for which to return the value |
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.
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.
public minus(a: Duration | number, b: ChronoUnit | number): Duration source
to handle function overriding this function accepts two arguments, checks their type and delegates to the appropriate function
Params:
Name | Type | Attribute | Description |
a | Duration | number |
|
|
b | ChronoUnit | number |
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 {@link TemporalUnit#isDurationEstimated() 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.
Params:
Name | Type | Attribute | Description |
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 |
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:
Name | Type | Attribute | Description |
daysToSubtract | Number | the days to subtract, positive or negative |
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:
Name | Type | Attribute | Description |
duration | Duration | the duration to subtract, positive or negative, 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:
Name | Type | Attribute | Description |
hoursToSubtract | Number | the hours to subtract, positive or negative |
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:
Name | Type | Attribute | Description |
millisToSubtract | Number | the milliseconds to subtract, positive or negative |
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:
Name | Type | Attribute | Description |
minutesToSubtract | Number | the minutes to subtract, positive or negative |
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:
Name | Type | Attribute | Description |
nanosToSubtract | Number | the nanoseconds to subtract, positive or negative |
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:
Name | Type | Attribute | Description |
secondsToSubtract | Number | the seconds to subtract, positive or negative |
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:
Name | Type | Attribute | Description |
multiplicand | Number | the value to multiply the duration by, positive or negative |
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 {@link #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, {@code PT1.3S} will be returned as {@code PT-1.3S}.
This instance is immutable and unaffected by this method call.
Throw:
* |
ArithmeticException if numeric overflow occurs |
public plus(a: Duration | number, b: ChronoUnit | number): Duration source
to handle function overriding this function accepts two arguments, checks their type and delegates to the appropriate function
Params:
Name | Type | Attribute | Description |
a | Duration | number |
|
|
b | ChronoUnit | number |
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 {@link TemporalUnit#isDurationEstimated() 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.
Params:
Name | Type | Attribute | Description |
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 |
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:
Name | Type | Attribute | Description |
daysToAdd | Number | the days to add, positive or negative |
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:
Name | Type | Attribute | Description |
duration | Duration | the duration to add, positive or negative, 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:
Name | Type | Attribute | Description |
hoursToAdd | Number | the hours to add, positive or negative |
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:
Name | Type | Attribute | Description |
millisToAdd | Number | the milliseconds to add, positive or negative |
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:
Name | Type | Attribute | Description |
minutesToAdd | Number | the minutes to add, positive or negative |
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:
Name | Type | Attribute | Description |
nanosToAdd | Number | the nanoseconds to add, positive or negative |
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:
Name | Type | Attribute | Description |
secondsToAdd | Number | the seconds to add, positive or negative |
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.
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 {@link #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.
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 {@link Temporal#minus(TemporalAmount)}.
// 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#subtractFromParams:
Name | Type | Attribute | Description |
temporal | Temporal | the temporal object to adjust, 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.
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.
public toMillis(): number source
Converts this duration to the total length in milliseconds.
If this duration is too large to fit in a {@code 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.
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.
public toNanos(): number source
Converts this duration to the total length in nanoseconds expressed as a {@code long}.
If this duration is too large to fit in a {@code long} nanoseconds, then an exception is thrown.
Throw:
* |
ArithmeticException if numeric overflow occurs |
public toSeconds(): number source
Converts this duration to the total length in seconds and fractional nanoseconds expressed as a {@code BigDecimal}.
public toString(): string source
A string representation of this duration using ISO-8601 seconds based representation, such as {@code PT8H6M12.345S}.
The format of the returned string will be {@code PTnHnMnS}, where n is the relevant hours, minutes or seconds part of the duration. Any fractional seconds are placed after a decimal povar 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.
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 {@code Period}.
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:
Name | Type | Attribute | Description |
nanoOfSecond | Number | the nano-of-second to represent, from 0 to 999,999,999 |
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:
Name | Type | Attribute | Description |
seconds | Number | the seconds to represent, may be negative |