A period in Joda-Time represents a period of time defined in terms of fields, for example, 3 years 5 months 2 days and 7 hours. This differs from a duration in that it is inexact in terms of milliseconds. A period can only be resolved to an exact number of milliseconds by specifying the instant (including chronology and time zone) it is relative to.
For example, consider a period of 1 month. If you add this period to the 1st February (ISO) then you will get the 1st March. If you add the same period to the 1st March you will get the 1st April. But the duration added (in milliseconds) in these two cases is very different.
As a second example, consider adding 1 day at the daylight savings boundary. If you use a period to do the addition then either 23 or 25 hours will be added as appropriate. If you had created a duration equal to 24 hours, then you would end up with the wrong result.
Periods are implemented as a set of int
fields.
The standard set of fields in a period are years, months, weeks, days, hours, minutes, seconds and millis.
The PeriodType class allows this set
of fields to be restricted, for example to elimate weeks.
This is significant when converting a duration or interval to a period, as the calculation
needs to know which period fields it should populate.
Methods exist on periods to obtain each field value.
Periods do not have a chronology or time zone.
You cannot compare periods for order (ie. they do not implement Comparable
).
Periods can be added to an instant, or to either end of an interval to change those objects. In datetime maths you could say:
instant + period = instant
Within Joda-Time a period is represented by the ReadablePeriod interface. There are two implementations of the interface provided:
The code can be used in various ways:
DateTime start = new DateTime(2004, 12, 25, 0, 0, 0, 0); DateTime end = new DateTime(2006, 1, 1, 0, 0, 0, 0); // period of 1 year and 7 days Period period = new Period(start, end); // calc will equal end DateTime calc = start.plus(period);
Note that the interface ReadablePeriod
should not be used like the collections API.
The interface only contains the core subset of the operations.
Instead, you should usually refer directly to the implementation classes in your APIs.