Class Period
- All Implemented Interfaces:
Serializable
,PeriodProvider
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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final int
The number of days.private final int
The number of hours.private final int
The number of minutes.private final int
The number of months.private final long
The number of nanoseconds.private PeriodFields
The cached PeriodFields.private final int
The number of seconds.private static final long
The serialization version.private String
The cached toString value.private static final PeriodUnit[]
The ISO period units, trusted to not be altered.private final int
The number of years.static final Period
A constant for a period of zero. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Period
(int years, int months, int days, int hours, int minutes, int seconds, long nanos) Constructor. -
Method Summary
Modifier and TypeMethodDescriptionstatic 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.dividedBy
(int divisor) Returns a new instance with each element in this period divided by the specified value.boolean
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
Gets the amount of minutes of this period, if any.int
Gets the amount of months of this period, if any.long
getNanos()
Gets the amount of nanoseconds of this period, if any.int
Gets the amount of nanoseconds of this period safely converted to anint
.int
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
Checks if this period is fully positive, excluding zero.boolean
Checks if this period is fully positive, including zero.boolean
isZero()
Checks if this period is zero-length.minus
(PeriodProvider periodProvider) Returns a copy of this period with the specified period subtracted.minusDays
(int days) Returns a copy of this period with the specified number of days subtracted.minusHours
(int hours) Returns a copy of this period with the specified number of hours subtracted.minusMinutes
(int minutes) Returns a copy of this period with the specified number of minutes subtracted.minusMonths
(int months) Returns a copy of this period with the specified number of months subtracted.minusNanos
(long nanos) Returns a copy of this period with the specified number of nanoseconds subtracted.minusSeconds
(int seconds) Returns a copy of this period with the specified number of seconds subtracted.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.multipliedBy
(int scalar) Returns a new instance with each element in this period multiplied by the specified scalar.negated()
Returns a new instance with each amount in this period negated.Returns a copy of this period with all amounts normalized to the standard ranges for date-time fields.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
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
Obtains aPeriod
from a text string such asPnYnMnDTnHnMn.nS
.plus
(PeriodProvider periodProvider) Returns a copy of this period with the specified period added.plusDays
(int days) Returns a copy of this period with the specified number of days added.plusHours
(int hours) Returns a copy of this period with the specified number of hours added.plusMinutes
(int minutes) Returns a copy of this period with the specified number of minutes added.plusMonths
(int months) Returns a copy of this period with the specified number of months added.plusNanos
(long nanos) Returns a copy of this period with the specified number of nanoseconds added.plusSeconds
(int seconds) Returns a copy of this period with the specified number of seconds added.plusYears
(int years) Returns a copy of this period with the specified number of years added.private Object
Resolves singletons.Calculates the accurate duration of this period.Calculates the accurate duration of this period.Estimates the duration of this period.Converts this period to aPeriodFields
.toString()
Returns a string representation of the amount of time.long
Gets the total number of days represented by this period using standard assumptions for the meaning of day, hour, minute and second.long
Gets the total number of hours represented by this period using standard assumptions for the meaning of hour, minute and second.long
Gets the total number of hours represented by this period using standard assumptions for the meaning of day, hour, minute and second.long
Gets the total number of minutes represented by this period using standard assumptions for the meaning of hour, minute and second.long
Gets the total number of minutes represented by this period using standard assumptions for the meaning of day, hour, minute and second.long
Gets the total number of months represented by this period using standard assumptions for the meaning of month.long
Gets the total number of nanoseconds represented by this period using standard assumptions for the meaning of hour, minute and second.long
Gets the total number of nanoseconds represented by this period using standard assumptions for the meaning of day, hour, minute and second.long
Gets the total number of seconds represented by this period using standard assumptions for the meaning of hour, minute and second.long
Gets the total number of seconds represented by this period using standard assumptions for the meaning of day, hour, minute and second.long
Gets the total number of years represented by this period using standard assumptions for the meaning of month.Returns a copy of this period with only the date-based fields retained.withDays
(int days) Returns a copy of this period with the specified amount of days.withHours
(int hours) Returns a copy of this period with the specified amount of hours.withMinutes
(int minutes) Returns a copy of this period with the specified amount of minutes.withMonths
(int months) Returns a copy of this period with the specified amount of months.withNanos
(long nanos) Returns a copy of this period with the specified amount of nanoseconds.withSeconds
(int seconds) Returns a copy of this period with the specified amount of seconds.Returns a copy of this period with only the time-based fields retained.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 Details
-
ZERO
A constant for a period of zero. -
serialVersionUID
private static final long serialVersionUIDThe serialization version.- See Also:
-
UNITS
The ISO period units, trusted to not be altered. -
years
private final int yearsThe number of years. -
months
private final int monthsThe number of months. -
days
private final int daysThe number of days. -
hours
private final int hoursThe number of hours. -
minutes
private final int minutesThe number of minutes. -
seconds
private final int secondsThe number of seconds. -
nanos
private final long nanosThe number of nanoseconds. -
periodFields
The cached PeriodFields. -
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 amountmonths
- the amountdays
- the amounthours
- the amountminutes
- the amountseconds
- the amountnanos
- the amount
-
-
Method Details
-
of
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
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 unitsArithmeticException
- if any provided amount, exceeds the supported range
-
ofDateFields
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
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 unitsArithmeticException
- if any provided amount, exceeds the supported range
-
ofTimeFields
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
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
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 unitsArithmeticException
- if any provided amount, exceeds the supported range
-
of
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
Obtains aPeriod
from a number of years.- Parameters:
years
- the amount of years, may be negative- Returns:
- the period, never null
-
ofMonths
Obtains aPeriod
from a number of months.- Parameters:
months
- the amount of months, may be negative- Returns:
- the period, never null
-
ofDays
Obtains aPeriod
from a number of days.- Parameters:
days
- the amount of days, may be negative- Returns:
- the period, never null
-
ofHours
Obtains aPeriod
from a number of hours.- Parameters:
hours
- the amount of hours, may be negative- Returns:
- the period, never null
-
ofMinutes
Obtains aPeriod
from a number of minutes.- Parameters:
minutes
- the amount of minutes, may be negative- Returns:
- the period, never null
-
ofSeconds
Obtains aPeriod
from a number of seconds.- Parameters:
seconds
- the amount of seconds, may be negative- Returns:
- the period, never null
-
ofNanos
Obtains aPeriod
from a number of nanoseconds.- Parameters:
nanos
- the amount of nanos, may be negative- Returns:
- the period, never null
-
of
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:
ArithmeticException
- if the result exceeds the supported period range
-
between
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:
ArithmeticException
- if the period exceeds the supported range
-
yearsBetween
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:
ArithmeticException
- if the period exceeds the supported range
-
monthsBetween
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:
ArithmeticException
- if the period exceeds the supported range
-
daysBetween
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:
ArithmeticException
- if the period exceeds the supported range
-
parse
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
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:
ArithmeticException
- if the number of nanoseconds exceeds the capacity of anint
-
withYears
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
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
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
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
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
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
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
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
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
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
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 anint
is exceeded
-
plusMonths
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 anint
is exceeded
-
plusDays
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 anint
is exceeded
-
plusHours
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 anint
is exceeded
-
plusMinutes
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 anint
is exceeded
-
plusSeconds
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 anint
is exceeded
-
plusNanos
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 along
is exceeded
-
minus
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
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 anint
is exceeded
-
minusMonths
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 anint
is exceeded
-
minusDays
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 anint
is exceeded
-
minusHours
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 anint
is exceeded
-
minusMinutes
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 anint
is exceeded
-
minusSeconds
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 anint
is exceeded
-
minusNanos
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 along
is exceeded
-
multipliedBy
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
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
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
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:
ArithmeticException
- if the capacity of any field is exceeded
-
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:
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:
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:
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:
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:
ArithmeticException
- if the capacity of along
is exceeded
-
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
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:
ArithmeticException
- if the calculation overflows
-
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
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
Is this period equal to the specified period. -
hashCode
public int hashCode()Returns the hash code for this period. -
toString
Returns a string representation of the amount of time.
-