Period

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> org >> joda >> [ time overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

SOURCE |

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.joda.time
Class Period

java.lang.Object
  org.joda.time.base.AbstractPeriod
      org.joda.time.base.BasePeriod
          org.joda.time.Period

All Implemented Interfaces:: ReadablePeriod, java.io.Serializable

public final class Period
extends org.joda.time.base.BasePeriod
implements ReadablePeriod, java.io.Serializable

An immutable time period specifying a set of duration field values.

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 thread-safe and immutable, provided that the PeriodType is as well. All standard PeriodType classes supplied are thread-safe and immutable.

Since:: 1.0

Field Summary

private static long serialVersionUID
          Serialization version

Fields inherited from class org.joda.time.base.BasePeriod

Constructor Summary

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

private Period(int[] values, PeriodType type)
          Constructor used when we trust ourselves.

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(java.lang.Object period)
          Creates a period from the specified object using the ConverterManager.

Period(java.lang.Object period, Chronology chrono)
          Creates a period from the specified object using the ConverterManager.

Period(java.lang.Object period, PeriodType type)
          Creates a period from the specified object using the ConverterManager.

Period(java.lang.Object period, PeriodType type, Chronology chrono)
          Creates a period from the specified object using the ConverterManager.

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 from the given interval endpoints using the standard set of fields.

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

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.

Method Summary

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 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 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.

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.

Methods inherited from class org.joda.time.base.BasePeriod

addField, addFieldInto, addPeriod, addPeriodInto, checkPeriodType, getFieldType, getPeriodType, getValue, mergePeriod, mergePeriodInto, setField, setFieldInto, setPeriod, setPeriod, setValue, setValues, size, toDurationFrom, toDurationTo

Methods inherited from class org.joda.time.base.AbstractPeriod

equals, get, getFieldTypes, getValues, hashCode, indexOf, isSupported, toMutablePeriod, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.joda.time.ReadablePeriod

equals, get, getFieldType, getPeriodType, getValue, hashCode, isSupported, size, toMutablePeriod, toString

Field Detail

serialVersionUID

private static final long serialVersionUID

Serialization version

See Also:: Constant Field Values

Constructor Detail

Period

public Period()

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

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 alterative 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);

Period

public Period(int hours,
              int minutes,
              int seconds,
              int millis)

Create a period from a set of field values using the standard set of fields. Note that the parameters specify the time fields hours, minutes, seconds and millis, not the date fields.

Period

public 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

public 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.

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.

Period

public Period(long duration)

Creates a period from the given millisecond duration using the standard set of fields.

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:

convert the duration to an Interval, and from there obtain the period
specify a period type that contains precise definitions of the day and larger fields, such as UTC

Period

public Period(long duration,
              PeriodType type)

Creates a period from the given millisecond duration.

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.

Period

public Period(long duration,
              Chronology chronology)

Creates a period from the given millisecond duration using the standard set of fields.

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.

Period

public Period(long duration,
              PeriodType type,
              Chronology chronology)

Creates a period from the given millisecond duration.

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.

Period

public Period(long startInstant,
              long endInstant)

Creates a period from the given interval endpoints using the standard set of fields.

Period

public Period(long startInstant,
              long endInstant,
              PeriodType type)

Creates a period from the given interval endpoints.

Period

public Period(long startInstant,
              long endInstant,
              Chronology chrono)

Creates a period from the given interval endpoints using the standard set of fields.

Period

public Period(long startInstant,
              long endInstant,
              PeriodType type,
              Chronology chrono)

Creates a period from the given interval endpoints.

Period

public Period(ReadableInstant startInstant,
              ReadableInstant endInstant)

Creates a period from the given interval endpoints using the standard set of fields.

Period

public Period(ReadableInstant startInstant,
              ReadableInstant endInstant,
              PeriodType type)

Creates a period from the given interval endpoints.

Period

