org.joda.time
Class Duration

java.lang.Object
  extended by org.joda.time.base.AbstractDuration
      extended by org.joda.time.base.BaseDuration
          extended by org.joda.time.Duration
All Implemented Interfaces:
Serializable, Comparable<ReadableDuration>, ReadableDuration

public final class Duration
extends BaseDuration
implements ReadableDuration, Serializable

An immutable duration specifying a length of time in milliseconds.

A duration is defined by a fixed number of milliseconds. There is no concept of fields, such as days or seconds, as these fields can vary in length. A duration may be converted to a Period to obtain field values. This conversion will typically cause a loss of precision however.

Duration is thread-safe and immutable.

Since:
1.0
Author:
Brian S O'Neill, Stephen Colebourne
See Also:
Serialized Form

Field Summary
static Duration ZERO
          Constant representing zero millisecond duration
 
Constructor Summary
Duration(long duration)
          Creates a duration from the given millisecond duration.
Duration(long startInstant, long endInstant)
          Creates a duration from the given interval endpoints.
Duration(Object duration)
          Creates a duration from the specified object using the ConverterManager.
Duration(ReadableInstant start, ReadableInstant end)
          Creates a duration from the given interval endpoints.
 
Method Summary
 long getStandardDays()
          Gets the length of this duration in days assuming that there are the standard number of milliseconds in a day.
 long getStandardHours()
          Gets the length of this duration in hours assuming that there are the standard number of milliseconds in an hour.
 long getStandardMinutes()
          Gets the length of this duration in minutes assuming that there are the standard number of milliseconds in a minute.
 long getStandardSeconds()
          Gets the length of this duration in seconds assuming that there are the standard number of milliseconds in a second.
static Duration millis(long millis)
          Create a duration with the specified number of milliseconds.
 Duration minus(long amount)
          Returns a new duration with this length minus that specified.
 Duration minus(ReadableDuration amount)
          Returns a new duration with this length minus that specified.
static Duration parse(String str)
          Parses a Duration from the specified string.
 Duration plus(long amount)
          Returns a new duration with this length plus that specified.
 Duration plus(ReadableDuration amount)
          Returns a new duration with this length plus that specified.
static Duration standardDays(long days)
          Create a duration with the specified number of days assuming that there are the standard number of milliseconds in a day.
static Duration standardHours(long hours)
          Create a duration with the specified number of hours assuming that there are the standard number of milliseconds in an hour.
static Duration standardMinutes(long minutes)
          Create a duration with the specified number of minutes assuming that there are the standard number of milliseconds in a minute.
static Duration standardSeconds(long seconds)
          Create a duration with the specified number of seconds assuming that there are the standard number of milliseconds in a second.
 Duration toDuration()
          Get this duration as an immutable Duration object by returning this.
 Days toStandardDays()
          Converts this duration to a period in days assuming that there are the standard number of milliseconds in a day.
 Hours toStandardHours()
          Converts this duration to a period in hours assuming that there are the standard number of milliseconds in an hour.
 Minutes toStandardMinutes()
          Converts this duration to a period in minutes assuming that there are the standard number of milliseconds in a minute.
 Seconds toStandardSeconds()
          Converts this duration to a period in seconds assuming that there are the standard number of milliseconds in a second.
 Duration withDurationAdded(long durationToAdd, int scalar)
          Returns a new duration with this length plus that specified multiplied by the scalar.
 Duration withDurationAdded(ReadableDuration durationToAdd, int scalar)
          Returns a new duration with this length plus that specified multiplied by the scalar.
 Duration withMillis(long duration)
          Creates a new Duration instance with a different milisecond length.
 
Methods inherited from class org.joda.time.base.BaseDuration
getMillis, setMillis, toIntervalFrom, toIntervalTo, toPeriod, toPeriod, toPeriod, toPeriodFrom, toPeriodFrom, toPeriodTo, toPeriodTo
 
Methods inherited from class org.joda.time.base.AbstractDuration
compareTo, equals, hashCode, isEqual, isLongerThan, isShorterThan, toPeriod, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.joda.time.ReadableDuration
equals, getMillis, hashCode, isEqual, isLongerThan, isShorterThan, toPeriod, toString
 
Methods inherited from interface java.lang.Comparable
compareTo
 

Field Detail

ZERO

public static final Duration ZERO
Constant representing zero millisecond duration

Constructor Detail

Duration

public Duration(long duration)
Creates a duration from the given millisecond duration.

Parameters:
duration - the duration, in milliseconds

Duration

