Duration

abs

fun abs(): Duration!

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.

addTo

fun addTo(temporal: Temporal!): Temporal!

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(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.

between

static fun between(
    startInclusive: Temporal!, 
    endExclusive: Temporal!
): Duration!

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.

compareTo

fun compareTo(other: Duration!): Int

Compares this duration to the specified Duration.

The comparison is based on the total length of the durations. It is "consistent with equals", as defined by Comparable.

dividedBy

fun dividedBy(divisor: Duration!): Long

Returns number of whole times a specified Duration occurs within this Duration.

This instance is immutable and unaffected by this method call.

dividedBy

fun dividedBy(divisor: Long): Duration!

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

This instance is immutable and unaffected by this method call.

equals

fun equals(other: Any?): Boolean

Checks if this duration is equal to the specified Duration.

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

from

static fun from(amount: TemporalAmount!): Duration!

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

get

fun get(unit: TemporalUnit!): Long

Gets the value of the requested unit.

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

getNano

fun getNano(): Int

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.

getSeconds

fun getSeconds(): Long

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.

getUnits

fun getUnits(): MutableList<TemporalUnit!>!

Gets the set of units supported by this duration.

The supported units are SECONDS, and NANOS. They are returned in the order seconds, nanos.

This set can be used in conjunction with get(java.time.temporal.TemporalUnit) to access the entire state of the duration.

hashCode

fun hashCode(): Int

A hash code for this duration.

isNegative

fun isNegative(): Boolean

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.

isZero

fun isZero(): Boolean

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.

minus

fun minus(duration: Duration!): Duration!

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

This instance is immutable and unaffected by this method call.

minus

fun minus(
    amountToSubtract: Long, 
    unit: TemporalUnit!
): Duration!

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.

minusDays

fun minusDays(daysToSubtract: Long): Duration!

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

The number of days is multiplied by 86400 to obtain the number of seconds to subtract. This is based on the standard definition of a day as 24 hours.

This instance is immutable and unaffected by this method call.

minusHours

fun minusHours(hoursToSubtract: Long): Duration!

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

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

This instance is immutable and unaffected by this method call.

minusMillis

fun minusMillis(millisToSubtract: Long): Duration!

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

This instance is immutable and unaffected by this method call.

minusMinutes

fun minusMinutes(minutesToSubtract: Long): Duration!

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.

minusNanos

fun minusNanos(nanosToSubtract: Long): Duration!

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

This instance is immutable and unaffected by this method call.

minusSeconds

fun minusSeconds(secondsToSubtract: Long): Duration!

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

This instance is immutable and unaffected by this method call.

multipliedBy

fun multipliedBy(multiplicand: Long): Duration!

Returns a copy of this duration multiplied by the scalar.

This instance is immutable and unaffected by this method call.

negated

fun negated(): Duration!

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.

of

static fun of(
    amount: Long, 
    unit: TemporalUnit!
): Duration!

Obtains a Duration representing an amount 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);
  

ofDays

static fun ofDays(days: Long): Duration!

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

ofHours

static fun ofHours(hours: Long): Duration!

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

ofMillis

static fun ofMillis(millis: Long): Duration!

Obtains a Duration representing a number of milliseconds.

The seconds and nanoseconds are extracted from the specified milliseconds.

ofMinutes

static fun ofMinutes(minutes: Long): Duration!

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

ofNanos

static fun ofNanos(nanos: Long): Duration!

Obtains a Duration representing a number of nanoseconds.

The seconds and nanoseconds are extracted from the specified nanoseconds.

ofSeconds

static fun ofSeconds(seconds: Long): Duration!

Obtains a Duration representing a number of seconds.

The nanosecond in second field is set to zero.

ofSeconds

static fun ofSeconds(
    seconds: Long, 
    nanoAdjustment: Long
): Duration!

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 exactly the same duration:

