public final class Period extends BasePeriod implements ReadablePeriod, Serializable
A time period is divided into a number of fields, such as hours and seconds. Which fields are supported is defined by the PeriodType class. The default is the standard period type, which supports years, months, weeks, days, hours, minutes, seconds and millis.
When this time period is added to an instant, the effect is of adding each field in turn.
As a result, this takes into account daylight savings time.
Adding a time period of 1 day to the day before daylight savings starts will only add
23 hours rather than 24 to ensure that the time remains the same.
If this is not the behaviour you want, then see Duration
.
The definition of a period also affects the equals method. A period of 1 day is not equal to a period of 24 hours, nor 1 hour equal to 60 minutes. This is because periods represent an abstracted definition of a time period (eg. a day may not actually be 24 hours, it might be 23 or 25 at daylight savings boundary). To compare the actual duration of two periods, convert both to durations using toDuration, an operation that emphasises that the result may differ according to the date you choose.
Period is threadsafe and immutable, provided that the PeriodType is as well. All standard PeriodType classes supplied are threadsafe and immutable.
MutablePeriod
,
Serialized FormModifier and Type  Field and Description 

static Period 
ZERO
A period of zero length and standard period type.

Constructor and Description 

Period()
Creates a new empty period with the standard set of fields.

Period(int hours,
int minutes,
int seconds,
int millis)
Create a period from a set of field values using the standard set of fields.

Period(int years,
int months,
int weeks,
int days,
int hours,
int minutes,
int seconds,
int millis)
Create a period from a set of field values using the standard set of fields.

Period(int years,
int months,
int weeks,
int days,
int hours,
int minutes,
int seconds,
int millis,
PeriodType type)
Create a period from a set of field values.

Period(long duration)
Creates a period from the given millisecond duration using the standard
set of fields.

Period(long duration,
Chronology chronology)
Creates a period from the given millisecond duration using the standard
set of fields.

Period(long startInstant,
long endInstant)
Creates a period from the given interval endpoints using the standard
set of fields.

Period(long startInstant,
long endInstant,
Chronology chrono)
Creates a period from the given interval endpoints using the standard
set of fields.

Period(long startInstant,
long endInstant,
PeriodType type)
Creates a period from the given interval endpoints.

Period(long startInstant,
long endInstant,
PeriodType type,
Chronology chrono)
Creates a period from the given interval endpoints.

Period(long duration,
PeriodType type)
Creates a period from the given millisecond duration.

Period(long duration,
PeriodType type,
Chronology chronology)
Creates a period from the given millisecond duration.

Period(Object period)
Creates a period by converting or copying from another object.

Period(Object period,
Chronology chrono)
Creates a period by converting or copying from another object.

Period(Object period,
PeriodType type)
Creates a period by converting or copying from another object.

Period(Object period,
PeriodType type,
Chronology chrono)
Creates a period by converting or copying from another object.

Period(ReadableDuration duration,
ReadableInstant endInstant)
Creates a period from the given duration and end point.

Period(ReadableDuration duration,
ReadableInstant endInstant,
PeriodType type)
Creates a period from the given duration and end point.

Period(ReadableInstant startInstant,
ReadableDuration duration)
Creates a period from the given start point and the duration.

Period(ReadableInstant startInstant,
ReadableDuration duration,
PeriodType type)
Creates a period from the given start point and the duration.

Period(ReadableInstant startInstant,
ReadableInstant endInstant)
Creates a period between the given instants using the standard set of fields.

Period(ReadableInstant startInstant,
ReadableInstant endInstant,
PeriodType type)
Creates a period between the given instants.

Period(ReadablePartial start,
ReadablePartial end)
Creates a period from two partially specified times.

Period(ReadablePartial start,
ReadablePartial end,
PeriodType type)
Creates a period from two partially specified times.

Modifier and Type  Method and Description 

static Period 
days(int days)
Create a period with a specified number of days.

static Period 
fieldDifference(ReadablePartial start,
ReadablePartial end)
Creates a period from two partially specified times, calculating
by field difference.

int 
getDays()
Gets the days field part of the period.

int 
getHours()
Gets the hours field part of the period.

int 
getMillis()
Gets the millis field part of the period.

int 
getMinutes()
Gets the minutes field part of the period.

