Class Period


  • public final class Period
    extends java.lang.Object
    Represents an approximate duration in multiple TimeUnits. Each unit, if set, has a count (which can be fractional and must be non-negative). In addition Period can either represent the duration as being into the past or future, and as being more or less than the defined value.

    Use a PeriodFormatter to convert a Period to a String.

    Periods are immutable. Mutating operations return the new result leaving the original unchanged.

    Example:

     Period p1 = Period.at(3, WEEK).and(2, DAY).inFuture();
     Period p2 = p1.and(12, HOUR);
    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) int[] counts  
      (package private) boolean inFuture  
      (package private) byte timeLimit  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Period​(int limit, boolean future, float count, TimeUnit unit)
      Private constructor used by static factory methods.
      (package private) Period​(int timeLimit, boolean inFuture, int[] counts)
      Package private constructor used by setters and factory.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Period and​(float count, TimeUnit unit)
      Set the given unit to have the given count.
      Period at()
      Mark the duration as being at the defined duration.
      static Period at​(float count, TimeUnit unit)
      Constructs a Period representing a duration of count units extending into the past.
      private static void checkCount​(float count)
      Validate count.
      boolean equals​(Period rhs)
      Returns true if the same units are defined with the same counts, both extend into the future or both into the past, and if the limits (at, more than, less than) are the same.
      boolean equals​(java.lang.Object rhs)
      Returns true if rhs extends Period and the two Periods are equal.
      float getCount​(TimeUnit unit)
      Returns the count for the specified unit.
      int hashCode()
      Returns the hashCode.
      Period inFuture()
      Mark the time as being in the future.
      Period inFuture​(boolean future)
      Mark the duration as extending into the future if future is true, and into the past otherwise.
      Period inPast()
      Mark the duration as extending into the past.
      Period inPast​(boolean past)
      Mark the duration as extending into the past if past is true, and into the future otherwise.
      boolean isInFuture()
      Returns true if this represents a duration into the future.
      boolean isInPast()
      Returns true if this represents a duration into the past
      boolean isLessThan()
      Returns true if this represents a duration less than the defined duration.
      boolean isMoreThan()
      Returns true if this represents a duration in excess of the defined duration.
      boolean isSet()
      Returns true if any unit is set.
      boolean isSet​(TimeUnit unit)
      Returns true if the given unit is set.
      Period lessThan()
      Mark the duration as being less than the defined duration.
      static Period lessThan​(float count, TimeUnit unit)
      Constructs a Period representing a duration less than count units extending into the past.
      Period moreThan()
      Mark the duration as being more than the defined duration.
      static Period moreThan​(float count, TimeUnit unit)
      Constructs a Period representing a duration more than count units extending into the past.
      Period omit​(TimeUnit unit)
      Mark the given unit as not being set.
      private Period setFuture​(boolean future)
      Sets whether this defines a future time.
      private Period setTimeLimit​(byte limit)
      Sets whether this is more than, less than, or 'about' the specified time.
      private Period setTimeUnitInternalValue​(TimeUnit unit, int value)
      Sets the period to have the provided value, 1/1000 of the unit plus 1.
      private Period setTimeUnitValue​(TimeUnit unit, float value)
      Set the unit's internal value, converting from float to int.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • timeLimit

        final byte timeLimit
      • inFuture

        final boolean inFuture
      • counts

        final int[] counts
    • Constructor Detail

      • Period

        private Period​(int limit,
                       boolean future,
                       float count,
                       TimeUnit unit)
        Private constructor used by static factory methods.
      • Period

        Period​(int timeLimit,
               boolean inFuture,
               int[] counts)
        Package private constructor used by setters and factory.
    • Method Detail

      • at

        public static Period at​(float count,
                                TimeUnit unit)
        Constructs a Period representing a duration of count units extending into the past.
        Parameters:
        count - the number of units, must be non-negative
        unit - the unit
        Returns:
        the new Period
      • moreThan

        public static Period moreThan​(float count,
                                      TimeUnit unit)
        Constructs a Period representing a duration more than count units extending into the past.
        Parameters:
        count - the number of units. must be non-negative
        unit - the unit
        Returns:
        the new Period
      • lessThan

        public static Period lessThan​(float count,
                                      TimeUnit unit)
        Constructs a Period representing a duration less than count units extending into the past.
        Parameters:
        count - the number of units. must be non-negative
        unit - the unit
        Returns:
        the new Period
      • and

        public Period and​(float count,
                          TimeUnit unit)
        Set the given unit to have the given count. Marks the unit as having been set. This can be used to set multiple units, or to reset a unit to have a new count. This does not add the count to an existing count for this unit.
        Parameters:
        count - the number of units. must be non-negative
        unit - the unit
        Returns:
        the new Period
      • omit

        public Period omit​(TimeUnit unit)
        Mark the given unit as not being set.
        Parameters:
        unit - the unit to unset
        Returns:
        the new Period
      • at

        public Period at()
        Mark the duration as being at the defined duration.
        Returns:
        the new Period
      • moreThan

        public Period moreThan()
        Mark the duration as being more than the defined duration.
        Returns:
        the new Period
      • lessThan

        public Period lessThan()
        Mark the duration as being less than the defined duration.
        Returns:
        the new Period
      • inFuture

        public Period inFuture()
        Mark the time as being in the future.
        Returns:
        the new Period
      • inPast

        public Period inPast()
        Mark the duration as extending into the past.
        Returns:
        the new Period
      • inFuture

        public Period inFuture​(boolean future)
        Mark the duration as extending into the future if future is true, and into the past otherwise.
        Parameters:
        future - true if the time is in the future
        Returns:
        the new Period
      • inPast

        public Period inPast​(boolean past)
        Mark the duration as extending into the past if past is true, and into the future otherwise.
        Parameters:
        past - true if the time is in the past
        Returns:
        the new Period
      • isSet

        public boolean isSet()
        Returns true if any unit is set.
        Returns:
        true if any unit is set
      • isSet

        public boolean isSet​(TimeUnit unit)
        Returns true if the given unit is set.
        Parameters:
        unit - the unit to test
        Returns:
        true if the given unit is set.
      • getCount

        public float getCount​(TimeUnit unit)
        Returns the count for the specified unit. If the unit is not set, returns 0.
        Parameters:
        unit - the unit to test
        Returns:
        the count
      • isInFuture

        public boolean isInFuture()
        Returns true if this represents a duration into the future.
        Returns:
        true if this represents a duration into the future.
      • isInPast

        public boolean isInPast()
        Returns true if this represents a duration into the past
        Returns:
        true if this represents a duration into the past
      • isMoreThan

        public boolean isMoreThan()
        Returns true if this represents a duration in excess of the defined duration.
        Returns:
        true if this represents a duration in excess of the defined duration.
      • isLessThan

        public boolean isLessThan()
        Returns true if this represents a duration less than the defined duration.
        Returns:
        true if this represents a duration less than the defined duration.
      • equals

        public boolean equals​(java.lang.Object rhs)
        Returns true if rhs extends Period and the two Periods are equal.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        rhs - the object to compare to
        Returns:
        true if rhs is a Period and is equal to this
      • equals

        public boolean equals​(Period rhs)
        Returns true if the same units are defined with the same counts, both extend into the future or both into the past, and if the limits (at, more than, less than) are the same. Note that this means that a period of 1000ms and a period of 1sec will not compare equal.
        Parameters:
        rhs - the period to compare to
        Returns:
        true if the two periods are equal
      • hashCode

        public int hashCode()
        Returns the hashCode.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hashCode
      • setTimeUnitValue

        private Period setTimeUnitValue​(TimeUnit unit,
                                        float value)
        Set the unit's internal value, converting from float to int.
      • setTimeUnitInternalValue

        private Period setTimeUnitInternalValue​(TimeUnit unit,
                                                int value)
        Sets the period to have the provided value, 1/1000 of the unit plus 1. Thus unset values are '0', 1' is the set value '0', 2 is the set value '1/1000', 3 is the set value '2/1000' etc.
        Parameters:
        p - the period to change
        value - the int value as described above.
      • setFuture

        private Period setFuture​(boolean future)
        Sets whether this defines a future time.
        Parameters:
        future - true if the time is in the future
        Returns:
        the new Period
      • setTimeLimit

        private Period setTimeLimit​(byte limit)
        Sets whether this is more than, less than, or 'about' the specified time.
        Parameters:
        limit - the kind of limit
        Returns:
        the new Period
      • checkCount

        private static void checkCount​(float count)
        Validate count.