Class 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 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:
    Serialized Form
    • 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 negative
        unit - the unit that the period is measured in, validated not null
    • Method Detail

      • 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:
        java.lang.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
        Throws:
        IllegalArgumetException - if the specified period has a different unit
        java.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 unit
        java.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 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:
        java.lang.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
        java.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 units
        java.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 the accurate 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 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 java.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 class java.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 class java.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 class java.lang.Object
        Returns:
        a descriptive representation of this period, not null