int 
getMonths()
Gets the months field part of the period.

int 
getSeconds()
Gets the seconds field part of the period.

int 
getWeeks()
Gets the weeks field part of the period.

int 
getYears()
Gets the years field part of the period.

static Period 
hours(int hours)
Create a period with a specified number of hours.

static Period 
millis(int millis)
Create a period with a specified number of millis.

Period 
minus(ReadablePeriod period)
Returns a new period with the specified period subtracted.

Period 
minusDays(int days)
Returns a new period minus the specified number of days taken away.

Period 
minusHours(int hours)
Returns a new period minus the specified number of hours taken away.

Period 
minusMillis(int millis)
Returns a new period minus the specified number of millis taken away.

Period 
minusMinutes(int minutes)
Returns a new period minus the specified number of minutes taken away.

Period 
minusMonths(int months)
Returns a new period minus the specified number of months taken away.

Period 
minusSeconds(int seconds)
Returns a new period minus the specified number of seconds taken away.

Period 
minusWeeks(int weeks)
Returns a new period minus the specified number of weeks taken away.

Period 
minusYears(int years)
Returns a new period with the specified number of years taken away.

static Period 
minutes(int minutes)
Create a period with a specified number of minutes.

static Period 
months(int months)
Create a period with a specified number of months.

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 
normalizedStandard()
Normalizes this period using standard rules, assuming a 12 month year,
7 day week, 24 hour day, 60 minute hour and 60 second minute.

Period 
normalizedStandard(PeriodType type)
Normalizes this period using standard rules, assuming a 12 month year,
7 day week, 24 hour day, 60 minute hour and 60 second minute,
providing control over how the result is split into fields.

static Period 
parse(String str)
Parses a
Period from the specified string. 
static Period 
parse(String str,
PeriodFormatter formatter)
Parses a
Period from the specified string using a formatter. 
Period 
plus(ReadablePeriod period)
Returns a new period with the specified period added.

Period 
plusDays(int days)
Returns a new period plus the specified number of days added.

Period 
plusHours(int hours)
Returns a new period plus the specified number of hours added.

Period 
plusMillis(int millis)
Returns a new period plus the specified number of millis added.

Period 
plusMinutes(int minutes)
Returns a new period plus the specified number of minutes added.

Period 
plusMonths(int months)
Returns a new period plus the specified number of months added.

Period 
plusSeconds(int seconds)
Returns a new period plus the specified number of seconds added.

Period 
plusWeeks(int weeks)
Returns a new period plus the specified number of weeks added.

Period 
plusYears(int years)
Returns a new period with the specified number of years added.

static Period 
seconds(int seconds)
Create a period with a specified number of seconds.

Period 
toPeriod()
Get this period as an immutable
Period object
by returning this . 
Days 
toStandardDays()
Converts this period to a period in days assuming a
7 day week, 24 hour day, 60 minute hour and 60 second minute.

Duration 
toStandardDuration()
Converts this period to a duration assuming a
7 day week, 24 hour day, 60 minute hour and 60 second minute.

Hours 
toStandardHours()
Converts this period to a period in hours assuming a
7 day week, 24 hour day, 60 minute hour and 60 second minute.

Minutes 
toStandardMinutes()
Converts this period to a period in minutes assuming a
7 day week, 24 hour day, 60 minute hour and 60 second minute.

Seconds 
toStandardSeconds()
Converts this period to a period in seconds assuming a
7 day week, 24 hour day, 60 minute hour and 60 second minute.

Weeks 
toStandardWeeks()
Converts this period to a period in weeks assuming a
7 day week, 24 hour day, 60 minute hour and 60 second minute.

static Period 
weeks(int weeks)
Create a period with a specified number of weeks.

Period 
withDays(int days)
Returns a new period with the specified number of days.

Period 
withField(DurationFieldType field,
int value)
Creates a new Period instance with the specified field set to a new value.

Period 
withFieldAdded(DurationFieldType field,
int value)
Creates a new Period instance with the valueToAdd added to the specified field.

Period 
withFields(ReadablePeriod period)
Creates a new Period instance with the fields from the specified period
copied on top of those from this period.

Period 
withHours(int hours)
Returns a new period with the specified number of hours.