public Period(ReadablePartial start,
              ReadablePartial end)

Creates a period from two partially specified times.

The two partials must contain the same fields, thus you can specify two YearMonthDay objects, or two TimeOfDay 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) 55 for a definition. Both YearMonthDay and TimeOfDay are contiguous.

An alternative way of constructing a Period from two Partials is fieldDifference(ReadablePartial, ReadablePartial) 55 . That method handles all kinds of partials.

Since:

1.1

Period

public Period(ReadablePartial start,
              ReadablePartial end,
              PeriodType type)

Creates a period from two partially specified times.

The two partials must also both be contiguous - see DateTimeUtils.isContiguous(ReadablePartial) 55 for a definition. Both YearMonthDay and TimeOfDay are contiguous.

An alternative way of constructing a Period from two Partials is fieldDifference(ReadablePartial, ReadablePartial) 55 . That method handles all kinds of partials.

Since:

1.1

Period

public Period(ReadableInstant startInstant,
              ReadableDuration duration)

Creates a period from the given start point and the duration.

Period

public Period(ReadableInstant startInstant,
              ReadableDuration duration,
              PeriodType type)

Creates a period from the given start point and the duration.

Period

public Period(ReadableDuration duration,
              ReadableInstant endInstant)

Creates a period from the given duration and end point.

Period

public Period(ReadableDuration duration,
              ReadableInstant endInstant,
              PeriodType type)

Creates a period from the given duration and end point.

Period

public Period(java.lang.Object period)

Creates a period from the specified object using the ConverterManager.

Period

public Period(java.lang.Object period,
              PeriodType type)

Creates a period from the specified object using the ConverterManager.

Period

public Period(java.lang.Object period,
              Chronology chrono)

Creates a period from the specified object using the ConverterManager.

Period

public Period(java.lang.Object period,
              PeriodType type,
              Chronology chrono)

Creates a period from the specified object using the ConverterManager.

Period

private Period(int[] values,
               PeriodType type)

Constructor used when we trust ourselves.

Method Detail

years

public static Period years(int years)

Create a period with a specified number of years. The standard period type is used.

months

public static Period months(int months)

Create a period with a specified number of months. The standard period type is used.

weeks

public static Period weeks(int weeks)

Create a period with a specified number of weeks. The standard period type is used.

days

public static Period days(int days)

Create a period with a specified number of days. The standard period type is used.

hours

public static Period hours(int hours)

Create a period with a specified number of hours. The standard period type is used.

minutes

public static Period minutes(int minutes)

Create a period with a specified number of minutes. The standard period type is used.

seconds

public static Period seconds(int seconds)

Create a period with a specified number of seconds. The standard period type is used.

millis

public static Period millis(int millis)

Create a period with a specified number of millis. The standard period type is used.

fieldDifference

public static Period fieldDifference(ReadablePartial start,
                                     ReadablePartial end)

Creates a period from two partially specified times, calculating by field difference.

The two partials must contain the same fields, thus you can specify two YearMonthDay objects, or two TimeOfDay 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 2005-06-09/2007-04-12 will yield P1Y-2M3D.

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 P1M-25D. This field-difference based period can be successfully applied to each month of the year to obtain the correct end date for a given start date.

Since:: 1.1

toPeriod

public Period toPeriod()

Get this period as an immutable Period object by returning this.

Specified by:: toPeriod in interface ReadablePeriod

getYears

public int getYears()

Gets the years field part of the period.

getMonths

public int getMonths()

Gets the months field part of the period.

getWeeks

public int getWeeks()

Gets the weeks field part of the period.

getDays

public int getDays()

Gets the days field part of the period.

getHours

public int getHours()

Gets the hours field part of the period.

getMinutes

public int getMinutes()

Gets the minutes field part of the period.

getSeconds

public int getSeconds()

Gets the seconds field part of the period.

getMillis

public int getMillis()

Gets the millis field part of the period.