Skip to content

Most visited

Recently visited

navigation

Duration

public final class Duration
extends Object implements TemporalAmount, Comparable<Duration>, Serializable

java.lang.Object
   ↳ java.time.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 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.

Summary

Fields

public static final Duration ZERO

Constant for a duration of zero.

Public methods

Duration abs()

Returns a copy of this duration with a positive length.

Temporal addTo(Temporal temporal)

Adds this duration to the specified temporal object.

static Duration between(Temporal startInclusive, Temporal endExclusive)

Obtains a Duration representing the duration between two temporal objects.

int compareTo(Duration otherDuration)

Compares this duration to the specified Duration.

Duration dividedBy(long divisor)

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

boolean equals(Object otherDuration)

Checks if this duration is equal to the specified Duration.

static Duration from(TemporalAmount amount)

Obtains an instance of Duration from a temporal amount.

long get(TemporalUnit unit)

Gets the value of the requested unit.

int getNano()

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

long getSeconds()

Gets the number of seconds in this duration.

List<TemporalUnit> getUnits()

Gets the set of units supported by this duration.

int hashCode()

A hash code for this duration.

boolean isNegative()

Checks if this duration is negative, excluding zero.

boolean isZero()

Checks if this duration is zero length.

Duration minus(Duration duration)

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

Duration minus(long amountToSubtract, TemporalUnit unit)

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

Duration minusDays(long daysToSubtract)

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

Duration minusHours(long hoursToSubtract)

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

Duration minusMillis(long millisToSubtract)

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

Duration minusMinutes(long minutesToSubtract)

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

Duration minusNanos(long nanosToSubtract)

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

Duration minusSeconds(long secondsToSubtract)

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

Duration multipliedBy(long multiplicand)

Returns a copy of this duration multiplied by the scalar.

Duration negated()

Returns a copy of this duration with the length negated.

static Duration of(long amount, TemporalUnit unit)

Obtains a Duration representing an amount in the specified unit.

static Duration ofDays(long days)

Obtains a Duration representing a number of standard 24 hour days.

static Duration ofHours(long hours)

Obtains a Duration representing a number of standard hours.

static Duration ofMillis(long millis)

Obtains a Duration representing a number of milliseconds.

static Duration ofMinutes(long minutes)

Obtains a Duration representing a number of standard minutes.

static Duration ofNanos(long nanos)

Obtains a Duration representing a number of nanoseconds.

static Duration ofSeconds(long seconds, long nanoAdjustment)

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

static Duration ofSeconds(long seconds)

Obtains a Duration representing a number of seconds.

static Duration parse(CharSequence text)

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

Duration plus(Duration duration)

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

Duration plus(long amountToAdd, TemporalUnit unit)

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

Duration plusDays(long daysToAdd)

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

Duration plusHours(long hoursToAdd)

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

Duration plusMillis(long millisToAdd)

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

Duration plusMinutes(long minutesToAdd)

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

Duration plusNanos(long nanosToAdd)

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

Duration plusSeconds(long secondsToAdd)

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

Temporal subtractFrom(Temporal temporal)

Subtracts this duration from the specified temporal object.

long toDays()

Gets the number of days in this duration.

long toHours()

Gets the number of hours in this duration.

long toMillis()

Converts this duration to the total length in milliseconds.

long toMinutes()

Gets the number of minutes in this duration.

long toNanos()

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

String toString()

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

Duration withNanos(int nanoOfSecond)

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

Duration withSeconds(long seconds)

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

Inherited methods

From class java.lang.Object
From interface java.time.temporal.TemporalAmount
From interface java.lang.Comparable

Fields

ZERO

added in API level 26
Duration ZERO

Constant for a duration of zero.

Public methods

abs

added in API level 26
Duration abs ()

Returns a copy of this duration with a positive length.

This method returns a positive duration by effectively removing the sign from any negative total length. For example, PT-1.3S will be returned as PT1.3S.

This instance is immutable and unaffected by this method call.

Returns
Duration a Duration based on this duration with an absolute length, not null

Throws
ArithmeticException if numeric overflow occurs

addTo

