javax.time.calendar
Class Period

java.lang.Object
  extended by javax.time.calendar.Period
All Implemented Interfaces:
java.io.Serializable, PeriodProvider

public final class Period
extends java.lang.Object
implements PeriodProvider, java.io.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:

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
static Period ZERO
          A constant for a period of zero.
 
Method Summary
static Period between(LocalDate startDate, LocalDate endDate)
          Obtains a Period consisting of the number of days, months and years between two dates.
static Period daysBetween(LocalDate startDate, LocalDate endDate)
          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(java.lang.Object obj)
          Checks if this period is equal to another 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()
          A 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(LocalDate startDate, LocalDate endDate)
          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(Duration duration)
          Obtains a Period from a Duration.
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 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(java.lang.CharSequence 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.
 java.lang.String toString()
          Outputs this period as a String, such as P6Y3M1DT12H.
 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(LocalDate startDate, LocalDate endDate)
          Obtains a Period consisting of the number of years between two dates.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

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, not 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, not 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, not null
Throws:
CalendricalException - if the provided period cannot be converted to the supported units
java.lang.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, not 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, not null
Throws:
CalendricalException - if the provided period cannot be converted to the supported units
java.lang.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, not 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, not 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, not null
Throws:
CalendricalException - if the provided period cannot be converted to the supported units
java.lang.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, not 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, not 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, not 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, not 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, not 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, not 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, not 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, not 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, not null
Throws:
java.lang.ArithmeticException - if the result exceeds the supported period range

between

public static Period between(LocalDate startDate,
                             LocalDate endDate)
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:
startDate - the start date, inclusive, not null
endDate - the end date, exclusive, not null
Returns:
the period in days, not null
Throws:
java.lang.ArithmeticException - if the period exceeds the supported range

yearsBetween

public static Period yearsBetween(LocalDate startDate,
                                  LocalDate endDate)
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:
startDate - the start date, inclusive, not null
endDate - the end date, exclusive, not null
Returns:
the period in days, not null
Throws:
java.lang.ArithmeticException - if the period exceeds the supported range

monthsBetween

public static Period monthsBetween(LocalDate startDate,
                                   LocalDate endDate)
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:
startDate - the start date, inclusive, not null
endDate - the end date, exclusive, not null
Returns:
the period in days, not null
Throws:
java.lang.ArithmeticException - if the period exceeds the supported range

daysBetween

public static Period daysBetween(LocalDate startDate,
                                 LocalDate endDate)
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:
startDate - the start date, inclusive, not null
endDate - the end date, exclusive, not null
Returns:
the period in days, not null
Throws:
java.lang.ArithmeticException - if the period exceeds the supported range

parse

public static Period parse(java.lang.CharSequence 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 ISO-8601 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, not 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:
java.lang.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 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, not 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 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, not 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 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, not 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 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, not 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 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, not 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 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, not 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 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, not 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, not 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, not 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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 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, not null
Throws:
java.lang.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, not null
Throws:
java.lang.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, not null
Throws:
java.lang.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, not null
Throws:
java.lang.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 ISO-8601:

This instance is immutable and unaffected by this method call.

Returns:
a Period based on this period with the amounts normalized, not null
Throws:
java.lang.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 ISO-8601:

This instance is immutable and unaffected by this method call.

Returns:
a Period based on this period with the amounts normalized, not null
Throws:
java.lang.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 ISO-8601:

Returns:
the total number of years
Throws:
java.lang.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 ISO-8601:

Returns:
the total number of years
Throws:
java.lang.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 ISO-8601:

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 ISO-8601:

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 ISO-8601:

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 ISO-8601:

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 ISO-8601:

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 ISO-8601:

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 ISO-8601:

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 ISO-8601:

Returns:
the total number of nanoseconds
Throws:
java.lang.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 ISO-8601:

Returns:
the total number of nanoseconds
Throws:
java.lang.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, not 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, not null
Throws:
java.lang.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 ISO-8601:

Returns:
a Duration equivalent to this period, not 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 ISO-8601:

Returns:
a Duration equivalent to this period, not null
Throws:
CalendricalException - if the period cannot be converted as it contains years/months/days

equals

public boolean equals(java.lang.Object obj)
Checks if this period is equal to another period.

The comparison is based on the amounts held in the period.

Overrides:
equals in class java.lang.Object
Parameters:
obj - the object to check, null returns false
Returns:
true if this is equal to the other period

hashCode

public int hashCode()
A hash code for this period.

Overrides:
hashCode in class java.lang.Object
Returns:
a suitable hash code

toString

public java.lang.String toString()
Outputs this period as a String, such as P6Y3M1DT12H.

The output will be in the ISO-8601 period format.

Overrides:
toString in class java.lang.Object
Returns:
a string representation of this period, not null