public Duration(long startInstant,
                long endInstant)
Creates a duration from the given interval endpoints.

Parameters:
startInstant - interval start, in milliseconds
endInstant - interval end, in milliseconds
Throws:
ArithmeticException - if the duration exceeds a 64 bit long

Duration

public Duration(ReadableInstant start,
                ReadableInstant end)
Creates a duration from the given interval endpoints.

Parameters:
start - interval start, null means now
end - interval end, null means now
Throws:
ArithmeticException - if the duration exceeds a 64 bit long

Duration

public Duration(Object duration)
Creates a duration from the specified object using the ConverterManager.

Parameters:
duration - duration to convert
Throws:
IllegalArgumentException - if duration is invalid
Method Detail

parse

public static Duration parse(String str)
Parses a Duration from the specified string.

This parses the format PTa.bS, as per AbstractDuration.toString().

Parameters:
str - the string to parse, not null
Since:
2.0

standardDays

public static Duration standardDays(long days)
Create a duration with the specified number of days assuming that there are the standard number of milliseconds in a day.

This method assumes that there are 24 hours in a day, 60 minutes in an hour, 60 seconds in a minute and 1000 milliseconds in a second. This will be true for most days, however days with Daylight Savings changes will not have 24 hours, so use this method with care.

A Duration is a representation of an amount of time. If you want to express the concepts of 'days' you should consider using the Days class.

Parameters:
days - the number of standard days in this duration
Returns:
the duration, never null
Throws:
ArithmeticException - if the days value is too large
Since:
1.6

standardHours

public static Duration standardHours(long hours)
Create a duration with the specified number of hours assuming that there are the standard number of milliseconds in an hour.

This method assumes that there are 60 minutes in an hour, 60 seconds in a minute and 1000 milliseconds in a second. All currently supplied chronologies use this definition.

A Duration is a representation of an amount of time. If you want to express the concepts of 'hours' you should consider using the Hours class.

Parameters:
hours - the number of standard hours in this duration
Returns:
the duration, never null
Throws:
ArithmeticException - if the hours value is too large
Since:
1.6

standardMinutes

public static Duration standardMinutes(long minutes)
Create a duration with the specified number of minutes assuming that there are the standard number of milliseconds in a minute.

This method assumes that there are 60 seconds in a minute and 1000 milliseconds in a second. All currently supplied chronologies use this definition.

A Duration is a representation of an amount of time. If you want to express the concepts of 'minutes' you should consider using the Minutes class.

Parameters:
minutes - the number of standard minutes in this duration
Returns:
the duration, never null
Throws:
ArithmeticException - if the minutes value is too large
Since:
1.6

standardSeconds

public static Duration standardSeconds(long seconds)
Create a duration with the specified number of seconds assuming that there are the standard number of milliseconds in a second.

This method assumes that there are 1000 milliseconds in a second. All currently supplied chronologies use this definition.

A Duration is a representation of an amount of time. If you want to express the concepts of 'seconds' you should consider using the Seconds class.

Parameters:
seconds - the number of standard seconds in this duration
Returns:
the duration, never null
Throws:
ArithmeticException - if the seconds value is too large
Since:
1.6

millis

public static Duration millis(long millis)
Create a duration with the specified number of milliseconds.

Parameters:
millis - the number of standard milliseconds in this duration
Returns:
the duration, never null
Since:
2.0

getStandardDays

public long getStandardDays()
Gets the length of this duration in days assuming that there are the standard number of milliseconds in a day.

This method assumes that there are 24 hours in a day, 60 minutes in an hour, 60 seconds in a minute and 1000 milliseconds in a second. This will be true for most days, however days with Daylight Savings changes will not have 24 hours, so use this method with care.

This returns getMillis() / MILLIS_PER_DAY. The result is an integer division, thus excess milliseconds are truncated.

Returns:
the length of the duration in standard seconds
Since:
2.0

getStandardHours

public long getStandardHours()
Gets the length of this duration in hours assuming that there are the standard number of milliseconds in an hour.

This method assumes that there are 60 minutes in an hour, 60 seconds in a minute and 1000 milliseconds in a second. All currently supplied chronologies use this definition.

This returns getMillis() / MILLIS_PER_HOUR. The result is an integer division, thus excess milliseconds are truncated.

Returns:
the length of the duration in standard seconds
Since:
2.0

getStandardMinutes

public long getStandardMinutes()
Gets the length of this duration in minutes assuming that there are the standard number of milliseconds in a minute.

This method assumes that there are 60 seconds in a minute and 1000 milliseconds in a second. All currently supplied chronologies use this definition.

