Duration (ThreeTen date and time API)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.time
Class Duration

java.lang.Object
  javax.time.Duration

All Implemented Interfaces:: java.io.Serializable, java.lang.Comparable<Duration>

public final class Duration
extends java.lang.Object
implements java.lang.Comparable<Duration>, java.io.Serializable
extends java.lang.Object
implements java.lang.Comparable<Duration>, java.io.Serializable

A duration between two instants on the time-line.

The Time Framework for Java models time as a series of instantaneous events, known as instants, along a single time-line. This class represents the duration between two of those instants. The model is of a directed duration, meaning that the duration may be negative.

A physical instant is an instantaneous event. However, for practicality the API and this class uses a precision of nanoseconds.

A physical duration could be of infinite length. However, for practicality the API and this class limits the length to the number of seconds that can be held in a long.

In order to represent the data a 96 bit number is required. To achieve this the data is stored as seconds, measured using a long, and nanoseconds, measured using an int. The nanosecond part will always be between 0 and 999,999,999 representing the nanosecond part of the second. For example, the negative duration of PT-0.1S is represented as -1 second and 900,000,000 nanoseconds.

In this API, the unit of "seconds" only has a precise meaning when applied to an instant. This is because it is the instant that defines the time scale used, not the duration. For example, the time-scale used by Instant uses a variable length second to avoid exposing leap seconds. By comparison, the TAI time scale follows the international scientific definition of a second exactly. For most applications, this subtlety will be irrelevant.

This class is immutable and thread-safe.

Author:: Michael Nascimento Santos, Stephen Colebourne
See Also:: Serialized Form

Field Summary
`static Duration`	`ZERO` Constant for a duration of zero.

Method Summary
`Duration`	`abs()` Returns a copy of this duration with a positive length.
`static Duration`	`between(InstantProvider startInclusive, InstantProvider endExclusive)` Obtains an instance of `Duration` representing the duration between two instants.
`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(java.lang.Object otherDuration)` Checks if this duration is equal to the specified `Duration`.
`long`	`get(java.util.concurrent.TimeUnit unit)` Gets the duration in terms of the specified unit.
`int`	`getNanoOfSecond()` Gets the number of nanoseconds within the second in this duration.
`long`	`getSeconds()` Gets the number of seconds in this duration.
`int`	`hashCode()` A hash code for this duration.
`boolean`	`isGreaterThan(Duration otherDuration)` Checks if this duration is greater than the specified `Duration`.
`boolean`	`isLessThan(Duration otherDuration)` Checks if this duration is less than the specified `Duration`.
`boolean`	`isNegative()` Checks if this duration is negative, excluding zero.
`boolean`	`isNegativeOrZero()` Checks if this duration is negative or zero.
`boolean`	`isPositive()` Checks if this duration is positive, excluding zero.
`boolean`	`isPositiveOrZero()` Checks if this duration is positive or 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 amount, java.util.concurrent.TimeUnit unit)` Returns a copy of this duration with the specified duration subtracted.
`Duration`	`minusMillis(long millisToSubtract)` Returns a copy of this duration with the specified number of milliseconds subtracted.
`Duration`	`minusNanos(long nanosToSubtract)` Returns a copy of this duration with the specified number of nanoseconds subtracted.
`Duration`	`minusSeconds(long secondsToSubtract)` Returns a copy of this duration with the specified number of 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, java.util.concurrent.TimeUnit unit)` Obtains an instance of `Duration` from a duration in a specified time unit.
`static Duration`	`ofDays(long days)` Obtains an instance of `Duration` from a number of standard 24 hour days.
`static Duration`	`ofHours(long hours)` Obtains an instance of `Duration` from a number of standard length hours.
`static Duration`	`ofMillis(long millis)` Obtains an instance of `Duration` from a number of milliseconds.
`static Duration`	`ofMinutes(long minutes)` Obtains an instance of `Duration` from a number of standard length minutes.
`static Duration`	`ofNanos(java.math.BigInteger nanos)` Obtains an instance of `Duration` from a number of nanoseconds.
`static Duration`	`ofNanos(long nanos)` Obtains an instance of `Duration` from a number of nanoseconds.
`static Duration`	`ofSeconds(java.math.BigDecimal seconds)` Obtains an instance of `Duration` from a number of seconds.
`static Duration`	`ofSeconds(long seconds)` Obtains an instance of `Duration` from a number of seconds.
`static Duration`	`ofSeconds(long seconds, long nanoAdjustment)` Obtains an instance of `Duration` from a number of seconds and an adjustment in nanoseconds.
`static Duration`	`parse(java.lang.CharSequence text)` Obtains an instance of `Duration` by parsing a text string.
`Duration`	`plus(Duration duration)` Returns a copy of this duration with the specified `Duration` added.
`Duration`	`plus(long amount, java.util.concurrent.TimeUnit unit)` Returns a copy of this duration with the specified duration added.
`Duration`	`plusMillis(long millisToAdd)` Returns a copy of this duration with the specified number of milliseconds added.
`Duration`	`plusNanos(long nanosToAdd)` Returns a copy of this duration with the specified number of nanoseconds added.
`Duration`	`plusSeconds(long secondsToAdd)` Returns a copy of this duration with the specified number of seconds added.
`long`	`toMillisLong()` Converts this duration to the total length in milliseconds.
`java.math.BigInteger`	`toNanos()` Converts this duration to the total length in nanoseconds expressed as a `BigInteger`.
`long`	`toNanosLong()` Converts this duration to the total length in nanoseconds expressed as a `long`.
`java.math.BigDecimal`	`toSeconds()` Converts this duration to the total length in seconds and fractional nanoseconds expressed as a `BigDecimal`.
`java.lang.String`	`toString()` A string representation of this duration using ISO-8601 seconds based representation, such as `PT12.345S`.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

