<?xml version="1.0" encoding="ISO-8859-1"?> | |
<document> | |
<properties> | |
<title>Java date and time API - Interval</title> | |
<author>Stephen Colebourne</author> | |
</properties> | |
<body> | |
<section name="Interval"> | |
<p> | |
An <i>interval</i> in Joda-Time represents an interval of time from one millisecond | |
<a href="key_instant.html">instant</a> to another instant. | |
Both instants are fully specified instants in the datetime continuum, complete with time zone. | |
</p> | |
<p> | |
Intervals are implemented as <i>half-open</i>, which is to say that the start instant is | |
inclusive but the end instant is exclusive. | |
The end is always greater than or equal to the start. | |
The interval is also restricted to just one <a href="key_chronology.html">chronology</a> and time zone. | |
</p> | |
<p> | |
Methods exist on intervals to obtain the start and end instants plus the chronology and time zone. | |
There are also methods to obtain the <a href="key_duration.html">duration</a> and | |
<a href="key_period.html">period</a> of the interval. | |
</p> | |
<p> | |
You cannot compare intervals for order (ie. they do not implement <code>Comparable</code>. | |
If you want to compare the length of intervals you must obtain the duration of each and compare those. | |
</p> | |
</section> | |
<section name="Using Intervals in Joda-Time"> | |
<p> | |
Within Joda-Time an interval is represented by the | |
<a href="apidocs/org/joda/time/ReadableInterval.html">ReadableInterval</a> interface. | |
There are two implementations of the interface provided: | |
<ul> | |
<li><a href="apidocs/org/joda/time/Interval.html">Interval</a> - An immutable implementation</li> | |
<li><a href="apidocs/org/joda/time/MutableInterval.html">MutableInterval</a> - A mutable implementation</li> | |
</ul> | |
We recommend the immutable implementation for general usage. | |
</p> | |
<p> | |
The code can be used in various ways: | |
<source> | |
// interval from start to end | |
DateTime start = new DateTime(2004, 12, 25, 0, 0, 0, 0); | |
DateTime end = new DateTime(2005, 1, 1, 0, 0, 0, 0); | |
Interval interval = new Interval(start, end); | |
</source> | |
Accessing other objects is easy: | |
<source> | |
Interval interval = ... | |
DateTime start = interval.getStart(); | |
DateTime end = interval.getEnd(); | |
Chronology chrono = interval.getChronology(); | |
Duration duration = interval.toDuration(); | |
Period period = interval.toPeriod(); | |
</source> | |
</p> | |
<p> | |
Note that the interface <code>ReadableInterval</code> 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. | |
</p> | |
<subsection name="Nulls"> | |
<p> | |
Joda-Time defines a null interval as a zero length interval from now to now. | |
Thus, when a method is defined as taking a <code>ReadableInterval</code>, passing null in | |
will be the same as passing in a zero length interval at the current time. | |
</p> | |
</subsection> | |
</section> | |
</body> | |
</document> |