Period 
withMillis(int millis)
Returns a new period with the specified number of millis.

Period 
withMinutes(int minutes)
Returns a new period with the specified number of minutes.

Period 
withMonths(int months)
Returns a new period with the specified number of months.

Period 
withPeriodType(PeriodType type)
Creates a new Period instance with the same field values but
different PeriodType.

Period 
withSeconds(int seconds)
Returns a new period with the specified number of seconds.

Period 
withWeeks(int weeks)
Returns a new period with the specified number of weeks.

Period 
withYears(int years)
Returns a new period with the specified number of years.

static Period 
years(int years)
Create a period with a specified number of years.

addField, addFieldInto, addPeriod, addPeriodInto, checkPeriodType, getPeriodType, getValue, mergePeriod, mergePeriodInto, setField, setFieldInto, setPeriod, setPeriod, setValue, setValues, toDurationFrom, toDurationTo
equals, get, getFieldType, getFieldTypes, getValues, hashCode, indexOf, isSupported, size, toMutablePeriod, toString, toString
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
equals, get, getFieldType, getPeriodType, getValue, hashCode, isSupported, size, toMutablePeriod, toString
public static final Period ZERO
public Period()
One way to initialise a period is as follows:
Period = new Period().withYears(6).withMonths(3).withSeconds(23);Bear in mind that this creates four period instances in total, three of which are immediately discarded. The alternative is more efficient, but less readable:
Period = new Period(6, 3, 0, 0, 0, 0, 23, 0);The following is also slightly less wasteful:
Period = Period.years(6).withMonths(3).withSeconds(23);
public Period(int hours, int minutes, int seconds, int millis)
hours
 amount of hours in this periodminutes
 amount of minutes in this periodseconds
 amount of seconds in this periodmillis
 amount of milliseconds in this periodpublic Period(int years, int months, int weeks, int days, int hours, int minutes, int seconds, int millis)
years
 amount of years in this periodmonths
 amount of months in this periodweeks
 amount of weeks in this perioddays
 amount of days in this periodhours
 amount of hours in this periodminutes
 amount of minutes in this periodseconds
 amount of seconds in this periodmillis
 amount of milliseconds in this periodpublic Period(int years, int months, int weeks, int days, int hours, int minutes, int seconds, int millis, PeriodType type)
There is usually little need to use this constructor. The period type is used primarily to define how to split an interval into a period. As this constructor already is split, the period type does no real work.
years
 amount of years in this period, which must be zero if unsupportedmonths
 amount of months in this period, which must be zero if unsupportedweeks
 amount of weeks in this period, which must be zero if unsupporteddays
 amount of days in this period, which must be zero if unsupportedhours
 amount of hours in this period, which must be zero if unsupportedminutes
 amount of minutes in this period, which must be zero if unsupportedseconds
 amount of seconds in this period, which must be zero if unsupportedmillis
 amount of milliseconds in this period, which must be zero if unsupportedtype
 which set of fields this period supports, null means AllTypeIllegalArgumentException
 if an unsupported field's value is nonzeropublic Period(long duration)
Only precise fields in the period type will be used. For the standard period type this is the time fields only. Thus the year, month, week and day fields will not be populated.
If the duration is small, less than one day, then this method will perform as you might expect and split the fields evenly.
If the duration is larger than one day then all the remaining duration will be stored in the largest available precise field, hours in this case.
For example, a duration equal to (365 + 60 + 5) days will be converted to ((365 + 60 + 5) * 24) hours by this constructor.
For more control over the conversion process, you have two options:
Interval
, and from there obtain the period
duration
 the duration, in millisecondspublic Period(long duration, PeriodType type)
Only precise fields in the period type will be used. Imprecise fields will not be populated.
If the duration is small then this method will perform as you might expect and split the fields evenly.
If the duration is large then all the remaining duration will be stored in the largest available precise field. For details as to which fields are precise, review the period type javadoc.
duration
 the duration, in millisecondstype
 which set of fields this period supports, null means standardpublic Period(long duration, Chronology chronology)
Only precise fields in the period type will be used. Imprecise fields will not be populated.
If the duration is small then this method will perform as you might expect and split the fields evenly.
If the duration is large then all the remaining duration will be stored in the largest available precise field. For details as to which fields are precise, review the period type javadoc.
duration
 the duration, in millisecondschronology
 the chronology to use to split the duration, null means ISO defaultpublic Period(long duration, PeriodType type, Chronology chronology)