added in API level 26
Temporal addTo (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 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.

Parameters
temporal Temporal: the temporal object to adjust, not null

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

Throws
DateTimeException if unable to add
ArithmeticException if numeric overflow occurs

between

added in API level 26
Duration between (Temporal startInclusive, 
                Temporal endExclusive)

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.

Parameters
startInclusive Temporal: the start instant, inclusive, not null

endExclusive Temporal: the end instant, exclusive, not null

Returns
Duration a Duration, not null

Throws
DateTimeException if the seconds between the temporals cannot be obtained
ArithmeticException if the calculation exceeds the capacity of Duration

compareTo

added in API level 26
int compareTo (Duration otherDuration)

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.

Parameters
otherDuration Duration: the other duration to compare to, not null

Returns
int the comparator value, negative if less, positive if greater

dividedBy

added in API level 26
Duration dividedBy (long divisor)

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

This instance is immutable and unaffected by this method call.

Parameters
divisor long: the value to divide the duration by, positive or negative, not zero

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

Throws
ArithmeticException if the divisor is zero or if numeric overflow occurs

equals

added in API level 26
boolean equals (Object otherDuration)

Checks if this duration is equal to the specified Duration.

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

Parameters
otherDuration Object: the other duration, null returns false

Returns
boolean true if the other duration is equal to this one

from

added in API level 26
Duration from (TemporalAmount amount)

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 DAYS which is treated as 24 hours. If any other units are found then an exception is thrown.

Parameters
amount TemporalAmount: the temporal amount to convert, not null

Returns
Duration the equivalent duration, not null

Throws
DateTimeException if unable to convert to a Duration
ArithmeticException if numeric overflow occurs

get

added in API level 26
long get (TemporalUnit unit)

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.

Parameters
unit TemporalUnit: the TemporalUnit for which to return the value

Returns
long the long value of the unit

Throws
DateTimeException if the unit is not supported
UnsupportedTemporalTypeException if the unit is not supported

getNano

added in API level 26
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
int the nanoseconds within the second part of the length of the duration, from 0 to 999,999,999

getSeconds

added in API level 26
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
long the whole seconds part of the length of the duration, positive or negative

getUnits

added in API level 26
List<TemporalUnit> getUnits ()

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(TemporalUnit) to access the entire state of the duration.

Returns
List<TemporalUnit> a list containing the seconds and nanos units, not null

hashCode

added in API level 26
int hashCode ()

A hash code for this duration.

Returns
int a suitable hash code

isNegative

added in API level 26
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
boolean true if this duration has a total length less than zero

isZero

added in API level 26
boolean isZero ()

Checks if this duration is zero length.

A Duration represents a directed distance between two points on the time-line and can therefore be positive, zero or negative. This method checks whether the length is zero.

Returns
boolean true if this duration has a total length equal to zero

minus

added in API level 26
Duration minus (Duration duration)

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

This instance is immutable and unaffected by this method call.

Parameters
duration Duration: the duration to subtract, positive or negative, not null

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

Throws
ArithmeticException if numeric overflow occurs

minus

added in API level 26
Duration minus (long amountToSubtract, 
                TemporalUnit unit)

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 DAYS which is treated as 24 hours. Other units throw an exception.

This instance is immutable and unaffected by this method call.

Parameters
amountToSubtract long: 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

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

Throws
ArithmeticException if numeric overflow occurs

minusDays

added in API level 26
Duration minusDays (long daysToSubtract)

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.

Parameters
daysToSubtract long: the days to subtract, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

minusHours

added in API level 26
Duration minusHours (long hoursToSubtract)

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.

Parameters
hoursToSubtract long: the hours to subtract, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

minusMillis

added in API level 26
Duration minusMillis (long millisToSubtract)

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

This instance is immutable and unaffected by this method call.

Parameters
millisToSubtract long: the milliseconds to subtract, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

minusMinutes

added in API level 26
Duration minusMinutes (long minutesToSubtract)

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.

Parameters
minutesToSubtract long: the minutes to subtract, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

minusNanos

added in API level 26
Duration minusNanos (long nanosToSubtract)

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

This instance is immutable and unaffected by this method call.

Parameters
nanosToSubtract long: the nanoseconds to subtract, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

minusSeconds

added in API level 26
Duration minusSeconds (long secondsToSubtract)

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

This instance is immutable and unaffected by this method call.

Parameters
secondsToSubtract long: the seconds to subtract, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

multipliedBy

added in API level 26
Duration multipliedBy (long multiplicand)

Returns a copy of this duration multiplied by the scalar.

This instance is immutable and unaffected by this method call.

Parameters
multiplicand long: the value to multiply the duration by, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

negated

added in API level 26
Duration negated ()

Returns a copy of this duration with the length negated.

This method swaps the sign of the total length of this duration. For example, PT1.3S will be returned as PT-1.3S.

This instance is immutable and unaffected by this method call.

Returns
Duration a Duration based on this duration with the amount negated, not null

Throws
ArithmeticException if numeric overflow occurs

of

added in API level 26
Duration of (long amount, 
                TemporalUnit unit)

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);
 
Only a subset of units are accepted by this method. The unit must either have an exact duration or be DAYS which is treated as 24 hours. Other units throw an exception.

Parameters
amount long: 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

Returns
Duration a Duration, not null

Throws
DateTimeException if the period unit has an estimated duration
ArithmeticException if a numeric overflow occurs

ofDays

added in API level 26
Duration ofDays (long days)

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.

Parameters
days long: the number of days, positive or negative

Returns
Duration a Duration, not null

Throws
ArithmeticException if the input days exceeds the capacity of Duration

ofHours

added in API level 26
Duration ofHours (long hours)

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.

Parameters
hours long: the number of hours, positive or negative

