Package org.threeten.extra

Class Days

java.lang.Object
org.threeten.extra.Days
All Implemented Interfaces:
Serializable, Comparable<Days>, TemporalAmount
public final class Days extends Object implements TemporalAmount, Comparable<Days>, Serializable
A day-based amount of time, such as '12 days'.

This class models a quantity or amount of time in terms of days. It is a type-safe way of representing a number of days 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:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Days
    ONE
    A constant for one day.
    static final Days
    ZERO
    A constant for zero days.

  • Method Summary

    Modifier and Type
    Method
    Description
    Days
    abs()
    Returns a copy of this duration with a positive length.
    Temporal
    addTo(Temporal temporal)
    Adds this amount to the specified temporal object.
    static Days
    between(Temporal startDateInclusive, Temporal endDateExclusive)
    Obtains a Days consisting of the number of days between two dates.
    int
    compareTo(Days otherAmount)
    Compares this amount to the specified Days.
    Days
    dividedBy(int divisor)
    Returns an instance with the amount divided by the specified divisor.
    boolean
    equals(@Nullable Object otherAmount)
    Checks if this amount is equal to the specified Days.
    static Days
    from(TemporalAmount amount)
    Obtains an instance of Days from a temporal amount.
    long
    get(TemporalUnit unit)
    Gets the value of the requested unit.
    int
    getAmount()
    Gets the number of days in this amount.
    List<TemporalUnit>
    getUnits()
    Gets the set of units supported by this amount.
    int
    hashCode()
    A hash code for this amount.
    boolean
    isNegative()
    Checks if the amount is negative.
    boolean
    isPositive()
    Checks if the amount is positive.
    boolean
    isZero()
    Checks if the amount is zero.
    Days
    minus(int days)
    Returns a copy of this amount with the specified number of days subtracted.
    Days
    minus(TemporalAmount amountToSubtract)
    Returns a copy of this amount with the specified amount subtracted.
    Days
    multipliedBy(int scalar)
    Returns an instance with the amount multiplied by the specified scalar.
    Days
    negated()
    Returns an instance with the amount negated.
    static Days
    of(int days)
    Obtains a Days representing a number of days.
    static Days
    ofWeeks(int weeks)
    Obtains a Days representing the number of days equivalent to a number of weeks.
    static Days
    parse(CharSequence text)
    Obtains a Days from a text string such as PnD.
    Days
    plus(int days)
    Returns a copy of this amount with the specified number of days added.
    Days
    plus(TemporalAmount amountToAdd)
    Returns a copy of this amount with the specified amount added.
    Temporal
    subtractFrom(Temporal temporal)
    Subtracts this amount from the specified temporal object.
    Period
    toPeriod()
    Gets the number of days as a Period.
    String
    toString()
    Returns a string representation of the number of days.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • ZERO

      public static final Days ZERO
      A constant for zero days.

    • ONE

      public static final Days ONE
      A constant for one day.

  • Method Details

    • of

      public static Days of(int days)
      Obtains a Days representing a number of days.

      The resulting amount will have the specified days.

      Parameters:
      days - the number of days, positive or negative
      Returns:
      the number of days, not null

    • ofWeeks

      public static Days ofWeeks(int weeks)
      Obtains a Days representing the number of days equivalent to a number of weeks.

      The resulting amount will be day-based, with the number of days equal to the number of weeks multiplied by 7.

      Parameters:
      weeks - the number of weeks, positive or negative
      Returns:
      the amount with the input weeks converted to days, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • from

      public static Days from(TemporalAmount amount)
      Obtains an instance of Days 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 Days.

      The result is calculated by looping around each unit in the specified amount. Each amount is converted to days 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:
      DateTimeException - if unable to convert to a Days
      ArithmeticException - if numeric overflow occurs

    • parse

      public static Days parse(CharSequence text)
      Obtains a Days from a text string such as PnD.

      This will parse the string produced by toString() which is based on the ISO-8601 period formats PnD and PnW.

      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 then two sections, each consisting of a number and a suffix. At least one of the two sections must be present. The sections have suffixes in ASCII of "W" and "D" for weeks and days, accepted in upper or lower case. The suffixes must occur in order. 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 weeks and days are not part of the ISO-8601 standard.

      For example, the following are valid inputs: 

         "P2D"             -- Days.of(2)
   "P-2D"            -- Days.of(-2)
   "-P2D"            -- Days.of(-2)
   "-P-2D"           -- Days.of(2)
   "P3W"             -- Days.of(3 * 7)
   "P3W-2D"          -- Days.of(3 * 7 - 2)
      Parameters:
      text - the text to parse, not null
      Returns:
      the parsed period, not null
      Throws:
      DateTimeParseException - if the text cannot be parsed to a period

    • between

      public static Days between(Temporal startDateInclusive, Temporal endDateExclusive)
      Obtains a Days consisting of the number of days between two dates.

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

      Parameters:
      startDateInclusive - the start date, inclusive, not null
      endDateExclusive - the end date, exclusive, not null
      Returns:
      the number of days between this date and the end date, not null

    • get

      public long get(TemporalUnit unit)
      Gets the value of the requested unit.

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

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

    • getUnits

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

      The single supported unit is DAYS.

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

      Specified by:
      getUnits in interface TemporalAmount
      Returns:
      a list containing the days unit, not null

    • getAmount

      public int getAmount()
      Gets the number of days in this amount.
      Returns:
      the number of days

    • isNegative

      public boolean isNegative()
      Checks if the amount is negative.
      Returns:
      true if the amount is negative, false if the amount is zero or positive

    • isZero

      public boolean isZero()
      Checks if the amount is zero.
      Returns:
      true if the amount is zero, false if not

    • isPositive

      public boolean isPositive()
      Checks if the amount is positive.
      Returns:
      true if the amount is positive, false if the amount is zero or negative

    • plus

      public Days plus(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 Days based on this instance with the requested amount added, not null
      Throws:
      DateTimeException - if the specified amount contains an invalid unit
      ArithmeticException - if numeric overflow occurs

    • plus

      public Days plus(int days)
      Returns a copy of this amount with the specified number of days added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      days - the amount of days to add, may be negative
      Returns:
      a Days based on this instance with the requested amount added, not null
      Throws:
      ArithmeticException - if the result overflows an int

    • minus

      public Days minus(TemporalAmount amountToSubtract)
      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:
      amountToSubtract - the amount to subtract, not null
      Returns:
      a Days based on this instance with the requested amount subtracted, not null
      Throws:
      DateTimeException - if the specified amount contains an invalid unit
      ArithmeticException - if numeric overflow occurs

    • minus

      public Days minus(int days)
      Returns a copy of this amount with the specified number of days subtracted.

      This instance is immutable and unaffected by this method call.

      Parameters:
      days - the amount of days to add, may be negative
      Returns:
      a Days based on this instance with the requested amount subtracted, not null
      Throws:
      ArithmeticException - if the result overflows an int

    • multipliedBy

      public Days 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:
      ArithmeticException - if numeric overflow occurs

    • dividedBy

      public Days 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:
      ArithmeticException - if the divisor is zero

    • negated

      public Days 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:
      ArithmeticException - if numeric overflow occurs, which only happens if the amount is Long.MIN_VALUE

    • abs

      public Days 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:
      ArithmeticException - if numeric overflow occurs, which only happens if the amount is Long.MIN_VALUE

    • toPeriod

      public Period toPeriod()
      Gets the number of days as a Period.

      This returns a period with the same number of days.

      Returns:
      the equivalent period, not null

    • addTo

      public Temporal addTo(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 TemporalAmount
      Parameters:
      temporal - the temporal object to adjust, not null
      Returns:
      an object of the same type with the adjustment made, not null
      Throws:
      DateTimeException - if unable to add
      UnsupportedTemporalTypeException - if the DAYS unit is not supported
      ArithmeticException - if numeric overflow occurs

    • subtractFrom

      public Temporal subtractFrom(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 TemporalAmount
      Parameters:
      temporal - the temporal object to adjust, not null
      Returns:
      an object of the same type with the adjustment made, not null
      Throws:
      DateTimeException - if unable to subtract
      UnsupportedTemporalTypeException - if the DAYS unit is not supported
      ArithmeticException - if numeric overflow occurs

    • compareTo

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

      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 Comparable<Days>
      Parameters:
      otherAmount - the other amount, not null
      Returns:
      the comparator value, negative if less, positive if greater

    • equals

      public boolean equals(@Nullable Object otherAmount)
      Checks if this amount is equal to the specified Days.

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

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

    • toString

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