public final class PeriodField extends Object implements PeriodProvider, Comparable<PeriodField>, Serializable
PeriodField
is an immutable period that stores an amount of human-scale
time for a single unit. For example, humans typically measure periods of time
in units of years, months, days, hours, minutes and seconds. These concepts are
defined by instances of PeriodUnit
in the chronology classes. This class
allows an amount to be specified for one of the units, such as '3 Days' or '65 Seconds'.
Basic mathematical operations are provided - plus(), minus(), multipliedBy(), dividedBy(), negated() and abs(), all of which return a new instance.
PeriodField
can store rules of any kind which makes it usable with
any calendar system.
PeriodField is immutable and thread-safe.
Modifier and Type | Method and Description |
---|---|
PeriodField |
abs()
Returns a copy of this period with a positive amount.
|
int |
compareTo(PeriodField otherPeriod)
Compares this period to the specified period.
|
PeriodField |
dividedBy(long divisor)
Returns a copy of this period with the amount divided by the specified divisor.
|
boolean |
equals(Object obj)
Checks if this period is equal to the specified period.
|
long |
getAmount()
Gets the amount of this period.
|
int |
getAmountInt()
Gets the amount of this period, converted to an
int . |
PeriodUnit |
getUnit()
Gets the unit of this period.
|
int |
hashCode()
Returns the hash code for this period.
|
boolean |
isZero()
Checks if this period is zero length.
|
PeriodField |
minus(long amount)
Returns a copy of this period with the specified period subtracted.
|
PeriodField |
minus(PeriodField period)
Returns a copy of this period with the specified period subtracted.
|
PeriodField |
multipliedBy(long scalar)
Returns a copy of this period with the amount multiplied by the specified scalar.
|
PeriodField |
negated()
Returns a copy of this period with the amount negated.
|
static PeriodField |
of(long amount,
PeriodUnit unit)
Obtains a
PeriodField from an amount and unit. |
PeriodField |
plus(long amount)
Returns a copy of this period with the specified period added.
|
PeriodField |
plus(PeriodField period)
Returns a copy of this period with the specified period added.
|
PeriodField |
remainder(long divisor)
Returns a copy of this period with the amount as the remainder following
division by the specified divisor.
|
Duration |
toDuration()
Calculates the accurate duration of this period.
|
PeriodField |
toEquivalent(PeriodUnit... requiredUnits)
Converts this period to an equivalent in one of the units specified.
|
PeriodField |
toEquivalent(PeriodUnit requiredUnit)
Converts this period to an equivalent in the specified unit.
|
Duration |
toEstimatedDuration()
Estimates the duration of this period.
|
PeriodFields |
toPeriodFields()
Converts this period to a
PeriodFields . |
String |
toString()
Returns a string representation of this period, such as '6 Days'.
|
PeriodField |
withAmount(long amount)
Returns a copy of this period with a different amount of time.
|
PeriodField |
withUnit(PeriodUnit unit)
Returns a copy of this period with a different unit.
|
public static PeriodField of(long amount, PeriodUnit unit)
PeriodField
from an amount and unit.
The parameters represent the two parts of a phrase like '6 Days'.
amount
- the amount of the period, measured in terms of the unit, positive or negativeunit
- the unit that the period is measured in, not nullPeriodField
instance, never nullpublic boolean isZero()
A PeriodField
can be positive, zero or negative.
This method checks whether the length is zero.
public long getAmount()
For example, in the period '5 Days', the amount is '5'.
public int getAmountInt()
int
.
For example, in the period '5 Days', the amount is '5'.
ArithmeticException
- if the amount exceeds the capacity of an int
public PeriodUnit getUnit()
For example, in the period '5 Days', the unit is 'Days'.
public PeriodField withAmount(long amount)
Calling this method returns a new period with the same unit but different amount. For example, it could be used to change '3 Days' to '5 Days'.
amount
- the amount of time to set in the returned period, positive or negativePeriodField
based on this period with the specified amount, never nullpublic PeriodField withUnit(PeriodUnit unit)
Calling this method returns a new period with the same amount but different unit. For example, it could be used to change '3 Days' to '3 Months'.
unit
- the unit to set in the returned period, positive or negativePeriodField
based on this period with the specified unit, never nullpublic PeriodField plus(PeriodField period)
This instance is immutable and unaffected by this method call.
period
- the period to add, positive or negativePeriodField
based on this period with the specified period added, never nullIllegalArgumetException
- if the specified period has a different unitArithmeticException
- if the calculation overflowspublic PeriodField plus(long amount)
This instance is immutable and unaffected by this method call.
amount
- the period to add, measured in the unit of the period, positive or negativePeriodField
based on this period with the specified amount added, never nullArithmeticException
- if the calculation overflowspublic PeriodField minus(PeriodField period)
This instance is immutable and unaffected by this method call.
period
- the period to subtract, positive or negativePeriodField
based on this period with the specified period subtracted, never nullIllegalArgumetException
- if the specified has a different unitArithmeticException
- if the calculation overflowspublic PeriodField minus(long amount)
This instance is immutable and unaffected by this method call.
amount
- the period to subtract, measured in the unit of the period, positive or negativePeriodField
based on this period with the specified amount subtracted, never nullArithmeticException
- if the calculation overflowspublic PeriodField multipliedBy(long scalar)
This instance is immutable and unaffected by this method call.
scalar
- the value to multiply by, positive or negativePeriodField
based on this period multiplied by the specified scalar, never nullArithmeticException
- if the calculation overflowspublic PeriodField dividedBy(long divisor)
This uses the /
operator and integer division to provide the result.
For example, the result of '11 Days' divided by 4 is '2 Days'.
This instance is immutable and unaffected by this method call.
divisor
- the value to divide by, positive or negativePeriodField
based on this period divided by the specified divisor, never nullArithmeticException
- if the divisor is zeropublic PeriodField remainder(long divisor)
This uses the %
operator to provide the result, which may be negative.
For example, the remainder of '11 Days' divided by 4 is '3 Days'.
This instance is immutable and unaffected by this method call.
divisor
- the value to divide by, positive or negativePeriodField
based on this period divided by the specified divisor, never nullArithmeticException
- if the divisor is zeropublic PeriodField negated()
This instance is immutable and unaffected by this method call.
PeriodField
based on this period with the amount negated, never nullArithmeticException
- if the amount is Long.MIN_VALUE
public PeriodField abs()
This instance is immutable and unaffected by this method call.
PeriodField
based on this period with an absolute amount, never nullArithmeticException
- if the amount is Long.MIN_VALUE
public PeriodField toEquivalent(PeriodUnit requiredUnit)
This converts this period to one measured in the specified unit.
This uses PeriodUnit.getEquivalentPeriod(PeriodUnit)
to lookup
the equivalent period for the unit.
For example, '3 Hours' could be converted to '180 Minutes'.
This method is equivalent to toEquivalent(PeriodUnit...)
with a single parameter.
requiredUnit
- the unit to convert to, not nullCalendricalException
- if this period cannot be converted to the specified unitArithmeticException
- if the calculation overflowspublic PeriodField toEquivalent(PeriodUnit... requiredUnits)
This converts this period to one measured in one of the specified units. It operates by trying to convert to each unit in turn until one succeeds. As such, it is recommended to specify the units from largest to smallest.
For example, '3 Hours' can normally be converted to both minutes and seconds. If the units array contains both 'Minutes' and 'Seconds', then the result will be measured in whichever is first in the array, either '180 Minutes' or '10800 Seconds'.
requiredUnits
- the required unit array, not altered, not null, no nullsCalendricalException
- if this period cannot be converted to any of the unitsArithmeticException
- if the calculation overflowspublic Duration toEstimatedDuration()
The PeriodUnit
contains an estimated duration for that unit.
The value allows an estimate to be calculated for this period irrespective
of whether the unit is of fixed or variable duration. The estimate will equal the
accurate
calculation if the unit is based on the second.
ArithmeticException
- if the calculation overflowspublic Duration toDuration()
The conversion is based on the ISOChronology
definition of the seconds and
nanoseconds units. If the unit of this period can be converted to either seconds
or nanoseconds then the conversion will succeed, subject to calculation overflow.
If the unit cannot be converted then an exception is thrown.
ISOChronology
fields, never nullArithmeticException
- if the calculation overflowspublic PeriodFields toPeriodFields()
PeriodFields
.
The returned PeriodFields
will always contain the unit even
if the amount is zero.
toPeriodFields
in interface PeriodProvider
public int compareTo(PeriodField otherPeriod)
The comparison orders first by the unit, then by the amount.
compareTo
in interface Comparable<PeriodField>
otherPeriod
- the other period to compare to, not nullpublic boolean equals(Object obj)
The comparison is based on the unit and amount.
public int hashCode()
Copyright © 2014. All rights reserved.