ZERO

public static final Duration ZERO

Constant for a duration of zero.

Method Detail

ofSeconds

public static Duration ofSeconds(long seconds)

Obtains an instance of Duration from a number of seconds.

The nanosecond in second field is set to zero.

Parameters:: seconds - the number of seconds, positive or negative
Returns:: a Duration, not null

ofSeconds

public static Duration ofSeconds(long seconds,
                                 long nanoAdjustment)

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, -999999999);
  Duration.ofSeconds(2, 1000000001);

Parameters:: seconds - the number of seconds, positive or negative; nanoAdjustment - the nanosecond adjustment to the number of seconds, positive or negative
Returns:: a Duration, not null
Throws:: java.lang.ArithmeticException - if the adjustment causes the seconds to exceed the capacity of Duration

ofSeconds

public static Duration ofSeconds(java.math.BigDecimal seconds)

Obtains an instance of Duration from a number of seconds.

The seconds and nanoseconds are extracted from the specified BigDecimal. If the decimal is larger than Long.MAX_VALUE or has more than 9 decimal places then an exception is thrown.

Parameters:: seconds - the number of seconds, up to scale 9, positive or negative
Returns:: a Duration, not null
Throws:: java.lang.ArithmeticException - if the input seconds exceeds the capacity of a Duration

ofMillis

public static Duration ofMillis(long millis)

Obtains an instance of Duration from a number of milliseconds.

The seconds and nanoseconds are extracted from the specified milliseconds.

Parameters:: millis - the number of milliseconds, positive or negative
Returns:: a Duration, not null

ofNanos

public static Duration ofNanos(long nanos)

Obtains an instance of Duration from a number of nanoseconds.

The seconds and nanoseconds are extracted from the specified nanoseconds.

Parameters:: nanos - the number of nanoseconds, positive or negative
Returns:: a Duration, not null

ofNanos

public static Duration ofNanos(java.math.BigInteger nanos)

Obtains an instance of Duration from a number of nanoseconds.

The seconds and nanoseconds are extracted from the specified BigInteger. If the resulting seconds value is larger than Long.MAX_VALUE then an exception is thrown.

Parameters:: nanos - the number of nanoseconds, positive or negative, not null
Returns:: a Duration, not null
Throws:: java.lang.ArithmeticException - if the input nanoseconds exceeds the capacity of Duration

ofMinutes