Duration.ofSeconds(3, 1);
   Duration.ofSeconds(4, -999_999_999);
   Duration.ofSeconds(2, 1000_000_001);
  

parse

static fun parse(text: CharSequence!): Duration!

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

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"
  

plus

fun plus(duration: Duration!): Duration!

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

This instance is immutable and unaffected by this method call.

plus

fun plus(
    amountToAdd: Long, 
    unit: TemporalUnit!
): Duration!

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

plusDays

fun plusDays(daysToAdd: Long): Duration!

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

The number of days is multiplied by 86400 to obtain the number of seconds to add. This is based on the standard definition of a day as 24 hours.

This instance is immutable and unaffected by this method call.

plusHours

fun plusHours(hoursToAdd: Long): Duration!

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

This instance is immutable and unaffected by this method call.

plusMillis

fun plusMillis(millisToAdd: Long): Duration!

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

This instance is immutable and unaffected by this method call.

plusMinutes

fun plusMinutes(minutesToAdd: Long): Duration!

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

This instance is immutable and unaffected by this method call.

plusNanos

fun plusNanos(nanosToAdd: Long): Duration!

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

This instance is immutable and unaffected by this method call.

plusSeconds

fun plusSeconds(secondsToAdd: Long): Duration!

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

This instance is immutable and unaffected by this method call.

subtractFrom

fun subtractFrom(temporal: Temporal!): Temporal!

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(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.

toDays

fun toDays(): Long

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.

toDaysPart

fun toDaysPart(): Long

Extracts the number of days in the 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.

toHours

fun toHours(): Long

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.

toHoursPart

fun toHoursPart(): Int

Extracts the number of hours part in the duration.

This returns the number of remaining hours when dividing toHours by hours in a day. This is based on the standard definition of a day as 24 hours.

This instance is immutable and unaffected by this method call.

toMillis

fun toMillis(): Long

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.

toMillisPart

fun toMillisPart(): Int

Extracts the number of milliseconds part of the duration.

This returns the milliseconds part by dividing the number of nanoseconds by 1,000,000. 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 getNano() and getSeconds().

This instance is immutable and unaffected by this method call.

toMinutes

fun toMinutes(): Long

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.

toMinutesPart

fun toMinutesPart(): Int

Extracts the number of minutes part in the duration.

This returns the number of remaining minutes when dividing toMinutes by minutes in an hour. This is based on the standard definition of an hour as 60 minutes.

This instance is immutable and unaffected by this method call.

toNanos

fun toNanos(): Long

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.

toNanosPart

fun toNanosPart(): Int

Get the nanoseconds part within seconds of the 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 getNano() and getSeconds().

This instance is immutable and unaffected by this method call.

toSeconds

fun toSeconds(): Long

Gets the number of seconds in this duration.

This returns the total number of whole seconds in the duration.

This instance is immutable and unaffected by this method call.

toSecondsPart

fun toSecondsPart(): Int

Extracts the number of seconds part in the duration.

This returns the remaining seconds when dividing toSeconds by seconds in a minute. This is based on the standard definition of a minute as 60 seconds.

This instance is immutable and unaffected by this method call.

toString

fun toString(): String

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"
  

truncatedTo

fun truncatedTo(unit: TemporalUnit!): Duration!

Returns a copy of this Duration truncated to the specified unit.

Truncating the duration returns a copy of the original with conceptual fields smaller than the specified unit set to zero. For example, truncating with the MINUTES unit will round down towards zero to the nearest minute, setting the seconds and nanoseconds to zero.

The unit must have a duration that divides into the length of a standard day without remainder. This includes all java.time.temporal.ChronoUnit#isTimeBased()} and DAYS. Other ChronoUnits throw an exception.

This instance is immutable and unaffected by this method call.

withNanos

fun withNanos(nanoOfSecond: Int): Duration!

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.

withSeconds

fun withSeconds(seconds: Long): Duration!

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.

ZERO

static val ZERO: Duration!

Constant for a duration of zero.