Class Hours

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Hours>, java.time.temporal.TemporalAmount

    public final class Hours
    extends java.lang.Object
    implements java.time.temporal.TemporalAmount, java.lang.Comparable<Hours>, java.io.Serializable
    A hour-based amount of time, such as '4 hours'.

    This class models a quantity or amount of time in terms of hours. It is a type-safe way of representing a number of hours in an application.

    The model is of a directed amount, meaning that the amount may be negative.

    Implementation Requirements:

    This class is immutable and thread-safe.

    This class must be treated as a value type. Do not synchronize, rely on the identity hash code or use the distinction between equals() and ==.

    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Hours ZERO
      A constant for zero hours.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      Hours abs()
      Returns a copy of this duration with a positive length.
      java.time.temporal.Temporal addTo​(java.time.temporal.Temporal temporal)
      Adds this amount to the specified temporal object.
      static Hours between​(java.time.temporal.Temporal startInclusive, java.time.temporal.Temporal endExclusive)
      Obtains a Hours consisting of the number of hours between two temporals.
      int compareTo​(Hours otherAmount)
      Compares this amount to the specified Hours.
      Hours dividedBy​(int divisor)
      Returns an instance with the amount divided by the specified divisor.
      boolean equals​(java.lang.Object otherAmount)
      Checks if this amount is equal to the specified Hours.
      static Hours from​(java.time.temporal.TemporalAmount amount)
      Obtains an instance of Hours from a temporal amount.
      long get​(java.time.temporal.TemporalUnit unit)
      Gets the value of the requested unit.
      int getAmount()
      Gets the number of hours in this amount.
      java.util.List<java.time.temporal.TemporalUnit> getUnits()
      Gets the set of units supported by this amount.
      int hashCode()
      A hash code for this amount.
      Hours minus​(int hours)
      Returns a copy of this amount with the specified number of hours subtracted.
      Hours minus​(java.time.temporal.TemporalAmount amountToAdd)
      Returns a copy of this amount with the specified amount subtracted.
      Hours multipliedBy​(int scalar)
      Returns an instance with the amount multiplied by the specified scalar.
      Hours negated()
      Returns an instance with the amount negated.
      static Hours of​(int hours)
      Obtains an Hours representing a number of hours.
      static Hours parse​(java.lang.CharSequence text)
      Obtains a Hours from a text string such as PTnH.
      Hours plus​(int hours)
      Returns a copy of this amount with the specified number of hours added.
      Hours plus​(java.time.temporal.TemporalAmount amountToAdd)
      Returns a copy of this amount with the specified amount added.
      java.time.temporal.Temporal subtractFrom​(java.time.temporal.Temporal temporal)
      Subtracts this amount from the specified temporal object.
      java.time.Duration toDuration()
      Gets the number of hours as a Duration.
      java.time.Duration toPeriod()
      Deprecated.
      java.lang.String toString()
      Returns a string representation of the number of hours.
      • Methods inherited from class java.lang.Object

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

      • ZERO

        public static final Hours ZERO
        A constant for zero hours.
    • Method Detail

      • of

        public static Hours of​(int hours)
        Obtains an Hours representing a number of hours.

        The resulting amount will have the specified hours.

        Parameters:
        hours - the number of hours, positive or negative
        Returns:
        the number of hours, not null
      • from

        public static Hours from​(java.time.temporal.TemporalAmount amount)
        Obtains an instance of Hours from a temporal amount.

        This obtains an instance based on the specified amount. A TemporalAmount represents an amount of time, which may be date-based or time-based, which this factory extracts to a Hours.

        The result is calculated by looping around each unit in the specified amount. Each amount is converted to hours using Temporals.convertAmount(long, java.time.temporal.TemporalUnit, java.time.temporal.TemporalUnit). If the conversion yields a remainder, an exception is thrown. If the amount is zero, the unit is ignored.

        Parameters:
        amount - the temporal amount to convert, not null
        Returns:
        the equivalent amount, not null
        Throws:
        java.time.DateTimeException - if unable to convert to a Hours
        java.lang.ArithmeticException - if numeric overflow occurs
      • parse

        public static Hours parse​(java.lang.CharSequence text)
        Obtains a Hours from a text string such as PTnH.

        This will parse the string produced by toString() and other related formats based on ISO-8601 PnDTnH.

        The string starts with an optional sign, denoted by the ASCII negative or positive symbol. If negative, the whole amount is negated. The ASCII letter "P" is next in upper or lower case. There are two sections consisting of a number and a suffix. There is one section for days suffixed by "D", followed by one section for hours suffixed by "H". At least one section must be present. If the hours section is present it must be prefixed by "T". If the hours section is omitted the "T" must be omitted. Letters must be in ASCII upper or lower case. The number part of each section must consist of ASCII digits. The number may be prefixed by the ASCII negative or positive symbol. The number must parse to an int.

        The leading plus/minus sign, and negative values for days and hours are not part of the ISO-8601 standard.

        For example, the following are valid inputs:

           "PT2H"            -- Hours.of(2)
           "PT-HM"           -- Hours.of(-2)
           "-PT2H"           -- Hours.of(-2)
           "-PT-2H"          -- Hours.of(2)
           "P3D"             -- Hours.of(3 * 24)
           "P3DT2H"          -- Hours.of(3 * 24 + 2)
         
        Parameters:
        text - the text to parse, not null
        Returns:
        the parsed period, not null
        Throws:
        java.time.format.DateTimeParseException - if the text cannot be parsed to a period
      • between

        public static Hours between​(java.time.temporal.Temporal startInclusive,
                                    java.time.temporal.Temporal endExclusive)
        Obtains a Hours consisting of the number of hours between two temporals.

        The start temporal is included, but the end temporal is not. The result of this method can be negative if the end is before the start.

        Parameters:
        startInclusive - the start temporal, inclusive, not null
        endExclusive - the end temporal, exclusive, not null
        Returns:
        the number of hours between the start and end temporals, not null
      • get

        public long get​(java.time.temporal.TemporalUnit unit)
        Gets the value of the requested unit.

        This returns a value for the supported unit - HOURS. All other units throw an exception.

        Specified by:
        get in interface java.time.temporal.TemporalAmount
        Parameters:
        unit - the TemporalUnit for which to return the value
        Returns:
        the long value of the unit
        Throws:
        java.time.temporal.UnsupportedTemporalTypeException - if the unit is not supported
      • getUnits

        public java.util.List<java.time.temporal.TemporalUnit> getUnits()
        Gets the set of units supported by this amount.

        The single supported unit is HOURS.

        This set can be used in conjunction with get(TemporalUnit) to access the entire state of the amount.

        Specified by:
        getUnits in interface java.time.temporal.TemporalAmount
        Returns:
        a list containing the hours unit, not null
      • getAmount

        public int getAmount()
        Gets the number of hours in this amount.
        Returns:
        the number of hours
      • plus

        public Hours plus​(java.time.temporal.TemporalAmount amountToAdd)
        Returns a copy of this amount with the specified amount added.

        The parameter is converted using from(TemporalAmount).

        This instance is immutable and unaffected by this method call.

        Parameters:
        amountToAdd - the amount to add, not null
        Returns:
        a Hours based on this instance with the requested amount added, not null
        Throws:
        java.time.DateTimeException - if the specified amount contains an invalid unit
        java.lang.ArithmeticException - if numeric overflow occurs
      • plus

        public Hours plus​(int hours)
        Returns a copy of this amount with the specified number of hours added.

        This instance is immutable and unaffected by this method call.

        Parameters:
        hours - the amount of hours to add, may be negative
        Returns:
        a Hours based on this instance with the requested amount added, not null
        Throws:
        java.lang.ArithmeticException - if the result overflows an int
      • minus

        public Hours minus​(java.time.temporal.TemporalAmount amountToAdd)
        Returns a copy of this amount with the specified amount subtracted.

        The parameter is converted using from(TemporalAmount).

        This instance is immutable and unaffected by this method call.

        Parameters:
        amountToAdd - the amount to add, not null
        Returns:
        a Hours based on this instance with the requested amount subtracted, not null
        Throws:
        java.time.DateTimeException - if the specified amount contains an invalid unit
        java.lang.ArithmeticException - if numeric overflow occurs
      • minus

        public Hours minus​(int hours)
        Returns a copy of this amount with the specified number of hours subtracted.

        This instance is immutable and unaffected by this method call.

        Parameters:
        hours - the amount of hours to add, may be negative
        Returns:
        a Hours based on this instance with the requested amount subtracted, not null
        Throws:
        java.lang.ArithmeticException - if the result overflows an int
      • multipliedBy

        public Hours multipliedBy​(int scalar)
        Returns an instance with the amount multiplied by the specified scalar.

        This instance is immutable and unaffected by this method call.

        Parameters:
        scalar - the scalar to multiply by, not null
        Returns:
        the amount multiplied by the specified scalar, not null
        Throws:
        java.lang.ArithmeticException - if numeric overflow occurs
      • dividedBy

        public Hours dividedBy​(int divisor)
        Returns an instance with the amount divided by the specified divisor.

        The calculation uses integer division, thus 3 divided by 2 is 1.

        This instance is immutable and unaffected by this method call.

        Parameters:
        divisor - the amount to divide by, may be negative
        Returns:
        the amount divided by the specified divisor, not null
        Throws:
        java.lang.ArithmeticException - if the divisor is zero
      • negated

        public Hours negated()
        Returns an instance with the amount negated.

        This instance is immutable and unaffected by this method call.

        Returns:
        the negated amount, not null
        Throws:
        java.lang.ArithmeticException - if numeric overflow occurs, which only happens if the amount is Long.MIN_VALUE
      • abs

        public Hours abs()
        Returns a copy of this duration with a positive length.

        This method returns a positive duration by effectively removing the sign from any negative total length.

        This instance is immutable and unaffected by this method call.

        Returns:
        the absolute amount, not null
        Throws:
        java.lang.ArithmeticException - if numeric overflow occurs, which only happens if the amount is Long.MIN_VALUE
      • toPeriod

        @Deprecated
        public java.time.Duration toPeriod()
        Deprecated.
        Gets the number of hours as a Duration.

        This returns a duration with the same number of hours.

        Returns:
        the equivalent duration, not null
      • toDuration

        public java.time.Duration toDuration()
        Gets the number of hours as a Duration.

        This returns a duration with the same number of hours.

        Returns:
        the equivalent duration, not null
      • addTo

        public java.time.temporal.Temporal addTo​(java.time.temporal.Temporal temporal)
        Adds this amount to the specified temporal object.

        This returns a temporal object of the same observable type as the input with this amount added.

        In most cases, it is clearer to reverse the calling pattern by using Temporal.plus(TemporalAmount).

           // these two lines are equivalent, but the second approach is recommended
           dateTime = thisAmount.addTo(dateTime);
           dateTime = dateTime.plus(thisAmount);
         

        Only non-zero amounts will be added.

        This instance is immutable and unaffected by this method call.

        Specified by:
        addTo in interface java.time.temporal.TemporalAmount
        Parameters:
        temporal - the temporal object to adjust, not null
        Returns:
        an object of the same type with the adjustment made, not null
        Throws:
        java.time.DateTimeException - if unable to add
        java.time.temporal.UnsupportedTemporalTypeException - if the HOURS unit is not supported
        java.lang.ArithmeticException - if numeric overflow occurs
      • subtractFrom

        public java.time.temporal.Temporal subtractFrom​(java.time.temporal.Temporal temporal)
        Subtracts this amount from the specified temporal object.

        This returns a temporal object of the same observable type as the input with this amount subtracted.

        In most cases, it is clearer to reverse the calling pattern by using Temporal.minus(TemporalAmount).

           // these two lines are equivalent, but the second approach is recommended
           dateTime = thisAmount.subtractFrom(dateTime);
           dateTime = dateTime.minus(thisAmount);
         

        Only non-zero amounts will be subtracted.

        This instance is immutable and unaffected by this method call.

        Specified by:
        subtractFrom in interface java.time.temporal.TemporalAmount
        Parameters:
        temporal - the temporal object to adjust, not null
        Returns:
        an object of the same type with the adjustment made, not null
        Throws:
        java.time.DateTimeException - if unable to subtract
        java.time.temporal.UnsupportedTemporalTypeException - if the HOURS unit is not supported
        java.lang.ArithmeticException - if numeric overflow occurs
      • compareTo

        public int compareTo​(Hours otherAmount)
        Compares this amount to the specified Hours.

        The comparison is based on the total length of the amounts. It is "consistent with equals", as defined by Comparable.

        Specified by:
        compareTo in interface java.lang.Comparable<Hours>
        Parameters:
        otherAmount - the other amount, not null
        Returns:
        the comparator value, negative if less, positive if greater
      • equals

        public boolean equals​(java.lang.Object otherAmount)
        Checks if this amount is equal to the specified Hours.

        The comparison is based on the total length of the durations.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        otherAmount - the other amount, null returns false
        Returns:
        true if the other amount is equal to this one
      • hashCode

        public int hashCode()
        A hash code for this amount.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a suitable hash code
      • toString

        public java.lang.String toString()
        Returns a string representation of the number of hours. This will be in the format 'PTnH' where n is the number of hours.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the number of hours in ISO-8601 string format