public static Duration ofMinutes(long minutes)

Obtains an instance of Duration from a number of standard length 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 - the number of minutes, positive or negative
Returns:: a Duration, not null
Throws:: java.lang.ArithmeticException - if the input minutes exceeds the capacity of Duration

ofHours

public static Duration ofHours(long hours)

Obtains an instance of Duration from a number of standard length 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 - the number of hours, positive or negative
Returns:: a Duration, not null
Throws:: java.lang.ArithmeticException - if the input hours exceeds the capacity of Duration

ofDays

public static Duration ofDays(long days)

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.

Parameters:: days - the number of days, positive or negative
Returns:: a Duration, not null
Throws:: java.lang.ArithmeticException - if the input days exceeds the capacity of Duration

of

public static Duration of(long amount,
                          java.util.concurrent.TimeUnit unit)

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

The duration amount is measured in terms of the specified unit. For example:

  Duration.of(3, TimeUnit.SECONDS);
  Duration.of(465, TimeUnit.MICROSECONDS);

Parameters:: amount - the amount of the duration, positive or negative; unit - the unit that the duration is measured in, not null
Returns:: a Duration, not null
Throws:: java.lang.ArithmeticException - if the input amount exceeds the capacity of Duration which can only occur for units MINUTES, HOURS and DAYS

between

public static Duration between(InstantProvider startInclusive,
                               InstantProvider endExclusive)

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

A Duration represents a directed distance between two points on the time-line. As such, this method will return a negative duration if the end is before the start. To guarantee to obtain a positive duration call abs() on the result of this factory.

Parameters:: startInclusive - the start instant, inclusive, not null; endExclusive - the end instant, exclusive, not null
Returns:: a Duration, not null
Throws:: java.lang.ArithmeticException - if the calculation exceeds the capacity of Duration

parse

public static Duration parse(java.lang.CharSequence text)

Obtains an instance of Duration by parsing a text string.

This will parse the string produced by toString() which is the ISO-8601 format PTnS where n is the number of seconds with optional decimal part. The number must consist of ASCII numerals. There must only be a negative sign at the start of the number and it can only be present if the value is less than zero. There must be at least one digit before any decimal point. There must be between 1 and 9 inclusive digits after any decimal point. The letters (P, T and S) will be accepted in upper or lower case. The decimal point may be either a dot or a comma.

Parameters:: text - the text to parse, not null
Returns:: a Duration, not null
Throws:: CalendricalParseException - if the text cannot be parsed to a Duration

isZero

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

isPositive

public boolean isPositive()

Checks if this duration is positive, 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 greater than zero.

Returns:: true if this duration has a total length greater than zero

isPositiveOrZero

public boolean isPositiveOrZero()

Checks if this duration is positive or 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 greater than or equal to zero.

Returns:: true if this duration has a total length greater than or equal zero

isNegative

public boolean isNegative()

Checks if this duration is negative, excluding zero.

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

Returns:: true if this duration has a total length less than zero

isNegativeOrZero

public boolean isNegativeOrZero()

Checks if this duration is negative or 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 or equal to zero.

Returns:: true if this duration has a total length less than or equal to zero

getSeconds

public long getSeconds()

Gets the number of seconds in this duration.

The length of the duration is stored using two fields - seconds and nanoseconds. The nanoseconds part is a value from 0 to 999,999,999 that is an adjustment to the length in seconds. The total duration is defined by calling this method and getNanoOfSecond().

A Duration represents a directed distance between two points on the time-line. A negative duration is expressed by the negative sign of the seconds part. A duration of -1 nanosecond is stored as -1 seconds plus 999,999,999 nanoseconds.

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

getNanoOfSecond

public int getNanoOfSecond()

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

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

get

public long get(java.util.concurrent.TimeUnit unit)

Gets the duration in terms of the specified unit.

This method returns the duration converted to the unit, truncating excess precision. If the conversion would overflow, the result will saturate to Long.MAX_VALUE or Long.MIN_VALUE.

Returns:: the duration in the specified unit, saturated at Long.MAX_VALUE and Long.MIN_VALUE, positive or negative