java.io.Serializable
, java.time.temporal.TemporalAmount
public final class PeriodDuration
extends java.lang.Object
implements java.time.temporal.TemporalAmount, java.io.Serializable
This class models a quantity or amount of time in terms of a Period
and Duration
.
A period is a date-based amount of time, consisting of years, months and days.
A duration is a time-based amount of time, consisting of seconds and nanoseconds.
See the Period
and Duration
classes for more details.
The days in a period take account of daylight saving changes (23 or 25 hour days). When performing calculations, the period is added first, then the duration.
The model is of a directed amount, meaning that the amount may be negative.
This class must be treated as a value type. Do not synchronize, rely on the identity hash code or use the distinction between equals() and ==.
Modifier and Type | Field | Description |
---|---|---|
static PeriodDuration |
ZERO |
A constant for a duration of zero.
|
Modifier and Type | Method | Description |
---|---|---|
java.time.temporal.Temporal |
addTo(java.time.temporal.Temporal temporal) |
Adds this amount to the specified temporal object.
|
static PeriodDuration |
between(java.time.temporal.Temporal startInclusive,
java.time.temporal.Temporal endExclusive) |
Obtains an instance consisting of the amount of time between two temporals.
|
boolean |
equals(java.lang.Object otherAmount) |
Checks if this amount is equal to the specified
PeriodDuration . |
static PeriodDuration |
from(java.time.temporal.TemporalAmount amount) |
Obtains an instance from a temporal amount.
|
long |
get(java.time.temporal.TemporalUnit unit) |
Gets the value of the requested unit.
|
java.time.Duration |
getDuration() |
Gets the duration part.
|
java.time.Period |
getPeriod() |
Gets the period part.
|
java.util.List<java.time.temporal.TemporalUnit> |
getUnits() |
Gets the set of units supported by this amount.
|
int |
hashCode() |
A hash code for this amount.
|
boolean |
isZero() |
Checks if all parts of this amount are zero.
|
PeriodDuration |
minus(java.time.temporal.TemporalAmount amountToAdd) |
Returns a copy of this amount with the specified amount subtracted.
|
PeriodDuration |
multipliedBy(int scalar) |
Returns an instance with the amount multiplied by the specified scalar.
|
PeriodDuration |
negated() |
Returns an instance with the amount negated.
|
PeriodDuration |
normalizedStandardDays() |
Returns a copy of this instance with the days and duration normalized using the standard day of 24 hours.
|
PeriodDuration |
normalizedYears() |
Returns a copy of this instance with the years and months exactly normalized.
|
static PeriodDuration |
of(java.time.Duration duration) |
Obtains an instance based on a duration.
|
static PeriodDuration |
of(java.time.Period period) |
Obtains an instance based on a period.
|
static PeriodDuration |
of(java.time.Period period,
java.time.Duration duration) |
Obtains an instance based on a period and duration.
|
static PeriodDuration |
parse(java.lang.CharSequence text) |
Obtains an instance from a text string such as
PnYnMnDTnHnMnS . |
PeriodDuration |
plus(java.time.temporal.TemporalAmount amountToAdd) |
Returns a copy of this amount with the specified amount added.
|
java.time.temporal.Temporal |
subtractFrom(java.time.temporal.Temporal temporal) |
Subtracts this amount from the specified temporal object.
|
java.lang.String |
toString() |
Returns a string representation of the amount.
|
PeriodDuration |
withDuration(java.time.Duration duration) |
Returns a copy of this period-duration with a different duration.
|
PeriodDuration |
withPeriod(java.time.Period period) |
Returns a copy of this period-duration with a different period.
|
public static final PeriodDuration ZERO
public static PeriodDuration of(java.time.Period period, java.time.Duration duration)
The total amount of time of the resulting instance is the period plus the duration.
period
- the period, not nullduration
- the duration, not nullpublic static PeriodDuration of(java.time.Period period)
The duration will be zero.
period
- the period, not nullpublic static PeriodDuration of(java.time.Duration duration)
The period will be zero.
duration
- the duration, not nullpublic static PeriodDuration from(java.time.temporal.TemporalAmount amount)
This obtains an instance based on the specified amount.
A TemporalAmount
represents an amount of time which this factory
extracts to a PeriodDuration
.
The result is calculated by looping around each unit in the specified amount.
Any amount that is zero is ignore.
If a unit has an exact duration, it will be totalled using Duration.plus(Duration)
.
If the unit is days or weeks, it will be totalled into the days part of the period.
If the unit is months or quarters, it will be totalled into the months part of the period.
If the unit is years, decades, centuries or millennia, it will be totalled into the years part of the period.
amount
- the temporal amount to convert, not nulljava.time.DateTimeException
- if unable to convert to a Duration
java.lang.ArithmeticException
- if numeric overflow occurspublic static PeriodDuration parse(java.lang.CharSequence text)
PnYnMnDTnHnMnS
.
This will parse the string produced by toString()
which is
based on the ISO-8601 period formats PnYnMnDTnHnMnS
and PnW
.
The string starts with an optional sign, denoted by the ASCII negative
or positive symbol. If negative, the whole amount is negated.
The ASCII letter "P" is next in upper or lower case.
There are then a number of sections, each consisting of a number and a suffix.
At least one of the sections must be present.
The sections have suffixes in ASCII of "Y" for years, "M" for months,
"W" for weeks, "D" for days, "H" for hours, "M" for minutes, "S" for seconds,
accepted in upper or lower case. Note that the ASCII letter "T" separates
the date and time parts and must be present if any time part is present.
The suffixes must occur in order.
The number part of each section must consist of ASCII digits.
The number may be prefixed by the ASCII negative or positive symbol.
The number must parse to an int
.
Any week-based input is multiplied by 7 and treated as a number of days.
The leading plus/minus sign, and negative values for weeks and days are not part of the ISO-8601 standard.
Note that the date style format PYYYY-MM-DDTHH:MM:SS
is not supported.
For example, the following are valid inputs:
"P2Y" -- PeriodDuration.of(Period.ofYears(2)) "P3M" -- PeriodDuration.of(Period.ofMonths(3)) "P4W" -- PeriodDuration.of(Period.ofWeeks(4)) "P5D" -- PeriodDuration.of(Period.ofDays(5)) "PT6H" -- PeriodDuration.of(Duration.ofHours(6)) "P1Y2M3D" -- PeriodDuration.of(Period.of(1, 2, 3)) "P1Y2M3W4DT8H" -- PeriodDuration.of(Period.of(1, 2, 25), Duration.ofHours(8)) "P-1Y2M" -- PeriodDuration.of(Period.of(-1, 2, 0)) "-P1Y2M" -- PeriodDuration.of(Period.of(-1, -2, 0))
text
- the text to parse, not nulljava.time.format.DateTimeParseException
- if the text cannot be parsed to a periodpublic static PeriodDuration between(java.time.temporal.Temporal startInclusive, java.time.temporal.Temporal endExclusive)
The start is included, but the end is not. The result of this method can be negative if the end is before the start.
The calculation examines the temporals and extracts LocalDate
and LocalTime
.
If the time is missing, it will be defaulted to midnight.
If one date is missing, it will be defaulted to the other date.
It then finds the amount of time between the two dates and between the two times.
startInclusive
- the start, inclusive, not nullendExclusive
- the end, exclusive, not nullpublic long get(java.time.temporal.TemporalUnit unit)
This returns a value for the supported units - ChronoUnit.YEARS
,
ChronoUnit.MONTHS
, ChronoUnit.DAYS
, ChronoUnit.SECONDS
and ChronoUnit.NANOS
.
All other units throw an exception.
Note that hours and minutes throw an exception.
get
in interface java.time.temporal.TemporalAmount
unit
- the TemporalUnit
for which to return the valuejava.time.temporal.UnsupportedTemporalTypeException
- if the unit is not supportedpublic java.util.List<java.time.temporal.TemporalUnit> getUnits()
This returns the list ChronoUnit.YEARS
, ChronoUnit.MONTHS
,
ChronoUnit.DAYS
, ChronoUnit.SECONDS
and ChronoUnit.NANOS
.
This set can be used in conjunction with get(TemporalUnit)
to access the entire state of the amount.
getUnits
in interface java.time.temporal.TemporalAmount
public java.time.Period getPeriod()
public PeriodDuration withPeriod(java.time.Period period)
This instance is immutable and unaffected by this method call.
period
- the new periodpublic java.time.Duration getDuration()
public PeriodDuration withDuration(java.time.Duration duration)
This instance is immutable and unaffected by this method call.
duration
- the new durationpublic boolean isZero()
This returns true if both Period.isZero()
and Duration.isZero()
return true.
public PeriodDuration plus(java.time.temporal.TemporalAmount amountToAdd)
The parameter is converted using from(TemporalAmount)
.
The period and duration are combined separately.
This instance is immutable and unaffected by this method call.
amountToAdd
- the amount to add, not nullDays
based on this instance with the requested amount added, not nulljava.time.DateTimeException
- if the specified amount contains an invalid unitjava.lang.ArithmeticException
- if numeric overflow occurspublic PeriodDuration minus(java.time.temporal.TemporalAmount amountToAdd)
The parameter is converted using from(TemporalAmount)
.
The period and duration are combined separately.
This instance is immutable and unaffected by this method call.
amountToAdd
- the amount to add, not nullDays
based on this instance with the requested amount subtracted, not nulljava.time.DateTimeException
- if the specified amount contains an invalid unitjava.lang.ArithmeticException
- if numeric overflow occurspublic PeriodDuration multipliedBy(int scalar)
This instance is immutable and unaffected by this method call.
scalar
- the scalar to multiply by, not nulljava.lang.ArithmeticException
- if numeric overflow occurspublic PeriodDuration negated()
This instance is immutable and unaffected by this method call.
java.lang.ArithmeticException
- if numeric overflow occurs, which only happens if
the amount is Long.MIN_VALUE
public PeriodDuration normalizedYears()
This normalizes the years and months units, leaving the days unit unchanged. The result is exact, always representing the same amount of time.
The months unit is adjusted to have an absolute value less than 11, with the years unit being adjusted to compensate. For example, a period of "1 year and 15 months" will be normalized to "2 years and 3 months".
The sign of the years and months units will be the same after normalization. For example, a period of "1 year and -25 months" will be normalized to "-1 year and -1 month".
Note that no normalization is performed on the days or duration.
This instance is immutable and unaffected by this method call.
PeriodDuration
based on this one with excess months normalized to years, not nulljava.lang.ArithmeticException
- if numeric overflow occurspublic PeriodDuration normalizedStandardDays()
This normalizes the days and duration, leaving the years and months unchanged. The result uses a standard day length of 24 hours.
This combines the duration seconds with the number of days and shares the total seconds between the two fields. For example, a period of "2 days and 86401 seconds" will be normalized to "3 days and 1 second".
The sign of the days and duration will be the same after normalization. For example, a period of "1 day and -172801 seconds" will be normalized to "-1 day and -1 second".
Note that no normalization is performed on the years or months.
This instance is immutable and unaffected by this method call.
PeriodDuration
based on this one with excess duration normalized to days, not nulljava.lang.ArithmeticException
- if numeric overflow occurspublic java.time.temporal.Temporal addTo(java.time.temporal.Temporal temporal)
This returns a temporal object of the same observable type as the input with this amount added. This simply adds the period and duration to the temporal.
This instance is immutable and unaffected by this method call.
addTo
in interface java.time.temporal.TemporalAmount
temporal
- the temporal object to adjust, not nulljava.time.DateTimeException
- if unable to addjava.time.temporal.UnsupportedTemporalTypeException
- if the DAYS unit is not supportedjava.lang.ArithmeticException
- if numeric overflow occurspublic java.time.temporal.Temporal subtractFrom(java.time.temporal.Temporal temporal)
This returns a temporal object of the same observable type as the input with this amount subtracted. This simply subtracts the period and duration from the temporal.
This instance is immutable and unaffected by this method call.
subtractFrom
in interface java.time.temporal.TemporalAmount
temporal
- the temporal object to adjust, not nulljava.time.DateTimeException
- if unable to subtractjava.time.temporal.UnsupportedTemporalTypeException
- if the DAYS unit is not supportedjava.lang.ArithmeticException
- if numeric overflow occurspublic boolean equals(java.lang.Object otherAmount)
PeriodDuration
.
The comparison is based on the underlying period and duration.
equals
in class java.lang.Object
otherAmount
- the other amount, null returns falsepublic int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
Copyright © 2010–2018 ThreeTen.org. All rights reserved.