Only precise fields in the period type will be used. Imprecise fields will not be populated.
If the duration is small then this method will perform as you might expect and split the fields evenly.
If the duration is large then all the remaining duration will be stored in the largest available precise field. For details as to which fields are precise, review the period type javadoc.
duration
 the duration, in millisecondstype
 which set of fields this period supports, null means standardchronology
 the chronology to use to split the duration, null means ISO defaultpublic Period(long startInstant, long endInstant)
startInstant
 interval start, in millisecondsendInstant
 interval end, in millisecondspublic Period(long startInstant, long endInstant, PeriodType type)
startInstant
 interval start, in millisecondsendInstant
 interval end, in millisecondstype
 which set of fields this period supports, null means standardpublic Period(long startInstant, long endInstant, Chronology chrono)
startInstant
 interval start, in millisecondsendInstant
 interval end, in millisecondschrono
 the chronology to use, null means ISO in default zonepublic Period(long startInstant, long endInstant, PeriodType type, Chronology chrono)
startInstant
 interval start, in millisecondsendInstant
 interval end, in millisecondstype
 which set of fields this period supports, null means standardchrono
 the chronology to use, null means ISO in default zonepublic Period(ReadableInstant startInstant, ReadableInstant endInstant)
Most calculations performed by this method have obvious results. The special case is where the calculation is from a "long" month to a "short" month. Here, the result favours increasing the months field rather than the days. For example, 20130131 to 20130228 is treated as one whole month. By contrast, 20130131 to 20130330 is treated as one month and 30 days (exposed as 4 weeks and 2 days). The results are explained by considering that the start date plus the calculated period result in the end date.
Another special case is around daylight savings. Consider the case where there is a DST gap from 01:00 to 02:00. The period from 00:30 to 02:30 will return one hour, not two, due to the missing hour. However, once the period exceeds one day, a different effect comes into play. Consider the period from 00:30 just before the DST gap to 02:30 one day later. Since this exceeds a day, the algorithm first adds one day following normal period rules, to get 00:30 one day later, and then adds 2 hours to reach 02:30. In this way, the DST gap effectively "disappears". In other words, the addition of days takes precedence over the addition of hours.
startInstant
 interval start, null means nowendInstant
 interval end, null means nowpublic Period(ReadableInstant startInstant, ReadableInstant endInstant, PeriodType type)
Most calculations performed by this method have obvious results. The special case is where the calculation is from a "long" month to a "short" month. Here, the result favours increasing the months field rather than the days. For example, 20130131 to 20130228 is treated as one whole month. By contrast, 20130131 to 20130330 is treated as one month and 30 days. The results are explained by considering that the start date plus the calculated period result in the end date.
Another special case is around daylight savings. Consider the case where there is a DST gap from 01:00 to 02:00. The period from 00:30 to 02:30 will return one hour, not two, due to the missing hour. However, once the period exceeds one day, a different effect comes into play. Consider the period from 00:30 just before the DST gap to 02:30 one day later. Since this exceeds a day, the algorithm first adds one day following normal period rules, to get 00:30 one day later, and then adds 2 hours to reach 02:30. In this way, the DST gap effectively "disappears". In other words, the addition of days takes precedence over the addition of hours.
startInstant
 interval start, null means nowendInstant
 interval end, null means nowtype
 which set of fields this period supports, null means standardpublic Period(ReadablePartial start, ReadablePartial end)
The two partials must contain the same fields, thus you can specify
two LocalDate
objects, or two LocalTime
objects,
but not one of each.
As these are Partial objects, time zones have no effect on the result.
The two partials must also both be contiguous  see
DateTimeUtils.isContiguous(ReadablePartial)
for a definition.
Both LocalDate
and LocalTime
are contiguous.
Most calculations performed by this method have obvious results. The special case is where the calculation is from a "long" month to a "short" month. Here, the result favours increasing the months field rather than the days. For example, 20130131 to 20130228 is treated as one whole month. By contrast, 20130131 to 20130330 is treated as one month and 30 days (exposed as 4 weeks and 2 days). The results are explained by considering that the start date plus the calculated period result in the end date.
An alternative way of constructing a Period from two Partials
is fieldDifference(ReadablePartial, ReadablePartial)
.
That method handles all kinds of partials.
start
 the start of the period, must not be nullend
 the end of the period, must not be nullIllegalArgumentException
 if the partials are null or invalidpublic Period(ReadablePartial start, ReadablePartial end, PeriodType type)