Returns
Duration a Duration, not null

Throws
ArithmeticException if the input hours exceeds the capacity of Duration

ofMillis

added in API level 26
Duration ofMillis (long millis)

Obtains a Duration representing a number of milliseconds.

The seconds and nanoseconds are extracted from the specified milliseconds.

Parameters
millis long: the number of milliseconds, positive or negative

Returns
Duration a Duration, not null

ofMinutes

added in API level 26
Duration ofMinutes (long minutes)

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.

Parameters
minutes long: the number of minutes, positive or negative

Returns
Duration a Duration, not null

Throws
ArithmeticException if the input minutes exceeds the capacity of Duration

ofNanos

added in API level 26
Duration ofNanos (long nanos)

Obtains a Duration representing a number of nanoseconds.

The seconds and nanoseconds are extracted from the specified nanoseconds.

Parameters
nanos long: the number of nanoseconds, positive or negative

Returns
Duration a Duration, not null

ofSeconds

added in API level 26
Duration ofSeconds (long seconds, 
                long nanoAdjustment)

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:

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

Parameters
seconds long: the number of seconds, positive or negative

nanoAdjustment long: the nanosecond adjustment to the number of seconds, positive or negative

Returns
Duration a Duration, not null

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

ofSeconds

added in API level 26
Duration ofSeconds (long seconds)

Obtains a Duration representing a number of seconds.

The nanosecond in second field is set to zero.

Parameters
seconds long: the number of seconds, positive or negative

Returns
Duration a Duration, not null

parse

added in API level 26
Duration parse (CharSequence text)

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"
 

Parameters
text CharSequence: the text to parse, not null

Returns
Duration the parsed duration, not null

Throws
DateTimeParseException if the text cannot be parsed to a duration

plus

added in API level 26
Duration plus (Duration duration)

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

This instance is immutable and unaffected by this method call.

Parameters
duration Duration: the duration to add, positive or negative, not null

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

Throws
ArithmeticException if numeric overflow occurs

plus

added in API level 26
Duration plus (long amountToAdd, 
                TemporalUnit unit)

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 DAYS which is treated as 24 hours. Other units throw an exception.

This instance is immutable and unaffected by this method call.

Parameters
amountToAdd long: 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

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

Throws
UnsupportedTemporalTypeException if the unit is not supported
ArithmeticException if numeric overflow occurs

plusDays

added in API level 26
Duration plusDays (long daysToAdd)

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.

Parameters
daysToAdd long: the days to add, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

plusHours

added in API level 26
Duration plusHours (long hoursToAdd)

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

This instance is immutable and unaffected by this method call.

Parameters
hoursToAdd long: the hours to add, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

plusMillis

added in API level 26
Duration plusMillis (long millisToAdd)

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

This instance is immutable and unaffected by this method call.

Parameters
millisToAdd long: the milliseconds to add, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

plusMinutes

added in API level 26
Duration plusMinutes (long minutesToAdd)

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

This instance is immutable and unaffected by this method call.

Parameters
minutesToAdd long: the minutes to add, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

plusNanos

added in API level 26
Duration plusNanos (long nanosToAdd)

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

This instance is immutable and unaffected by this method call.

Parameters
nanosToAdd long: the nanoseconds to add, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

plusSeconds

added in API level 26
Duration plusSeconds (long secondsToAdd)

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

This instance is immutable and unaffected by this method call.

Parameters
secondsToAdd long: the seconds to add, positive or negative

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

Throws
ArithmeticException if numeric overflow occurs

subtractFrom

added in API level 26
Temporal subtractFrom (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 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.

Parameters
temporal Temporal: the temporal object to adjust, not null

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

Throws
DateTimeException if unable to subtract
ArithmeticException if numeric overflow occurs

toDays

added in API level 26
long toDays ()

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.

Returns
long the number of days in the duration, may be negative

toHours

added in API level 26
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
long the number of hours in the duration, may be negative

toMillis

added in API level 26
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.

Returns
long the total length of the duration in milliseconds

Throws
ArithmeticException if numeric overflow occurs

toMinutes

added in API level 26
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
long the number of minutes in the duration, may be negative

toNanos

added in API level 26
long toNanos ()

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.

Returns
long the total length of the duration in nanoseconds

Throws
ArithmeticException if numeric overflow occurs

toString

added in API level 26
String 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.

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.

Returns
String an ISO-8601 representation of this duration, not null

withNanos

added in API level 26
Duration withNanos (int nanoOfSecond)

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.

Parameters
nanoOfSecond int: the nano-of-second to represent, from 0 to 999,999,999

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

Throws
DateTimeException if the nano-of-second is invalid

withSeconds

added in API level 26
Duration withSeconds (long seconds)

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.

Parameters
seconds long: the seconds to represent, may be negative

Returns
Duration a Duration based on this period with the requested seconds, not null

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience. (Dec 2017 Android Platform & Tools Survey)