Class Period
- java.lang.Object
-
- 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:- 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
Period is immutable and thread-safe.
- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description private int
days
The number of days.private int
hours
The number of hours.private int
minutes
The number of minutes.private int
months
The number of months.private long
nanos
The number of nanoseconds.private PeriodFields
periodFields
The cached PeriodFields.private int
seconds
The number of seconds.private static long
serialVersionUID
The serialization version.private java.lang.String
string
The cached toString value.private static PeriodUnit[]
UNITS
The ISO period units, trusted to not be altered.private int
years
The number of years.static 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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static Period
between(DateProvider startDateProvider, DateProvider endDateProvider)
Obtains aPeriod
consisting of the number of days, months and years between two dates.static Period
daysBetween(DateProvider startDateProvider, DateProvider endDateProvider)
Obtains aPeriod
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)
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 anint
.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 aPeriod
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 aPeriod
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 aPeriod
from date-based and time-based fields.static Period
of(int amount, PeriodUnit unit)
Obtains aPeriod
from an amount and unit.static Period
of(PeriodProvider periodProvider)
Obtains aPeriod
from a provider of periods.static Period
of(Duration duration)
Obtains aPeriod
from aDuration
.static Period
ofDateFields(int years, int months, int days)
Obtains aPeriod
from date-based fields.static Period
ofDateFields(PeriodProvider periodProvider)
Obtains aPeriod
from the date-based fields of a period.static Period
ofDays(int days)
Obtains aPeriod
from a number of days.static Period
ofHours(int hours)
Obtains aPeriod
from a number of hours.static Period
ofMinutes(int minutes)
Obtains aPeriod
from a number of minutes.static Period
ofMonths(int months)
Obtains aPeriod
from a number of months.static Period
ofNanos(long nanos)
Obtains aPeriod
from a number of nanoseconds.static Period
ofSeconds(int seconds)
Obtains aPeriod
from a number of seconds.static Period
ofTimeFields(int hours, int minutes, int seconds)
Obtains aPeriod
from time-based fields.static Period
ofTimeFields(int hours, int minutes, int seconds, long nanos)
Obtains aPeriod
from time-based fields.static Period
ofTimeFields(PeriodProvider periodProvider)
Obtains aPeriod
from the time-based fields of a period.static Period
ofYears(int years)
Obtains aPeriod
from a number of years.static Period
parse(java.lang.String text)
Obtains aPeriod
from a text string such asPnYnMnDTnHnMn.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 java.lang.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 aPeriodFields
.java.lang.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 aPeriod
consisting of the number of years between two dates.
-
-
-
Field Detail
-
ZERO
public static final Period ZERO
A constant for a period of zero.
-
serialVersionUID
private static final long serialVersionUID
The serialization version.- See Also:
- Constant Field Values
-
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 java.lang.String string
The cached toString value.
-
-
Method Detail
-
of
public static Period of(int years, int months, int days, int hours, int minutes, int seconds)
Obtains aPeriod
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 negativemonths
- the amount of months, may be negativedays
- the amount of days, may be negativehours
- the amount of hours, may be negativeminutes
- the amount of minutes, may be negativeseconds
- 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 aPeriod
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 negativemonths
- the amount of months, may be negativedays
- the amount of days, may be negativehours
- the amount of hours, may be negativeminutes
- the amount of minutes, may be negativeseconds
- the amount of seconds, may be negativenanos
- the amount of nanos, may be negative- Returns:
- the period, never null
-
of
public static Period of(PeriodProvider periodProvider)
Obtains aPeriod
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 unitsjava.lang.ArithmeticException
- if any provided amount, exceeds the supported range
-
ofDateFields
public static Period ofDateFields(int years, int months, int days)
Obtains aPeriod
from date-based fields.This creates an instance based on years, months and days.
- Parameters:
years
- the amount of years, may be negativemonths
- the amount of months, may be negativedays
- the amount of days, may be negative- Returns:
- the period, never null
-
ofDateFields
public static Period ofDateFields(PeriodProvider periodProvider)
Obtains aPeriod
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 unitsjava.lang.ArithmeticException
- if any provided amount, exceeds the supported range
-
ofTimeFields
public static Period ofTimeFields(int hours, int minutes, int seconds)
Obtains aPeriod
from time-based fields.This creates an instance based on hours, minutes and seconds.
- Parameters:
hours
- the amount of hours, may be negativeminutes
- the amount of minutes, may be negativeseconds
- 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 aPeriod
from time-based fields.This creates an instance based on hours, minutes, seconds and nanoseconds.
- Parameters:
hours
- the amount of hours, may be negativeminutes
- the amount of minutes, may be negativeseconds
- the amount of seconds, may be negativenanos
- the amount of nanos, may be negative- Returns:
- the period, never null
-
ofTimeFields
public static Period ofTimeFields(PeriodProvider periodProvider)
Obtains aPeriod
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 unitsjava.lang.ArithmeticException
- if any provided amount, exceeds the supported range
-
of
public static Period of(int amount, PeriodUnit unit)
Obtains aPeriod
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 negativeunit
- the unit that the period is measured in, not null- Returns:
- the period, never null
-
ofYears
public static Period ofYears(int years)
Obtains aPeriod
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 aPeriod
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 aPeriod
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 aPeriod
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 aPeriod
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 aPeriod
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 aPeriod
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 aPeriod
from aDuration
.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:
java.lang.ArithmeticException
- if the result exceeds the supported period range
-
between
public static Period between(DateProvider startDateProvider, DateProvider endDateProvider)
Obtains aPeriod
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
to2011-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 nullendDateProvider
- the end date, exclusive, not null- Returns:
- the period in days, never null
- Throws:
java.lang.ArithmeticException
- if the period exceeds the supported range
-
yearsBetween
public static Period yearsBetween(DateProvider startDateProvider, DateProvider endDateProvider)
Obtains aPeriod
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
to2012-01-15
is two years, whereas from2010-01-15
to2012-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 nullendDateProvider
- the end date, exclusive, not null- Returns:
- the period in days, never null
- Throws:
java.lang.ArithmeticException
- if the period exceeds the supported range
-
monthsBetween
public static Period monthsBetween(DateProvider startDateProvider, DateProvider endDateProvider)
Obtains aPeriod
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
to2010-03-15
is two months, whereas from2010-01-15
to2010-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 nullendDateProvider
- the end date, exclusive, not null- Returns:
- the period in days, never null
- Throws:
java.lang.ArithmeticException
- if the period exceeds the supported range
-
daysBetween
public static Period daysBetween(DateProvider startDateProvider, DateProvider endDateProvider)
Obtains aPeriod
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
to2010-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 nullendDateProvider
- the end date, exclusive, not null- Returns:
- the period in days, never null
- Throws:
java.lang.ArithmeticException
- if the period exceeds the supported range
-
parse
public static Period parse(java.lang.String text)
Obtains aPeriod
from a text string such asPnYnMnDTnHnMn.nS
.This will parse the string produced by
toString()
which is a subset of the ISO8601 period formatPnYnMnDTnHnMn.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 java.lang.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 anint
.- Returns:
- the amount of nanoseconds of this period
- Throws:
java.lang.ArithmeticException
- if the number of nanoseconds exceeds the capacity of anint
-
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:
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 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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of along
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:
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 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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of anint
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:
java.lang.ArithmeticException
- if the capacity of along
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:
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, never 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, never 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 toP2Y3M1DT29H1M
.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 instance is immutable and unaffected by this method call.
- Returns:
- a
Period
based on this period with the amounts normalized, never 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 toP2Y3M2DT4H
.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 instance is immutable and unaffected by this method call.
- Returns:
- a
Period
based on this period with the amounts normalized, never 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 the assumption:
- 12 months in a year
- Returns:
- the total number of years
- Throws:
java.lang.ArithmeticException
- if the capacity of along
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
- Returns:
- the total number of years
- Throws:
java.lang.ArithmeticException
- if the capacity of along
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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- Returns:
- the total number of nanoseconds
- Throws:
java.lang.ArithmeticException
- if the capacity of along
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
- Returns:
- the total number of nanoseconds
- Throws:
java.lang.ArithmeticException
- if the capacity of along
is exceeded
-
toPeriodFields
public PeriodFields toPeriodFields()
Converts this period to aPeriodFields
.The returned
PeriodFields
will only contain the non-zero amounts.- Specified by:
toPeriodFields
in interfacePeriodProvider
- 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 theaccurate
calculation if the years, months and days fields are zero.- Returns:
- the estimated duration of this period, never 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 assumptions:
- 60 minutes in an hour
- 60 seconds in a minute
- 1,000,000,000 nanoseconds in a second
- 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
- 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(java.lang.Object obj)
Is this period equal to the specified period.- Overrides:
equals
in classjava.lang.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 classjava.lang.Object
- Returns:
- a suitable hash code
-
toString
public java.lang.String toString()
Returns a string representation of the amount of time.- Overrides:
toString
in classjava.lang.Object
- Returns:
- the amount of time in ISO8601 string format
-
-