public final class SimplePeriod extends java.lang.Object implements TemporalAdder, TemporalSubtractor, java.lang.Comparable<SimplePeriod>, java.io.Serializable
A SimplePeriod
represents an amount of time measured in terms of a
single unit
. Any unit may be used with this class.
An alternative period implementation is Period
, which
allows a combination of date and time units.
This class is the return type from TemporalUnit.between(R, R)
.
It can be used more generally, but is designed to enable the following code:
date = date.minus(MONTHS.between(start, end));The unit determines which calendar systems it can be added to.
The period is modeled as a directed amount of time, meaning that the period may
be negative. See abs()
to ensure the period is positive.
Modifier and Type | Method and Description |
---|---|
SimplePeriod |
abs()
Returns a copy of this period with a positive amount.
|
Temporal |
addTo(Temporal temporal)
Adds this period to the specified temporal object.
|
int |
compareTo(SimplePeriod other)
Compares this
SimplePeriod to another period. |
boolean |
equals(java.lang.Object obj)
Checks if this period is equal to another period.
|
long |
getAmount()
Gets the amount of this period.
|
TemporalUnit |
getUnit()
Gets the unit of this period.
|
int |
hashCode()
A hash code for this period.
|
static SimplePeriod |
of(long amount,
TemporalUnit unit)
Obtains an instance of
SimplePeriod from a period in the specified unit. |
Temporal |
subtractFrom(Temporal temporal)
Subtracts this period to the specified temporal object.
|
java.lang.String |
toString()
Outputs this period as a
String , such as 2 Months . |
public static SimplePeriod of(long amount, TemporalUnit unit)
SimplePeriod
from a period in the specified unit.
The parameters represent the two parts of a phrase like '6 Days'. For example:
SimplePeriod.of(3, SECONDS); SimplePeriod.of(5, YEARS);
amount
- the amount of the period, measured in terms of the unit, positive or negativeunit
- the unit that the period is measured in, not nullpublic long getAmount()
In the phrase "2 Months", the amount is 2.
public TemporalUnit getUnit()
In the phrase "2 Months", the unit is "Months".
public Temporal addTo(Temporal temporal)
This returns a temporal object of the same observable type as the input with this period added.
In most cases, it is clearer to reverse the calling pattern by using
Temporal.plus(TemporalAdder)
.
// these two lines are equivalent, but the second approach is recommended dateTime = thisPeriod.addTo(dateTime); dateTime = dateTime.plus(thisPeriod);
The calculation is equivalent to invoking Temporal.plus(long, TemporalUnit)
.
This instance is immutable and unaffected by this method call.
addTo
in interface TemporalAdder
temporal
- the temporal object to adjust, not nullDateTimeException
- if unable to addjava.lang.ArithmeticException
- if numeric overflow occurspublic Temporal subtractFrom(Temporal temporal)
This returns a temporal object of the same observable type as the input with this period subtracted.
In most cases, it is clearer to reverse the calling pattern by using
Temporal.plus(TemporalAdder)
.
// these two lines are equivalent, but the second approach is recommended dateTime = thisPeriod.subtractFrom(dateTime); dateTime = dateTime.minus(thisPeriod);
The calculation is equivalent to invoking Temporal.minus(long, TemporalUnit)
.
This instance is immutable and unaffected by this method call.
subtractFrom
in interface TemporalSubtractor
temporal
- the temporal object to adjust, not nullDateTimeException
- if unable to subtractjava.lang.ArithmeticException
- if numeric overflow occurspublic SimplePeriod abs()
This returns a period with the absolute value of the amount and the same unit.
If the amount of this period is positive or zero, then this period is returned.
If the amount of this period is negative, then a period with the negated
amount is returned. If the amount equals Long.MIN_VALUE
,
an ArithmeticException
is thrown
This is useful to convert the result of TemporalUnit.between(R, R)
to
a positive amount when you do not know which date is the earlier and
which is the later.
java.lang.ArithmeticException
- if the amount is Long.MIN_VALUE
public int compareTo(SimplePeriod other)
SimplePeriod
to another period.
The comparison is based on the amount within the unit. Only two periods with the same unit can be compared.
compareTo
in interface java.lang.Comparable<SimplePeriod>
other
- the other period to compare to, not nulljava.lang.IllegalArgumentException
- if the units do not matchpublic boolean equals(java.lang.Object obj)
The comparison is based on the amount and unit.
equals
in class java.lang.Object
obj
- the object to check, null returns falseObject.hashCode()
,
HashMap
public int hashCode()
hashCode
in class java.lang.Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public java.lang.String toString()
String
, such as 2 Months
.
The string consists of the amount, then a space, then the unit name.
toString
in class java.lang.Object