The two partials must contain the same fields, thus you can specify
two LocalDate
objects, or two LocalTime
objects,
but not one of each.
As these are Partial objects, time zones have no effect on the result.
The two partials must also both be contiguous  see
DateTimeUtils.isContiguous(ReadablePartial)
for a definition.
Both LocalDate
and LocalTime
are contiguous.
Most calculations performed by this method have obvious results. The special case is where the calculation is from a "long" month to a "short" month. Here, the result favours increasing the months field rather than the days. For example, 20130131 to 20130228 is treated as one whole month. By contrast, 20130131 to 20130330 is treated as one month and 30 days. The results are explained by considering that the start date plus the calculated period result in the end date.
An alternative way of constructing a Period from two Partials
is fieldDifference(ReadablePartial, ReadablePartial)
.
That method handles all kinds of partials.
start
 the start of the period, must not be nullend
 the end of the period, must not be nulltype
 which set of fields this period supports, null means standardIllegalArgumentException
 if the partials are null or invalidpublic Period(ReadableInstant startInstant, ReadableDuration duration)
startInstant
 the interval start, null means nowduration
 the duration of the interval, null means zerolengthpublic Period(ReadableInstant startInstant, ReadableDuration duration, PeriodType type)
startInstant
 the interval start, null means nowduration
 the duration of the interval, null means zerolengthtype
 which set of fields this period supports, null means standardpublic Period(ReadableDuration duration, ReadableInstant endInstant)
duration
 the duration of the interval, null means zerolengthendInstant
 the interval end, null means nowpublic Period(ReadableDuration duration, ReadableInstant endInstant, PeriodType type)
duration
 the duration of the interval, null means zerolengthendInstant
 the interval end, null means nowtype
 which set of fields this period supports, null means standardpublic Period(Object period)
The recognised object types are defined in
ConverterManager
and
include ReadablePeriod, ReadableInterval and String.
The String formats are described by ISOPeriodFormat.standard()
.
period
 period to convertIllegalArgumentException
 if period is invalidUnsupportedOperationException
 if an unsupported field's value is nonzeropublic Period(Object period, PeriodType type)
The recognised object types are defined in
ConverterManager
and
include ReadablePeriod, ReadableInterval and String.
The String formats are described by ISOPeriodFormat.standard()
.
period
 period to converttype
 which set of fields this period supports, null means use converterIllegalArgumentException
 if period is invalidUnsupportedOperationException
 if an unsupported field's value is nonzeropublic Period(Object period, Chronology chrono)
The recognised object types are defined in
ConverterManager
and
include ReadablePeriod, ReadableInterval and String.
The String formats are described by ISOPeriodFormat.standard()
.
period
 period to convertchrono
 the chronology to use, null means ISO in default zoneIllegalArgumentException
 if period is invalidUnsupportedOperationException
 if an unsupported field's value is nonzeropublic Period(Object period, PeriodType type, Chronology chrono)
The recognised object types are defined in
ConverterManager
and
include ReadablePeriod, ReadableInterval and String.
The String formats are described by ISOPeriodFormat.standard()
.
period
 period to converttype
 which set of fields this period supports, null means use converterchrono
 the chronology to use, null means ISO in default zoneIllegalArgumentException
 if period is invalidUnsupportedOperationException
 if an unsupported field's value is nonzeropublic static Period parse(String str)
Period
from the specified string.
This uses ISOPeriodFormat.standard()
.
str
 the string to parse, not nullpublic static Period parse(String str, PeriodFormatter formatter)
Period
from the specified string using a formatter.str
 the string to parse, not nullformatter
 the formatter to use, not nullpublic static Period years(int years)
The standard period type is used, thus you can add other fields such
as months or days using the withXxx()
methods.
For example, Period.years(2).withMonths(6);
If you want a yearbased period that cannot have other fields added,
then you should consider using Years
.
years
 the amount of years in this periodpublic static Period months(int months)
