Class PeriodField
- java.lang.Object
-
- javax.time.calendar.PeriodField
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Comparable<PeriodField>
,PeriodProvider
public final class PeriodField extends java.lang.Object implements PeriodProvider, java.lang.Comparable<PeriodField>, java.io.Serializable
A period of time measured using a single unit, such as '3 Days' or '65 Seconds'.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 ofPeriodUnit
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:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description private long
amount
The amount of the period.private static long
serialVersionUID
The serialization version.private PeriodUnit
unit
The unit the period is measured in.
-
Constructor Summary
Constructors Modifier Constructor Description private
PeriodField(long amount, PeriodUnit unit)
Constructor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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(java.lang.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 anint
.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 aPeriodField
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 requiredUnit)
Converts this period to an equivalent in the specified unit.PeriodField
toEquivalent(PeriodUnit... requiredUnits)
Converts this period to an equivalent in one of the units specified.Duration
toEstimatedDuration()
Estimates the duration of this period.PeriodFields
toPeriodFields()
Converts this period to aPeriodFields
.java.lang.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.
-
-
-
Field Detail
-
serialVersionUID
private static final long serialVersionUID
The serialization version.- See Also:
- Constant Field Values
-
amount
private final long amount
The amount of the period.
-
unit
private final PeriodUnit unit
The unit the period is measured in.
-
-
Constructor Detail
-
PeriodField
private PeriodField(long amount, PeriodUnit unit)
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 Detail
-
of
public static PeriodField of(long amount, PeriodUnit unit)
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:
java.lang.ArithmeticException
- if the amount exceeds the capacity of anint
-
getUnit
public PeriodUnit 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
public PeriodField withAmount(long amount)
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
public PeriodField withUnit(PeriodUnit unit)
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
public PeriodField plus(PeriodField period)
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 - Throws:
IllegalArgumetException
- if the specified period has a different unitjava.lang.ArithmeticException
- if the calculation overflows
-
plus
public PeriodField plus(long amount)
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:
java.lang.ArithmeticException
- if the calculation overflows
-
minus
public PeriodField minus(PeriodField period)
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 - Throws:
IllegalArgumetException
- if the specified has a different unitjava.lang.ArithmeticException
- if the calculation overflows
-
minus
public PeriodField minus(long amount)
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:
java.lang.ArithmeticException
- if the calculation overflows
-
multipliedBy
public PeriodField multipliedBy(long scalar)
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:
java.lang.ArithmeticException
- if the calculation overflows
-
dividedBy
public PeriodField dividedBy(long divisor)
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:
java.lang.ArithmeticException
- if the divisor is zero
-
remainder
public PeriodField remainder(long divisor)
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:
java.lang.ArithmeticException
- if the divisor is zero
-
negated
public PeriodField 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:
java.lang.ArithmeticException
- if the amount isLong.MIN_VALUE
-
abs
public PeriodField 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:
java.lang.ArithmeticException
- if the amount isLong.MIN_VALUE
-
toEquivalent
public PeriodField toEquivalent(PeriodUnit requiredUnit)
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 unitjava.lang.ArithmeticException
- if the calculation overflows
-
toEquivalent
public PeriodField toEquivalent(PeriodUnit... requiredUnits)
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 unitsjava.lang.ArithmeticException
- if the calculation overflows
-
toEstimatedDuration
public Duration 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:
java.lang.ArithmeticException
- if the calculation overflows
-
toDuration
public Duration 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:
java.lang.ArithmeticException
- if the calculation overflows
-
toPeriodFields
public PeriodFields 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
public int compareTo(PeriodField otherPeriod)
Compares this period to the specified period.The comparison orders first by the unit, then by the amount.
- Specified by:
compareTo
in interfacejava.lang.Comparable<PeriodField>
- Parameters:
otherPeriod
- the other period to compare to, not null- Returns:
- the comparator value, negative if less, positive if greater
-
equals
public boolean equals(java.lang.Object obj)
Checks if this period is equal to the specified period.The comparison is based on the unit and amount.
- Overrides:
equals
in classjava.lang.Object
- Parameters:
obj
- the object to check, null returns false- Returns:
- true if this period is the same as that specified
-
hashCode
public int hashCode()
Returns the hash code for this period.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- a suitable hash code
-
toString
public java.lang.String 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.
- Overrides:
toString
in classjava.lang.Object
- Returns:
- a descriptive representation of this period, not null
-
-