This returns getMillis() / 60000. The result is an integer division, thus excess milliseconds are truncated.

Returns:
the length of the duration in standard seconds
Since:
2.0

getStandardSeconds

public long getStandardSeconds()
Gets the length of this duration in seconds assuming that there are the standard number of milliseconds in a second.

This method assumes that there are 1000 milliseconds in a second. All currently supplied chronologies use this definition.

This returns getMillis() / 1000. The result is an integer division, so 2999 millis returns 2 seconds.

Returns:
the length of the duration in standard seconds
Since:
1.6

toDuration

public Duration toDuration()
Get this duration as an immutable Duration object by returning this.

Specified by:
toDuration in interface ReadableDuration
Overrides:
toDuration in class AbstractDuration
Returns:
this

toStandardDays

public Days toStandardDays()
Converts this duration to a period in days assuming that there are the standard number of milliseconds in a day.

This method assumes that there are 24 hours in a day, 60 minutes in an hour, 60 seconds in a minute and 1000 milliseconds in a second. This will be true for most days, however days with Daylight Savings changes will not have 24 hours, so use this method with care.

Returns:
a period representing the number of standard days in this period, never null
Throws:
ArithmeticException - if the number of days is too large to be represented
Since:
2.0

toStandardHours

public Hours toStandardHours()
Converts this duration to a period in hours assuming that there are the standard number of milliseconds in an hour.

This method assumes that there are 60 minutes in an hour, 60 seconds in a minute and 1000 milliseconds in a second. All currently supplied chronologies use this definition.

Returns:
a period representing the number of standard hours in this period, never null
Throws:
ArithmeticException - if the number of hours is too large to be represented
Since:
2.0

toStandardMinutes

public Minutes toStandardMinutes()
Converts this duration to a period in minutes assuming that there are the standard number of milliseconds in a minute.

This method assumes that there are 60 seconds in a minute and 1000 milliseconds in a second. All currently supplied chronologies use this definition.

Returns:
a period representing the number of standard minutes in this period, never null
Throws:
ArithmeticException - if the number of minutes is too large to be represented
Since:
2.0

toStandardSeconds

public Seconds toStandardSeconds()
Converts this duration to a period in seconds assuming that there are the standard number of milliseconds in a second.

This method assumes that there are 1000 milliseconds in a second. All currently supplied chronologies use this definition.

Returns:
a period representing the number of standard seconds in this period, never null
Throws:
ArithmeticException - if the number of seconds is too large to be represented
Since:
1.6

withMillis

public Duration withMillis(long duration)
Creates a new Duration instance with a different milisecond length.

Parameters:
duration - the new length of the duration
Returns:
the new duration instance

withDurationAdded

public Duration withDurationAdded(long durationToAdd,
                                  int scalar)
Returns a new duration with this length plus that specified multiplied by the scalar. This instance is immutable and is not altered.

If the addition is zero, this instance is returned.

Parameters:
durationToAdd - the duration to add to this one
scalar - the amount of times to add, such as -1 to subtract once
Returns:
the new duration instance

withDurationAdded

public Duration withDurationAdded(ReadableDuration durationToAdd,
                                  int scalar)
Returns a new duration with this length plus that specified multiplied by the scalar. This instance is immutable and is not altered.

If the addition is zero, this instance is returned.

Parameters:
durationToAdd - the duration to add to this one, null means zero
scalar - the amount of times to add, such as -1 to subtract once
Returns:
the new duration instance

plus

public Duration plus(long amount)
Returns a new duration with this length plus that specified. This instance is immutable and is not altered.

If the addition is zero, this instance is returned.

Parameters:
amount - the duration to add to this one
Returns:
the new duration instance

plus

public Duration plus(ReadableDuration amount)
Returns a new duration with this length plus that specified. This instance is immutable and is not altered.

If the amount is zero, this instance is returned.

Parameters:
amount - the duration to add to this one, null means zero
Returns:
the new duration instance

minus

public Duration minus(long amount)
Returns a new duration with this length minus that specified. This instance is immutable and is not altered.

If the addition is zero, this instance is returned.

Parameters:
amount - the duration to take away from this one
Returns:
the new duration instance

minus

public Duration minus(ReadableDuration amount)
Returns a new duration with this length minus that specified. This instance is immutable and is not altered.

If the amount is zero, this instance is returned.

Parameters:
amount - the duration to take away from this one, null means zero
Returns:
the new duration instance


Copyright © 2002-2013 Joda.org. All Rights Reserved.