The standard period type is used, thus you can add other fields such
as years or days using the withXxx()
methods.
For example, Period.months(2).withDays(6);
If you want a monthbased period that cannot have other fields added,
then you should consider using Months
.
months
 the amount of months in this periodpublic static Period weeks(int weeks)
The standard period type is used, thus you can add other fields such
as months or days using the withXxx()
methods.
For example, Period.weeks(2).withDays(6);
If you want a weekbased period that cannot have other fields added,
then you should consider using Weeks
.
weeks
 the amount of weeks in this periodpublic static Period days(int days)
The standard period type is used, thus you can add other fields such
as months or weeks using the withXxx()
methods.
For example, Period.days(2).withHours(6);
If you want a daybased period that cannot have other fields added,
then you should consider using Days
.
days
 the amount of days in this periodpublic static Period hours(int hours)
The standard period type is used, thus you can add other fields such
as months or days using the withXxx()
methods.
For example, Period.hours(2).withMinutes(30);
If you want a hourbased period that cannot have other fields added,
then you should consider using Hours
.
hours
 the amount of hours in this periodpublic static Period minutes(int minutes)
The standard period type is used, thus you can add other fields such
as days or hours using the withXxx()
methods.
For example, Period.minutes(2).withSeconds(30);
If you want a minutebased period that cannot have other fields added,
then you should consider using Minutes
.
minutes
 the amount of minutes in this periodpublic static Period seconds(int seconds)
The standard period type is used, thus you can add other fields such
as days or hours using the withXxx()
methods.
For example, Period.seconds(2).withMillis(30);
If you want a secondbased period that cannot have other fields added,
then you should consider using Seconds
.
seconds
 the amount of seconds in this periodpublic static Period millis(int millis)
The standard period type is used, thus you can add other fields such
as days or hours using the withXxx()
methods.
For example, Period.millis(20).withSeconds(30);
millis
 the amount of millis in this periodpublic static Period fieldDifference(ReadablePartial start, ReadablePartial end)
The two partials must contain the same fields, thus you can specify
two LocalDate
objects, or two LocalTime
objects,
but not one of each. Also, the partial may not contain overlapping
fields, such as dayOfWeek and dayOfMonth.
Calculation by field difference works by extracting the difference one field at a time and not wrapping into other fields. Thus 20050609/20070412 will yield P2Y2M3D.
For example, you have an event that always runs from the 27th of each month to the 2nd of the next month. If you calculate this period using a standard constructor, then you will get between P3D and P6D depending on the month. If you use this method, then you will get P1M25D. This fielddifference based period can be successfully applied to each month of the year to obtain the correct end date for a given start date.
start
 the start of the period, must not be nullend
 the end of the period, must not be nullIllegalArgumentException
 if the partials are null or invalidpublic Period toPeriod()
Period
object
by returning this
.toPeriod
in interface ReadablePeriod
toPeriod
in class AbstractPeriod
this
public int getYears()
public int getMonths()
public int getWeeks()
public int getDays()
public int getHours()
public int getMinutes()
public int getSeconds()
public int getMillis()
public Period withPeriodType(PeriodType type)
This period instance is immutable and unaffected by this method call.
type
 the period type to use, null means standardIllegalArgumentException
 if the new period won't accept all of the current fieldspublic Period withFields(ReadablePeriod period)
This period instance is immutable and unaffected by this method call.
period
 the period to copy from, null ignoredIllegalArgumentException
 if a field type is unsupportedpublic Period withField(DurationFieldType field, int value)
This period instance is immutable and unaffected by this method call.
field
 the field to set, not nullvalue
 the value to set toIllegalArgumentException
 if the field type is null or unsupportedpublic Period withFieldAdded(DurationFieldType field, int value)
This period instance is immutable and unaffected by this method call.
field
 the field to set, not nullvalue
 the value to addIllegalArgumentException
 if the field type is null or unsupportedpublic Period withYears(int years)
This period instance is immutable and unaffected by this method call.
years
 the amount of years to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period withMonths(int months)
This period instance is immutable and unaffected by this method call.
months
 the amount of months to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period withWeeks(int weeks)
This period instance is immutable and unaffected by this method call.
weeks
 the amount of weeks to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period withDays(int days)
