Class Period

  • All Implemented Interfaces:
    Serializable, PeriodProvider

    public final class Period
    extends Object
    implements PeriodProvider, Serializable
    An immutable period consisting of the ISO-8601 year, month, day, hour, minute, second and nanosecond units, such as '3 Months, 4 Days and 7 Hours'.

    A period is a human-scale description of an amount of time. This class represents the 7 standard definitions from ISOChronology. The period units used are 'Years', 'Months', 'Days', 'Hours', 'Minutes', 'Seconds' and 'Nanoseconds'.

    The ISOChronology defines a relationship between some of the units:

    • 12 months in a year
    • 24 hours in a day (ignoring time-zones)
    • 60 minutes in an hour
    • 60 seconds in a minute
    • 1,000,000,000 nanoseconds in a second
    The 24 hours in a day connection is not always true, due to time-zone changes. As such, methods on this class make it clear when the that connection is being used.

    Period is immutable and thread-safe.

    Author:
    Stephen Colebourne
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Period ZERO
      A constant for a period of zero.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static Period between​(DateProvider startDateProvider, DateProvider endDateProvider)
      Obtains a Period consisting of the number of days, months and years between two dates.
      static Period daysBetween​(DateProvider startDateProvider, DateProvider endDateProvider)
      Obtains a Period consisting of the number of days between two dates.
      Period dividedBy​(int divisor)
      Returns a new instance with each element in this period divided by the specified value.
      boolean equals​(Object obj)
      Is this period equal to the specified period.
      int getDays()
      Gets the amount of days of this period, if any.
      int getHours()
      Gets the amount of hours of this period, if any.
      int getMinutes()
      Gets the amount of minutes of this period, if any.
      int getMonths()
      Gets the amount of months of this period, if any.
      long getNanos()
      Gets the amount of nanoseconds of this period, if any.
      int getNanosInt()
      Gets the amount of nanoseconds of this period safely converted to an int.
      int getSeconds()
      Gets the amount of seconds of this period, if any.
      int getYears()
      Gets the amount of years of this period, if any.
      int hashCode()
      Returns the hash code for this period.
      boolean isPositive()
      Checks if this period is fully positive, excluding zero.
      boolean isPositiveOrZero()
      Checks if this period is fully positive, including zero.
      boolean isZero()
      Checks if this period is zero-length.
      Period minus​(PeriodProvider periodProvider)
      Returns a copy of this period with the specified period subtracted.
      Period minusDays​(int days)
      Returns a copy of this period with the specified number of days subtracted.
      Period minusHours​(int hours)
      Returns a copy of this period with the specified number of hours subtracted.
      Period minusMinutes​(int minutes)
      Returns a copy of this period with the specified number of minutes subtracted.
      Period minusMonths​(int months)
      Returns a copy of this period with the specified number of months subtracted.
      Period minusNanos​(long nanos)
      Returns a copy of this period with the specified number of nanoseconds subtracted.
      Period minusSeconds​(int seconds)
      Returns a copy of this period with the specified number of seconds subtracted.
      Period minusYears​(int years)
      Returns a copy of this period with the specified number of years subtracted.
      static Period monthsBetween​(DateProvider startDateProvider, DateProvider endDateProvider)
      Obtains a Period consisting of the number of months between two dates.
      Period multipliedBy​(int scalar)
      Returns a new instance with each element in this period multiplied by the specified scalar.
      Period negated()
      Returns a new instance with each amount in this period negated.
      Period normalized()
      Returns a copy of this period with all amounts normalized to the standard ranges for date-time fields.
      Period normalizedWith24HourDays()
      Returns a copy of this period with all amounts normalized to the standard ranges for date-time fields including the assumption that days are 24 hours long.
      static Period of​(int years, int months, int days, int hours, int minutes, int seconds)
      Obtains a Period from date-based and time-based fields.
      static Period of​(int years, int months, int days, int hours, int minutes, int seconds, long nanos)
      Obtains a Period from date-based and time-based fields.
      static Period of​(int amount, PeriodUnit unit)
      Obtains a Period from an amount and unit.
      static Period of​(PeriodProvider periodProvider)
      Obtains a Period from a provider of periods.
      static Period of​(Duration duration)
      Obtains a Period from a Duration.
      static Period ofDateFields​(int years, int months, int days)
      Obtains a Period from date-based fields.
      static Period ofDateFields​(PeriodProvider periodProvider)
      Obtains a Period from the date-based fields of a period.
      static Period ofDays​(int days)
      Obtains a Period from a number of days.
      static Period ofHours​(int hours)
      Obtains a Period from a number of hours.
      static Period ofMinutes​(int minutes)
      Obtains a Period from a number of minutes.
      static Period ofMonths​(int months)
      Obtains a Period from a number of months.
      static Period ofNanos​(long nanos)
      Obtains a Period from a number of nanoseconds.
      static Period ofSeconds​(int seconds)
      Obtains a Period from a number of seconds.
      static Period ofTimeFields​(int hours, int minutes, int seconds)
      Obtains a Period from time-based fields.
      static Period ofTimeFields​(int hours, int minutes, int seconds, long nanos)
      Obtains a Period from time-based fields.
      static Period ofTimeFields​(PeriodProvider periodProvider)
      Obtains a Period from the time-based fields of a period.
      static Period ofYears​(int years)
      Obtains a Period from a number of years.
      static Period parse​(String text)
      Obtains a Period from a text string such as PnYnMnDTnHnMn.nS.
      Period plus​(PeriodProvider periodProvider)
      Returns a copy of this period with the specified period added.
      Period plusDays​(int days)
      Returns a copy of this period with the specified number of days added.
      Period plusHours​(int hours)
      Returns a copy of this period with the specified number of hours added.
      Period plusMinutes​(int minutes)
      Returns a copy of this period with the specified number of minutes added.
      Period plusMonths​(int months)
      Returns a copy of this period with the specified number of months added.
      Period plusNanos​(long nanos)
      Returns a copy of this period with the specified number of nanoseconds added.
      Period plusSeconds​(int seconds)
      Returns a copy of this period with the specified number of seconds added.
      Period plusYears​(int years)
      Returns a copy of this period with the specified number of years added.
      Duration toDuration()
      Calculates the accurate duration of this period.
      Duration toDurationWith24HourDays()
      Calculates the accurate duration of this period.
      Duration toEstimatedDuration()
      Estimates the duration of this period.
      PeriodFields toPeriodFields()
      Converts this period to a PeriodFields.
      String toString()
      Returns a string representation of the amount of time.
      long totalDaysWith24HourDays()
      Gets the total number of days represented by this period using standard assumptions for the meaning of day, hour, minute and second.
      long totalHours()
      Gets the total number of hours represented by this period using standard assumptions for the meaning of hour, minute and second.
      long totalHoursWith24HourDays()
      Gets the total number of hours represented by this period using standard assumptions for the meaning of day, hour, minute and second.
      long totalMinutes()
      Gets the total number of minutes represented by this period using standard assumptions for the meaning of hour, minute and second.
      long totalMinutesWith24HourDays()
      Gets the total number of minutes represented by this period using standard assumptions for the meaning of day, hour, minute and second.
      long totalMonths()
      Gets the total number of months represented by this period using standard assumptions for the meaning of month.
      long totalNanos()
      Gets the total number of nanoseconds represented by this period using standard assumptions for the meaning of hour, minute and second.
      long totalNanosWith24HourDays()
      Gets the total number of nanoseconds represented by this period using standard assumptions for the meaning of day, hour, minute and second.
      long totalSeconds()
      Gets the total number of seconds represented by this period using standard assumptions for the meaning of hour, minute and second.
      long totalSecondsWith24HourDays()
      Gets the total number of seconds represented by this period using standard assumptions for the meaning of day, hour, minute and second.
      long totalYears()
      Gets the total number of years represented by this period using standard assumptions for the meaning of month.
      Period withDateFieldsOnly()
      Returns a copy of this period with only the date-based fields retained.
      Period withDays​(int days)
      Returns a copy of this period with the specified amount of days.
      Period withHours​(int hours)
      Returns a copy of this period with the specified amount of hours.
      Period withMinutes​(int minutes)
      Returns a copy of this period with the specified amount of minutes.
      Period withMonths​(int months)
      Returns a copy of this period with the specified amount of months.
      Period withNanos​(long nanos)
      Returns a copy of this period with the specified amount of nanoseconds.
      Period withSeconds​(int seconds)
      Returns a copy of this period with the specified amount of seconds.
      Period withTimeFieldsOnly()
      Returns a copy of this period with only the time-based fields retained.
      Period withYears​(int years)
      Returns a copy of this period with the specified amount of years.
      static Period yearsBetween​(DateProvider startDateProvider, DateProvider endDateProvider)
      Obtains a Period consisting of the number of years between two dates.
    • Field Detail

      • ZERO

        public static final Period ZERO
        A constant for a period of zero.
    • Method Detail

      • of

        public static Period of​(int years,
                                int months,
                                int days,
                                int hours,
                                int minutes,
                                int seconds)
        Obtains a Period from date-based and time-based fields.

        This creates an instance based on years, months, days, hours, minutes and seconds.

        Parameters:
        years - the amount of years, may be negative
        months - the amount of months, may be negative
        days - the amount of days, may be negative
        hours - the amount of hours, may be negative
        minutes - the amount of minutes, may be negative
        seconds - the amount of seconds, may be negative
        Returns:
        the period, never null
      • of

        public static Period of​(int years,
                                int months,
                                int days,
                                int hours,
                                int minutes,
                                int seconds,
                                long nanos)
        Obtains a Period from date-based and time-based fields.

        This creates an instance based on years, months, days, hours, minutes, seconds and nanoseconds. The resulting period will have normalized seconds and nanoseconds.

        Parameters:
        years - the amount of years, may be negative
        months - the amount of months, may be negative
        days - the amount of days, may be negative
        hours - the amount of hours, may be negative
        minutes - the amount of minutes, may be negative
        seconds - the amount of seconds, may be negative
        nanos - the amount of nanos, may be negative
        Returns:
        the period, never null
      • of

        public static Period of​(PeriodProvider periodProvider)
        Obtains a Period from a provider of periods.

        A Period supports 7 units, ISO years, months, days, hours, minutes, seconds and nanoseconds. Any period that contains amounts in these units, or in units that can be converted to these units will be accepted. If the provider contains any other unit, an exception is thrown.

        Parameters:
        periodProvider - a provider of period information, not null
        Returns:
        the period, never null
        Throws:
        CalendricalException - if the provided period cannot be converted to the supported units
        ArithmeticException - if any provided amount, exceeds the supported range
      • ofDateFields

        public static Period ofDateFields​(int years,
                                          int months,
                                          int days)
        Obtains a Period from date-based fields.

        This creates an instance based on years, months and days.

        Parameters:
        years - the amount of years, may be negative
        months - the amount of months, may be negative
        days - the amount of days, may be negative
        Returns:
        the period, never null
      • ofDateFields

        public static Period ofDateFields​(PeriodProvider periodProvider)
        Obtains a Period from the date-based fields of a period.

        A Period supports 7 units, ISO years, months, days, hours, minutes, seconds and nanoseconds. Any period that contains amounts in these units, or in units that can be converted to these units will be accepted. If the provider contains any other unit, an exception is thrown.

        Once the initial conversion to the 7 units is complete, the period is created using just the date-based fields - years, months and days. The time-based fields are ignored and will be zero in the created period.

        Parameters:
        periodProvider - a provider of period information, not null
        Returns:
        the period containing only date-based fields, never null
        Throws:
        CalendricalException - if the provided period cannot be converted to the supported units
        ArithmeticException - if any provided amount, exceeds the supported range
      • ofTimeFields

        public static Period ofTimeFields​(int hours,
                                          int minutes,
                                          int seconds)
        Obtains a Period from time-based fields.

        This creates an instance based on hours, minutes and seconds.

        Parameters:
        hours - the amount of hours, may be negative
        minutes - the amount of minutes, may be negative
        seconds - the amount of seconds, may be negative
        Returns:
        the period, never null
      • ofTimeFields

        public static Period ofTimeFields​(int hours,
                                          int minutes,
                                          int seconds,
                                          long nanos)
        Obtains a Period from time-based fields.

        This creates an instance based on hours, minutes, seconds and nanoseconds.

        Parameters:
        hours - the amount of hours, may be negative
        minutes - the amount of minutes, may be negative
        seconds - the amount of seconds, may be negative
        nanos - the amount of nanos, may be negative
        Returns:
        the period, never null
      • ofTimeFields

        public static Period ofTimeFields​(PeriodProvider periodProvider)
        Obtains a Period from the time-based fields of a period.

        A Period supports 7 units, ISO years, months, days, hours, minutes, seconds and nanoseconds. Any period that contains amounts in these units, or in units that can be converted to these units will be accepted. If the provider contains any other unit, an exception is thrown.

        Once the initial conversion to the 7 units is complete, the period is created using just the time-based fields - hours, minutes, seconds and nanoseconds. The date-based fields are ignored and will be zero in the created period.

        Parameters:
        periodProvider - a provider of period information, not null
        Returns:
        the period containing only time-based fields, never null
        Throws:
        CalendricalException - if the provided period cannot be converted to the supported units
        ArithmeticException - if any provided amount, exceeds the supported range
      • of

        public static Period of​(int amount,
                                PeriodUnit unit)
        Obtains a Period from an amount and unit.

        The parameters represent the two parts of a phrase like '6 Days'.

        A Period supports 7 units, ISO years, months, days, hours, minutes, seconds and nanoseconds. The unit must be one of these, or be able to be converted to one of these.

        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 period, never null
      • ofYears

        public static Period ofYears​(int years)
        Obtains a Period from a number of years.
        Parameters:
        years - the amount of years, may be negative
        Returns:
        the period, never null
      • ofMonths

        public static Period ofMonths​(int months)
        Obtains a Period from a number of months.
        Parameters:
        months - the amount of months, may be negative
        Returns:
        the period, never null
      • ofDays

        public static Period ofDays​(int days)
        Obtains a Period from a number of days.
        Parameters:
        days - the amount of days, may be negative
        Returns:
        the period, never null
      • ofHours

        public static Period ofHours​(int hours)
        Obtains a Period from a number of hours.
        Parameters:
        hours - the amount of hours, may be negative
        Returns:
        the period, never null
      • ofMinutes

        public static Period ofMinutes​(int minutes)
        Obtains a Period from a number of minutes.
        Parameters:
        minutes - the amount of minutes, may be negative
        Returns:
        the period, never null
      • ofSeconds

        public static Period ofSeconds​(int seconds)
        Obtains a Period from a number of seconds.
        Parameters:
        seconds - the amount of seconds, may be negative
        Returns:
        the period, never null
      • ofNanos

        public static Period ofNanos​(long nanos)
        Obtains a Period from a number of nanoseconds.
        Parameters:
        nanos - the amount of nanos, may be negative
        Returns:
        the period, never null
      • of

        public static Period of​(Duration duration)
        Obtains a Period from a Duration.

        The created period will have normalized values for the hours, minutes, seconds and nanoseconds fields. The years, months and days fields will be zero.

        To populate the days field, call normalizedWith24HourDays() on the created period.

        Parameters:
        duration - the duration to create from, not null
        Returns:
        the PeriodFields instance, never null
        Throws:
        ArithmeticException - if the result exceeds the supported period range
      • between

        public static Period between​(DateProvider startDateProvider,
                                     DateProvider endDateProvider)
        Obtains a Period consisting of the number of days, months and years between two dates.

        The start date is included, but the end date is not. Only whole years count. For example, from 2010-01-15 to 2011-03-18 is one year, two months and three days.

        The result of this method can be a negative period if the end is before the start. The negative sign will be the same in each of year, month and day.

        Adding the result of this method to the start date will always yield the end date.

        Parameters:
        startDateProvider - the start date, inclusive, not null
        endDateProvider - the end date, exclusive, not null
        Returns:
        the period in days, never null
        Throws:
        ArithmeticException - if the period exceeds the supported range
      • yearsBetween

        public static Period yearsBetween​(DateProvider startDateProvider,
                                          DateProvider endDateProvider)
        Obtains a Period consisting of the number of years between two dates.

        The start date is included, but the end date is not. Only whole years count. For example, from 2010-01-15 to 2012-01-15 is two years, whereas from 2010-01-15 to 2012-01-14 is only one year.

        The result of this method can be a negative period if the end is before the start.

        Parameters:
        startDateProvider - the start date, inclusive, not null
        endDateProvider - the end date, exclusive, not null
        Returns:
        the period in days, never null
        Throws:
        ArithmeticException - if the period exceeds the supported range
      • monthsBetween

        public static Period monthsBetween​(DateProvider startDateProvider,
                                           DateProvider endDateProvider)
        Obtains a Period consisting of the number of months between two dates.

        The start date is included, but the end date is not. Only whole months count. For example, from 2010-01-15 to 2010-03-15 is two months, whereas from 2010-01-15 to 2010-03-14 is only one month.

        The result of this method can be a negative period if the end is before the start.

        Parameters:
        startDateProvider - the start date, inclusive, not null
        endDateProvider - the end date, exclusive, not null
        Returns:
        the period in days, never null
        Throws:
        ArithmeticException - if the period exceeds the supported range
      • daysBetween

        public static Period daysBetween​(DateProvider startDateProvider,
                                         DateProvider endDateProvider)
        Obtains a Period consisting of the number of days between two dates.

        The start date is included, but the end date is not. For example, from 2010-01-15 to 2010-01-18 is three days.

        The result of this method can be a negative period if the end is before the start.

        Parameters:
        startDateProvider - the start date, inclusive, not null
        endDateProvider - the end date, exclusive, not null
        Returns:
        the period in days, never null
        Throws:
        ArithmeticException - if the period exceeds the supported range
      • parse

        public static Period parse​(String text)
        Obtains a Period from a text string such as PnYnMnDTnHnMn.nS.

        This will parse the string produced by toString() which is a subset of the ISO8601 period format PnYnMnDTnHnMn.nS.

        The string consists of a series of numbers with a suffix identifying their meaning. The values, and suffixes, must be in the sequence year, month, day, hour, minute, second. Any of the number/suffix pairs may be omitted providing at least one is present. If the period is zero, the value is normally represented as PT0S. The numbers must consist of ASCII digits. Any of the numbers may be negative. Negative zero is not accepted. The number of nanoseconds is expressed as an optional fraction of the seconds. There must be at least one digit before any decimal point. There must be between 1 and 9 inclusive digits after any decimal point. The letters will all be accepted in upper or lower case. The decimal point may be either a dot or a comma.

        Parameters:
        text - the text to parse, not null
        Returns:
        the parsed period, never null
        Throws:
        CalendricalParseException - if the text cannot be parsed to a Period
      • isZero

        public boolean isZero()
        Checks if this period is zero-length.
        Returns:
        true if this period is zero-length
      • isPositive

        public boolean isPositive()
        Checks if this period is fully positive, excluding zero.

        This checks whether all the amounts in the period are positive, defined as greater than zero.

        Returns:
        true if this period is fully positive excluding zero
      • isPositiveOrZero

        public boolean isPositiveOrZero()
        Checks if this period is fully positive, including zero.

        This checks whether all the amounts in the period are positive, defined as greater than or equal to zero.

        Returns:
        true if this period is fully positive including zero
      • getYears

        public int getYears()
        Gets the amount of years of this period, if any.
        Returns:
        the amount of years of this period
      • getMonths

        public int getMonths()
        Gets the amount of months of this period, if any.
        Returns:
        the amount of months of this period
      • getDays

        public int getDays()
        Gets the amount of days of this period, if any.
        Returns:
        the amount of days of this period
      • getHours

        public int getHours()
        Gets the amount of hours of this period, if any.
        Returns:
        the amount of hours of this period
      • getMinutes

        public int getMinutes()
        Gets the amount of minutes of this period, if any.
        Returns:
        the amount of minutes of this period
      • getSeconds

        public int getSeconds()
        Gets the amount of seconds of this period, if any.
        Returns:
        the amount of seconds of this period
      • getNanos

        public long getNanos()
        Gets the amount of nanoseconds of this period, if any.
        Returns:
        the amount of nanoseconds of this period
      • getNanosInt

        public int getNanosInt()
        Gets the amount of nanoseconds of this period safely converted to an int.
        Returns:
        the amount of nanoseconds of this period
        Throws:
        ArithmeticException - if the number of nanoseconds exceeds the capacity of an int
      • withYears

        public Period withYears​(int years)
        Returns a copy of this period with the specified amount of years.

        This method will only affect the the years field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        years - the years to represent
        Returns:
        a Period based on this period with the requested years, never null
      • withMonths

        public Period withMonths​(int months)
        Returns a copy of this period with the specified amount of months.

        This method will only affect the the months field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        months - the months to represent
        Returns:
        a Period based on this period with the requested months, never null
      • withDays

        public Period withDays​(int days)
        Returns a copy of this period with the specified amount of days.

        This method will only affect the the days field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        days - the days to represent
        Returns:
        a Period based on this period with the requested days, never null
      • withHours

        public Period withHours​(int hours)
        Returns a copy of this period with the specified amount of hours.

        This method will only affect the the hours field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        hours - the hours to represent
        Returns:
        a Period based on this period with the requested hours, never null
      • withMinutes

        public Period withMinutes​(int minutes)
        Returns a copy of this period with the specified amount of minutes.

        This method will only affect the the minutes field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        minutes - the minutes to represent
        Returns:
        a Period based on this period with the requested minutes, never null
      • withSeconds

        public Period withSeconds​(int seconds)
        Returns a copy of this period with the specified amount of seconds.

        This method will only affect the the seconds field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        seconds - the seconds to represent
        Returns:
        a Period based on this period with the requested seconds, never null
      • withNanos

        public Period withNanos​(long nanos)
        Returns a copy of this period with the specified amount of nanoseconds.

        This method will only affect the the nanoseconds field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        nanos - the nanoseconds to represent
        Returns:
        a Period based on this period with the requested nanoseconds, never null
      • withDateFieldsOnly

        public Period withDateFieldsOnly()
        Returns a copy of this period with only the date-based fields retained.

        The returned period will have the same values for the date-based fields (years, months and days) and zero values for the time-based fields.

        This instance is immutable and unaffected by this method call.

        Returns:
        a Period based on this period with zero values for time-based fields, never null
      • withTimeFieldsOnly

        public Period withTimeFieldsOnly()
        Returns a copy of this period with only the time-based fields retained.

        The returned period will have the same values for the time-based fields (hours, minutes, seconds and nanoseconds) and zero values for the date-based fields.

        This instance is immutable and unaffected by this method call.

        Returns:
        a Period based on this period with zero values for date-based fields, never null
      • plus

        public Period plus​(PeriodProvider periodProvider)
        Returns a copy of this period with the specified period added.

        This instance is immutable and unaffected by this method call.

        Parameters:
        periodProvider - the period to add, not null
        Returns:
        a Period based on this period with the requested period added, never null
        Throws:
        ArithmeticException - if the capacity of any field is exceeded
      • plusYears

        public Period plusYears​(int years)
        Returns a copy of this period with the specified number of years added.

        This method will only affect the the years field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        years - the years to add, positive or negative
        Returns:
        a Period based on this period with the requested years added, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • plusMonths

        public Period plusMonths​(int months)
        Returns a copy of this period with the specified number of months added.

        This method will only affect the the months field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        months - the months to add, positive or negative
        Returns:
        a Period based on this period with the requested months added, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • plusDays

        public Period plusDays​(int days)
        Returns a copy of this period with the specified number of days added.

        This method will only affect the the days field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        days - the days to add, positive or negative
        Returns:
        a Period based on this period with the requested days added, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • plusHours

        public Period plusHours​(int hours)
        Returns a copy of this period with the specified number of hours added.

        This method will only affect the the hours field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        hours - the hours to add, positive or negative
        Returns:
        a Period based on this period with the requested hours added, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • plusMinutes

        public Period plusMinutes​(int minutes)
        Returns a copy of this period with the specified number of minutes added.

        This method will only affect the the minutes field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        minutes - the minutes to add, positive or negative
        Returns:
        a Period based on this period with the requested minutes added, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • plusSeconds

        public Period plusSeconds​(int seconds)
        Returns a copy of this period with the specified number of seconds added.

        This method will only affect the the seconds field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        seconds - the seconds to add, positive or negative
        Returns:
        a Period based on this period with the requested seconds added, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • plusNanos

        public Period plusNanos​(long nanos)
        Returns a copy of this period with the specified number of nanoseconds added.

        This method will only affect the the nanoseconds field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        nanos - the nanoseconds to add, positive or negative
        Returns:
        a Period based on this period with the requested nanoseconds added, never null
        Throws:
        ArithmeticException - if the capacity of a long is exceeded
      • minus

        public Period minus​(PeriodProvider periodProvider)
        Returns a copy of this period with the specified period subtracted.

        This instance is immutable and unaffected by this method call.

        Parameters:
        periodProvider - the period to subtract, not null
        Returns:
        a Period based on this period with the requested period subtracted, never null
        Throws:
        ArithmeticException - if the capacity of any field is exceeded
      • minusYears

        public Period minusYears​(int years)
        Returns a copy of this period with the specified number of years subtracted.

        This method will only affect the the years field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        years - the years to subtract, positive or negative
        Returns:
        a Period based on this period with the requested years subtracted, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • minusMonths

        public Period minusMonths​(int months)
        Returns a copy of this period with the specified number of months subtracted.

        This method will only affect the the months field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        months - the months to subtract, positive or negative
        Returns:
        a Period based on this period with the requested months subtracted, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • minusDays

        public Period minusDays​(int days)
        Returns a copy of this period with the specified number of days subtracted.

        This method will only affect the the days field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        days - the days to subtract, positive or negative
        Returns:
        a Period based on this period with the requested days subtracted, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • minusHours

        public Period minusHours​(int hours)
        Returns a copy of this period with the specified number of hours subtracted.

        This method will only affect the the hours field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        hours - the hours to subtract, positive or negative
        Returns:
        a Period based on this period with the requested hours subtracted, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • minusMinutes

        public Period minusMinutes​(int minutes)
        Returns a copy of this period with the specified number of minutes subtracted.

        This method will only affect the the minutes field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        minutes - the minutes to subtract, positive or negative
        Returns:
        a Period based on this period with the requested minutes subtracted, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • minusSeconds

        public Period minusSeconds​(int seconds)
        Returns a copy of this period with the specified number of seconds subtracted.

        This method will only affect the the seconds field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        seconds - the seconds to subtract, positive or negative
        Returns:
        a Period based on this period with the requested seconds subtracted, never null
        Throws:
        ArithmeticException - if the capacity of an int is exceeded
      • minusNanos

        public Period minusNanos​(long nanos)
        Returns a copy of this period with the specified number of nanoseconds subtracted.

        This method will only affect the the nanoseconds field. All other fields are left untouched.

        This instance is immutable and unaffected by this method call.

        Parameters:
        nanos - the nanoseconds to subtract, positive or negative
        Returns:
        a Period based on this period with the requested nanoseconds subtracted, never null
        Throws:
        ArithmeticException - if the capacity of a long is exceeded
      • multipliedBy

        public Period multipliedBy​(int scalar)
        Returns a new instance with each element in this period multiplied by the specified scalar.
        Parameters:
        scalar - the scalar to multiply by, not null
        Returns:
        a Period based on this period with the amounts multiplied by the scalar, never null
        Throws:
        ArithmeticException - if the capacity of any field is exceeded
      • dividedBy

        public Period dividedBy​(int divisor)
        Returns a new instance with each element in this period divided by the specified value.

        The implementation simply divides each separate field by the divisor using integer division.

        Parameters:
        divisor - the value to divide by, not null
        Returns:
        a Period based on this period with the amounts divided by the divisor, never null
        Throws:
        ArithmeticException - if dividing by zero
      • negated

        public Period negated()
        Returns a new instance with each amount in this period negated.
        Returns:
        a Period based on this period with the amounts negated, never null
        Throws:
        ArithmeticException - if any field has the minimum value
      • normalized

        public Period normalized()
        Returns a copy of this period with all amounts normalized to the standard ranges for date-time fields.

        Two normalizations occur, one for years and months, and one for hours, minutes, seconds and nanoseconds. Days are not normalized, as a day may vary in length at daylight savings cutover. For example, a period of P1Y15M1DT28H61M will be normalized to P2Y3M1DT29H1M.

        Note that this method normalizes using assumptions:

        • 12 months in a year
        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.

        This instance is immutable and unaffected by this method call.

        Returns:
        a Period based on this period with the amounts normalized, never null
        Throws:
        ArithmeticException - if the capacity of any field is exceeded
      • normalizedWith24HourDays

        public Period normalizedWith24HourDays()
        Returns a copy of this period with all amounts normalized to the standard ranges for date-time fields including the assumption that days are 24 hours long.

        Two normalizations occur, one for years and months, and one for days, hours, minutes, seconds and nanoseconds. For example, a period of P1Y15M1DT28H will be normalized to P2Y3M2DT4H.

        Note that this method normalizes using assumptions:

        • 12 months in a year
        • 24 hours in a day
        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.

        This instance is immutable and unaffected by this method call.

        Returns:
        a Period based on this period with the amounts normalized, never null
        Throws:
        ArithmeticException - if the capacity of any field is exceeded
      • totalYears

        public long totalYears()
        Gets the total number of years represented by this period using standard assumptions for the meaning of month.

        This method ignores days, hours, minutes, seconds and nanos. It calculates using the assumption:

        • 12 months in a year
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of years
        Throws:
        ArithmeticException - if the capacity of a long is exceeded
      • totalMonths

        public long totalMonths()
        Gets the total number of months represented by this period using standard assumptions for the meaning of month.

        This method ignores days, hours, minutes, seconds and nanos. It calculates using the assumption:

        • 12 months in a year
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of years
        Throws:
        ArithmeticException - if the capacity of a long is exceeded
      • totalDaysWith24HourDays

        public long totalDaysWith24HourDays()
        Gets the total number of days represented by this period using standard assumptions for the meaning of day, hour, minute and second.

        This method ignores years and months. It calculates using assumptions:

        • 24 hours in a day
        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of days
      • totalHours

        public long totalHours()
        Gets the total number of hours represented by this period using standard assumptions for the meaning of hour, minute and second.

        This method ignores years, months and days. It calculates using assumptions:

        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of hours
      • totalHoursWith24HourDays

        public long totalHoursWith24HourDays()
        Gets the total number of hours represented by this period using standard assumptions for the meaning of day, hour, minute and second.

        This method ignores years and months. It calculates using assumptions:

        • 24 hours in a day
        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of hours
      • totalMinutes

        public long totalMinutes()
        Gets the total number of minutes represented by this period using standard assumptions for the meaning of hour, minute and second.

        This method ignores years, months and days. It calculates using assumptions:

        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of minutes
      • totalMinutesWith24HourDays

        public long totalMinutesWith24HourDays()
        Gets the total number of minutes represented by this period using standard assumptions for the meaning of day, hour, minute and second.

        This method ignores years and months. It calculates using assumptions:

        • 24 hours in a day
        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of minutes
      • totalSeconds

        public long totalSeconds()
        Gets the total number of seconds represented by this period using standard assumptions for the meaning of hour, minute and second.

        This method ignores years, months and days. It calculates using assumptions:

        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of seconds
      • totalSecondsWith24HourDays

        public long totalSecondsWith24HourDays()
        Gets the total number of seconds represented by this period using standard assumptions for the meaning of day, hour, minute and second.

        This method ignores years and months. It calculates using assumptions:

        • 24 hours in a day
        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of seconds
      • totalNanos

        public long totalNanos()
        Gets the total number of nanoseconds represented by this period using standard assumptions for the meaning of hour, minute and second.

        This method ignores years, months and days. It calculates using assumptions:

        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of nanoseconds
        Throws:
        ArithmeticException - if the capacity of a long is exceeded
      • totalNanosWith24HourDays

        public long totalNanosWith24HourDays()
        Gets the total number of nanoseconds represented by this period using standard assumptions for the meaning of day, hour, minute and second.

        This method ignores years and months. It calculates using assumptions:

        • 24 hours in a day
        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        the total number of nanoseconds
        Throws:
        ArithmeticException - if the capacity of a long is exceeded
      • toPeriodFields

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

        The returned PeriodFields will only contain the non-zero amounts.

        Specified by:
        toPeriodFields in interface PeriodProvider
        Returns:
        a PeriodFields equivalent to this period, never null
      • toEstimatedDuration

        public Duration toEstimatedDuration()
        Estimates the duration of this period.

        Each PeriodUnit contains an estimated duration for that unit. The per-unit estimate allows an estimate to be calculated for the whole period including years, months and days. The estimate will equal the accurate calculation if the years, months and days fields are zero.

        Returns:
        the estimated duration of this period, never null
        Throws:
        ArithmeticException - if the calculation overflows
      • toDuration

        public Duration toDuration()
        Calculates the accurate duration of this period.

        The calculation uses the hours, minutes, seconds and nanoseconds fields. If years, months or days are present an exception is thrown.

        The duration is calculated using assumptions:

        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        a Duration equivalent to this period, never null
        Throws:
        CalendricalException - if the period cannot be converted as it contains years/months/days
      • toDurationWith24HourDays

        public Duration toDurationWith24HourDays()
        Calculates the accurate duration of this period.

        The calculation uses the days, hours, minutes, seconds and nanoseconds fields. If years or months are present an exception is thrown.

        The duration is calculated using assumptions:

        • 24 hours in a day
        • 60 minutes in an hour
        • 60 seconds in a minute
        • 1,000,000,000 nanoseconds in a second
        This method is only appropriate to call if these assumptions are met.
        Returns:
        a Duration equivalent to this period, never null
        Throws:
        CalendricalException - if the period cannot be converted as it contains years/months/days
      • equals

        public boolean equals​(Object obj)
        Is this period equal to the specified period.
        Overrides:
        equals in class Object
        Parameters:
        obj - the other period to compare to, null returns false
        Returns:
        true if this instance is equal to the specified period
      • 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 the amount of time.
        Overrides:
        toString in class Object
        Returns:
        the amount of time in ISO8601 string format