Class PeriodField
- All Implemented Interfaces:
Serializable
,Comparable<PeriodField>
,PeriodProvider
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.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final long
The amount of the period.private static final long
The serialization version.private final PeriodUnit
The unit the period is measured in. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabs()
Returns a copy of this period with a positive amount.int
compareTo
(PeriodField otherPeriod) Compares this period to the specified period.dividedBy
(long divisor) Returns a copy of this period with the amount divided by the specified divisor.boolean
Checks if this period is equal to the specified period.long
Gets the amount of this period.int
Gets the amount of this period, converted to anint
.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.minus
(long amount) Returns a copy of this period with the specified period subtracted.minus
(PeriodField period) Returns a copy of this period with the specified period subtracted.multipliedBy
(long scalar) Returns a copy of this period with the amount multiplied by the specified scalar.negated()
Returns a copy of this period with the amount negated.static PeriodField
of
(long amount, PeriodUnit unit) Obtains aPeriodField
from an amount and unit.plus
(long amount) Returns a copy of this period with the specified period added.plus
(PeriodField period) Returns a copy of this period with the specified period added.remainder
(long divisor) Returns a copy of this period with the amount as the remainder following division by the specified divisor.Calculates the accurate duration of this period.toEquivalent
(PeriodUnit requiredUnit) Converts this period to an equivalent in the specified unit.toEquivalent
(PeriodUnit... requiredUnits) Converts this period to an equivalent in one of the units specified.Estimates the duration of this period.Converts this period to aPeriodFields
.toString()
Returns a string representation of this period, such as '6 Days'.withAmount
(long amount) Returns a copy of this period with a different amount of time.withUnit
(PeriodUnit unit) Returns a copy of this period with a different unit.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDThe serialization version.- See Also:
-
amount
private final long amountThe amount of the period. -
unit
The unit the period is measured in.
-
-
Constructor Details
-
PeriodField
Constructor.- Parameters:
amount
- the amount of the period, measured in terms of the unit, positive or negativeunit
- the unit that the period is measured in, validated not null
-
-
Method Details
-
of
Obtains aPeriodField
from an amount and unit.The parameters represent the two parts of a phrase like '6 Days'.
- Parameters:
amount
- the amount of the period, measured in terms of the unit, positive or negativeunit
- the unit that the period is measured in, not null- Returns:
- the
PeriodField
instance, never null
-
isZero
public boolean isZero()Checks if this period is zero length.A
PeriodField
can be positive, zero or negative. This method checks whether the length is zero.- Returns:
- true if this period is zero length
-
getAmount
public long getAmount()Gets the amount of this period.For example, in the period '5 Days', the amount is '5'.
- Returns:
- the amount of time of this period, positive or negative
-
getAmountInt
public int getAmountInt()Gets the amount of this period, converted to anint
.For example, in the period '5 Days', the amount is '5'.
- Returns:
- the amount of time of this period, positive or negative
- Throws:
ArithmeticException
- if the amount exceeds the capacity of anint
-
getUnit
Gets the unit of this period.For example, in the period '5 Days', the unit is 'Days'.
- Returns:
- the period unit, never null
-
withAmount
Returns a copy of this period with a different amount of time.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'.
- Parameters:
amount
- the amount of time to set in the returned period, positive or negative- Returns:
- a
PeriodField
based on this period with the specified amount, never null
-
withUnit
Returns a copy of this period with a different 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'.
- Parameters:
unit
- the unit to set in the returned period, positive or negative- Returns:
- a
PeriodField
based on this period with the specified unit, never null
-
plus
Returns a copy of this period with the specified period added.This instance is immutable and unaffected by this method call.
- Parameters:
period
- the period to add, positive or negative- Returns:
- a
PeriodField
based on this period with the specified period added, never null
-
plus
Returns a copy of this period with the specified period added.This instance is immutable and unaffected by this method call.
- Parameters:
amount
- the period to add, measured in the unit of the period, positive or negative- Returns:
- a
PeriodField
based on this period with the specified amount added, never null - Throws:
ArithmeticException
- if the calculation overflows
-
minus
Returns a copy of this period with the specified period subtracted.This instance is immutable and unaffected by this method call.
- Parameters:
period
- the period to subtract, positive or negative- Returns:
- a
PeriodField
based on this period with the specified period subtracted, never null
-
minus
Returns a copy of this period with the specified period subtracted.This instance is immutable and unaffected by this method call.
- Parameters:
amount
- the period to subtract, measured in the unit of the period, positive or negative- Returns:
- a
PeriodField
based on this period with the specified amount subtracted, never null - Throws:
ArithmeticException
- if the calculation overflows
-
multipliedBy
Returns a copy of this period with the amount multiplied by the specified scalar.This instance is immutable and unaffected by this method call.
- Parameters:
scalar
- the value to multiply by, positive or negative- Returns:
- a
PeriodField
based on this period multiplied by the specified scalar, never null - Throws:
ArithmeticException
- if the calculation overflows
-
dividedBy
Returns a copy of this period with the amount divided by the specified 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.
- Parameters:
divisor
- the value to divide by, positive or negative- Returns:
- a
PeriodField
based on this period divided by the specified divisor, never null - Throws:
ArithmeticException
- if the divisor is zero
-
remainder
Returns a copy of this period with the amount as the remainder following division by the specified 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.
- Parameters:
divisor
- the value to divide by, positive or negative- Returns:
- a
PeriodField
based on this period divided by the specified divisor, never null - Throws:
ArithmeticException
- if the divisor is zero
-
negated
Returns a copy of this period with the amount negated.This instance is immutable and unaffected by this method call.
- Returns:
- a
PeriodField
based on this period with the amount negated, never null - Throws:
ArithmeticException
- if the amount isLong.MIN_VALUE
-
abs
Returns a copy of this period with a positive amount.This instance is immutable and unaffected by this method call.
- Returns:
- a
PeriodField
based on this period with an absolute amount, never null - Throws:
ArithmeticException
- if the amount isLong.MIN_VALUE
-
toEquivalent
Converts this period to an equivalent in the specified unit.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.- Parameters:
requiredUnit
- the unit to convert to, not null- Returns:
- a period equivalent to this period, never null
- Throws:
CalendricalException
- if this period cannot be converted to the specified unitArithmeticException
- if the calculation overflows
-
toEquivalent
Converts this period to an equivalent in one of the units specified.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'.
- Parameters:
requiredUnits
- the required unit array, not altered, not null, no nulls- Returns:
- a period equivalent to this period, never null
- Throws:
CalendricalException
- if this period cannot be converted to any of the unitsArithmeticException
- if the calculation overflows
-
toEstimatedDuration
Estimates the duration of this period.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 theaccurate
calculation if the unit is based on the second.- Returns:
- the estimated duration of this period, positive or negative
- Throws:
ArithmeticException
- if the calculation overflows
-
toDuration
Calculates the accurate duration of this period.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.- Returns:
- the duration of this period based on
ISOChronology
fields, never null - Throws:
ArithmeticException
- if the calculation overflows
-
toPeriodFields
Converts this period to aPeriodFields
.The returned
PeriodFields
will always contain the unit even if the amount is zero.- Specified by:
toPeriodFields
in interfacePeriodProvider
- Returns:
- the equivalent period, never null
-
compareTo
Compares this period to the specified period.The comparison orders first by the unit, then by the amount.
- Specified by:
compareTo
in interfaceComparable<PeriodField>
- Parameters:
otherPeriod
- the other period to compare to, not null- Returns:
- the comparator value, negative if less, positive if greater
-
equals
Checks if this period is equal to the specified period.The comparison is based on the unit and amount.
-
hashCode
public int hashCode()Returns the hash code for this period. -
toString
Returns a string representation of this period, such as '6 Days'.The format consists of the amount, followed by a space, followed by the unit name.
-