This period instance is immutable and unaffected by this method call.
days
 the amount of days to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period withHours(int hours)
This period instance is immutable and unaffected by this method call.
hours
 the amount of hours to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period withMinutes(int minutes)
This period instance is immutable and unaffected by this method call.
minutes
 the amount of minutes to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period withSeconds(int seconds)
This period instance is immutable and unaffected by this method call.
seconds
 the amount of seconds to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period withMillis(int millis)
This period instance is immutable and unaffected by this method call.
millis
 the amount of millis to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period plus(ReadablePeriod period)
Each field of the period is added separately. Thus a period of
2 hours 30 minutes plus 3 hours 40 minutes will produce a result
of 5 hours 70 minutes  see normalizedStandard()
.
If the period being added contains a nonzero amount for a field that is not supported in this period then an exception is thrown.
This period instance is immutable and unaffected by this method call.
period
 the period to add, null adds zero and returns thisUnsupportedOperationException
 if any field is not supportedpublic Period plusYears(int years)
This period instance is immutable and unaffected by this method call.
years
 the amount of years to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period plusMonths(int months)
This period instance is immutable and unaffected by this method call.
months
 the amount of months to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period plusWeeks(int weeks)
This period instance is immutable and unaffected by this method call.
weeks
 the amount of weeks to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period plusDays(int days)
This period instance is immutable and unaffected by this method call.
days
 the amount of days to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period plusHours(int hours)
This period instance is immutable and unaffected by this method call.
hours
 the amount of hours to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period plusMinutes(int minutes)
This period instance is immutable and unaffected by this method call.
minutes
 the amount of minutes to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period plusSeconds(int seconds)
This period instance is immutable and unaffected by this method call.
seconds
 the amount of seconds to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period plusMillis(int millis)
This period instance is immutable and unaffected by this method call.
millis
 the amount of millis to add, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period minus(ReadablePeriod period)
Each field of the period is subtracted separately. Thus a period of
3 hours 30 minutes minus 2 hours 40 minutes will produce a result
of 1 hour and 10 minutes  see normalizedStandard()
.
If the period being added contains a nonzero amount for a field that is not supported in this period then an exception is thrown.
This period instance is immutable and unaffected by this method call.
period
 the period to add, null adds zero and returns thisUnsupportedOperationException
 if any field is not supportedpublic Period minusYears(int years)
This period instance is immutable and unaffected by this method call.
years
 the amount of years to take away, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period minusMonths(int months)
This period instance is immutable and unaffected by this method call.
months
 the amount of months to take away, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period minusWeeks(int weeks)
This period instance is immutable and unaffected by this method call.
weeks
 the amount of weeks to take away, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period minusDays(int days)
This period instance is immutable and unaffected by this method call.
days
 the amount of days to take away, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period minusHours(int hours)
This period instance is immutable and unaffected by this method call.
hours
 the amount of hours to take away, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period minusMinutes(int minutes)
This period instance is immutable and unaffected by this method call.
minutes
 the amount of minutes to take away, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period minusSeconds(int seconds)
This period instance is immutable and unaffected by this method call.
seconds
 the amount of seconds to take away, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period minusMillis(int millis)
This period instance is immutable and unaffected by this method call.
millis
 the amount of millis to take away, may be negativeUnsupportedOperationException
 if the field is not supportedpublic Period multipliedBy(int scalar)
scalar
 the scalar to multiply by, not nullPeriod
based on this period with the amounts multiplied by the scalar, never nullArithmeticException
 if the capacity of any field is exceededpublic Period negated()
Period
based on this period with the amounts negated, never nullArithmeticException
 if any field has the minimum valuepublic Weeks toStandardWeeks()
This method allows you to convert between different types of period. However to achieve this it makes the assumption that all weeks are 7 days, all days are 24 hours, all hours are 60 minutes and all minutes are 60 seconds. This is not true when daylight savings time is considered, and may also not be true for some unusual chronologies. However, it is included as it is a useful operation for many applications and business rules.
If the period contains years or months, an exception will be thrown.
UnsupportedOperationException
 if the period contains years or monthsArithmeticException
 if the number of weeks is too large to be representedpublic Days toStandardDays()
