Class PeriodField

java.lang.Object
javax.time.calendar.PeriodField
All Implemented Interfaces:
Serializable, Comparable<PeriodField>, PeriodProvider
public final class PeriodField extends Object implements PeriodProvider, Comparable<PeriodField>, 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 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 Details

    • serialVersionUID

      private static final long serialVersionUID
      The serialization version.
      See Also:

    • amount

      private final long amount
      The amount of the period.

    • unit

      private final PeriodUnit unit
      The unit the period is measured in.

  • Constructor Details

    • PeriodField

      private PeriodField(long amount, PeriodUnit unit)
      Constructor.
      Parameters:
      amount - the amount of the period, measured in terms of the unit, positive or negative
      unit - the unit that the period is measured in, validated not null

  • Method Details

    • of

      public static PeriodField of(long amount, PeriodUnit unit)
      Obtains a PeriodField 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 negative
      unit - 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 an int.

      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 an int

    • 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

    • 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:
      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

    • 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:
      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:
      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:
      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:
      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:
      ArithmeticException - if the amount is Long.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:
      ArithmeticException - if the amount is Long.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 unit
      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 units
      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 the accurate 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

      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:
      ArithmeticException - if the calculation overflows

    • toPeriodFields

      public PeriodFields toPeriodFields()
      Converts this period to a PeriodFields.

      The returned PeriodFields will always contain the unit even if the amount is zero.

      Specified by:
      toPeriodFields in interface PeriodProvider
      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 interface 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(Object obj)
      Checks if this period is equal to the specified period.

      The comparison is based on the unit and amount.

      Overrides:
      equals in class 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 class Object
      Returns:
      a suitable hash code

    • toString

      public 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 class Object
      Returns:
      a descriptive representation of this period, not null