Class Duration
- All Implemented Interfaces:
Serializable
,Comparable<ReadableDuration>
,ReadableDuration
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.
Duration is thread-safe and immutable.
- Since:
- 1.0
- Author:
- Brian S O'Neill, Stephen Colebourne
- See Also:
-
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionDuration
(long duration) Creates a duration from the given millisecond duration.Duration
(long startInstant, long endInstant) Creates a duration from the given interval endpoints.Creates a duration from the specified object using theConverterManager
.Duration
(ReadableInstant start, ReadableInstant end) Creates a duration from the given interval endpoints. -
Method Summary
Modifier and TypeMethodDescriptionabs()
Returns a duration that has a positive or zero number of milliseconds.dividedBy
(long divisor) Returns a new duration with this length divided by the specified divisor.dividedBy
(long divisor, RoundingMode roundingMode) Returns a new duration with its length divided by the specified divisor.long
Gets the length of this duration in days assuming that there are the standard number of milliseconds in a day.long
Gets the length of this duration in hours assuming that there are the standard number of milliseconds in an hour.long
Gets the length of this duration in minutes assuming that there are the standard number of milliseconds in a minute.long
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.minus
(long amount) Returns a new duration with this length minus that specified.minus
(ReadableDuration amount) Returns a new duration with this length minus that specified.multipliedBy
(long multiplicand) Returns a new duration with this length multiplied by the specified multiplicand.negated()
Returns a new duration with this length negated.static Duration
Parses aDuration
from the specified string.plus
(long amount) Returns a new duration with this length plus that specified.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.Get this duration as an immutableDuration
object by returningthis
.Converts this duration to a period in days assuming that there are the standard number of milliseconds in a day.Converts this duration to a period in hours assuming that there are the standard number of milliseconds in an hour.Converts this duration to a period in minutes assuming that there are the standard number of milliseconds in a minute.Converts this duration to a period in seconds assuming that there are the standard number of milliseconds in a second.withDurationAdded
(long durationToAdd, int scalar) Returns a new duration with this length plus that specified multiplied by the scalar.withDurationAdded
(ReadableDuration durationToAdd, int scalar) Returns a new duration with this length plus that specified multiplied by the scalar.withMillis
(long duration) Creates a new Duration instance with a different millisecond 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 java.lang.Comparable
compareTo
Methods inherited from interface org.joda.time.ReadableDuration
equals, getMillis, hashCode, isEqual, isLongerThan, isShorterThan, toPeriod, toString
-
Field Details
-
ZERO
Constant representing zero millisecond duration
-
-
Constructor Details
-
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 millisecondsendInstant
- interval end, in milliseconds- Throws:
ArithmeticException
- if the duration exceeds a 64-bit long
-
Duration
Creates a duration from the given interval endpoints.- Parameters:
start
- interval start, null means nowend
- interval end, null means now- Throws:
ArithmeticException
- if the duration exceeds a 64-bit long
-
Duration
Creates a duration from the specified object using theConverterManager
.- Parameters:
duration
- duration to convert- Throws:
IllegalArgumentException
- if duration is invalid
-
-
Method Details
-
parse
Parses aDuration
from the specified string.This parses the format
PTa.bS
, as perAbstractDuration.toString()
.- Parameters:
str
- the string to parse, not null- Returns:
- the parsed duration, not null
- Since:
- 2.0
-
standardDays
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 concept 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
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 concept 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
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 concept 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
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 concept 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
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 days
- 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 hours
- 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() / MILLIS_PER_MINUTE
. The result is an integer division, thus excess milliseconds are truncated.- Returns:
- the length of the duration in standard minutes
- 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
Get this duration as an immutableDuration
object by returningthis
.- Specified by:
toDuration
in interfaceReadableDuration
- Overrides:
toDuration
in classAbstractDuration
- Returns:
this
-
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
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
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
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
Creates a new Duration instance with a different millisecond length.- Parameters:
duration
- the new length of the duration- Returns:
- the new duration instance
-
withDurationAdded
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 onescalar
- the amount of times to add, such as -1 to subtract once- Returns:
- the new duration instance
-
withDurationAdded
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 zeroscalar
- the amount of times to add, such as -1 to subtract once- Returns:
- the new duration instance
-
plus
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
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
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
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
-
multipliedBy
Returns a new duration with this length multiplied by the specified multiplicand. This instance is immutable and is not altered.If the multiplicand is one, this instance is returned.
- Parameters:
multiplicand
- the multiplicand to multiply this one by- Returns:
- the new duration instance
-
dividedBy
Returns a new duration with this length divided by the specified divisor. This instance is immutable and is not altered.If the divisor is one, this instance is returned.
- Parameters:
divisor
- the divisor to divide this one by- Returns:
- the new duration instance
-
dividedBy
Returns a new duration with its length divided by the specified divisor.RoundingMode
can be specified. This instance is immutable and is not altered.If the divisor is one, this instance is returned.
- Parameters:
divisor
- the divisor to divide this one byroundingMode
- the type of rounding desired- Returns:
- the new duration instance
-
negated
Returns a new duration with this length negated. This instance is immutable and is not altered.- Returns:
- the new duration instance
-
abs
Returns a duration that has a positive or zero number of milliseconds.This instance is immutable and is not altered.
- Returns:
- the absolute duration instance
- Since:
- 2.10
-