This method allows you to convert between different types of period. However to achieve this it makes the assumption that all weeks are 7 days, all days are 24 hours, all hours are 60 minutes and all minutes are 60 seconds. This is not true when daylight savings time is considered, and may also not be true for some unusual chronologies. However, it is included as it is a useful operation for many applications and business rules.
If the period contains years or months, an exception will be thrown.
UnsupportedOperationException
 if the period contains years or monthsArithmeticException
 if the number of days is too large to be representedpublic Hours toStandardHours()
This method allows you to convert between different types of period. However to achieve this it makes the assumption that all weeks are 7 days, all days are 24 hours, all hours are 60 minutes and all minutes are 60 seconds. This is not true when daylight savings time is considered, and may also not be true for some unusual chronologies. However, it is included as it is a useful operation for many applications and business rules.
If the period contains years or months, an exception will be thrown.
UnsupportedOperationException
 if the period contains years or monthsArithmeticException
 if the number of hours is too large to be representedpublic Minutes toStandardMinutes()
This method allows you to convert between different types of period. However to achieve this it makes the assumption that all weeks are 7 days, all days are 24 hours, all hours are 60 minutes and all minutes are 60 seconds. This is not true when daylight savings time is considered, and may also not be true for some unusual chronologies. However, it is included as it is a useful operation for many applications and business rules.
If the period contains years or months, an exception will be thrown.
UnsupportedOperationException
 if the period contains years or monthsArithmeticException
 if the number of minutes is too large to be representedpublic Seconds toStandardSeconds()
This method allows you to convert between different types of period. However to achieve this it makes the assumption that all weeks are 7 days, all days are 24 hours, all hours are 60 minutes and all minutes are 60 seconds. This is not true when daylight savings time is considered, and may also not be true for some unusual chronologies. However, it is included as it is a useful operation for many applications and business rules.
If the period contains years or months, an exception will be thrown.
UnsupportedOperationException
 if the period contains years or monthsArithmeticException
 if the number of seconds is too large to be representedpublic Duration toStandardDuration()
This method allows you to convert from a period to a duration. However to achieve this it makes the assumption that all weeks are 7 days, all days are 24 hours, all hours are 60 minutes and all minutes are 60 seconds. This is not true when daylight savings time is considered, and may also not be true for some unusual chronologies. However, it is included as it is a useful operation for many applications and business rules.
If the period contains years or months, an exception will be thrown.
UnsupportedOperationException
 if the period contains years or monthspublic Period normalizedStandard()
This method allows you to normalize a period. However to achieve this it makes the assumption that all years are 12 months, all weeks are 7 days, all days are 24 hours, all hours are 60 minutes and all minutes are 60 seconds. This is not true when daylight savings time is considered, and may also not be true for some chronologies. However, it is included as it is a useful operation for many applications and business rules.
If the period contains years or months, then the months will be normalized to be between 0 and 11. The days field and below will be normalized as necessary, however this will not overflow into the months field. Thus a period of 1 year 15 months will normalize to 2 years 3 months. But a period of 1 month 40 days will remain as 1 month 40 days.
The result will always have a PeriodType
of standard, thus
days will be grouped into weeks.
ArithmeticException
 if any field is too large to be representedpublic Period normalizedStandard(PeriodType type)
This method allows you to normalize a period. However to achieve this it makes the assumption that all years are 12 months, all weeks are 7 days, all days are 24 hours, all hours are 60 minutes and all minutes are 60 seconds. This is not true when daylight savings time is considered, and may also not be true for some chronologies. However, it is included as it is a useful operation for many applications and business rules.
If the period contains years or months, then the months will be normalized to be between 0 and 11. The days field and below will be normalized as necessary, however this will not overflow into the months field. Thus a period of 1 year 15 months will normalize to 2 years 3 months. But a period of 1 month 40 days will remain as 1 month 40 days.
The PeriodType parameter controls how the result is created. It allows
you to omit certain fields from the result if desired. For example,
you may not want the result to include weeks, in which case you pass
in PeriodType.yearMonthDayTime()
.
type
 the period type of the new period, null means standard typeArithmeticException
 if any field is too large to be representedUnsupportedOperationException
 if this period contains nonzero
years or months but the specified period type does not support themCopyright © 2002–2023 Joda.org. All rights reserved.