Class Period

java.lang.Object
javax.time.calendar.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.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final int
    days
    The number of days.
    private final int
    hours
    The number of hours.
    private final int
    minutes
    The number of minutes.
    private final int
    months
    The number of months.
    private final long
    nanos
    The number of nanoseconds.
    private PeriodFields
    periodFields
    The cached PeriodFields.
    private final int
    seconds
    The number of seconds.
    private static final long
    serialVersionUID
    The serialization version.
    private String
    string
    The cached toString value.
    private static final PeriodUnit[]
    UNITS
    The ISO period units, trusted to not be altered.
    private final int
    years
    The number of years.
    static final Period
    ZERO
    A constant for a period of zero.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Period(int years, int months, int days, int hours, int minutes, int seconds, long nanos)
    Constructor.

  • Method Summary

    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.
    private Object
    readResolve()
    Resolves singletons.
    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.

    Methods inherited from class Object

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

  • Field Details

    • ZERO

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

    • serialVersionUID

      private static final long serialVersionUID
      The serialization version.
      See Also:

    • UNITS

      private static final PeriodUnit[] UNITS
      The ISO period units, trusted to not be altered.

    • years

      private final int years
      The number of years.

    • months

      private final int months
      The number of months.

    • days

      private final int days
      The number of days.

    • hours

      private final int hours
      The number of hours.

    • minutes

      private final int minutes
      The number of minutes.

    • seconds

      private final int seconds
      The number of seconds.

    • nanos

      private final long nanos
      The number of nanoseconds.

    • periodFields

      private transient volatile PeriodFields periodFields
      The cached PeriodFields.

    • string

      private transient volatile String string
      The cached toString value.

  • Constructor Details

    • Period

      private Period(int years, int months, int days, int hours, int minutes, int seconds, long nanos)
      Constructor.
      Parameters:
      years - the amount
      months - the amount
      days - the amount
      hours - the amount
      minutes - the amount
      seconds - the amount
      nanos - the amount

  • Method Details

    • 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

    • readResolve

      private Object readResolve()
      Resolves singletons.
      Returns:
      the resolved instance

    • 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