001/*
002 *  Copyright 2001-2006 Stephen Colebourne
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.joda.time;
017
018/** 
019 * Readable interface for an interval of time between two instants.
020 * <p>
021 * A time interval represents a period of time between two instants.
022 * Intervals are inclusive of the start instant and exclusive of the end.
023 * The end instant is always greater than or equal to the start instant.
024 * <p>
025 * Intervals have a fixed millisecond duration.
026 * This is the difference between the start and end instants.
027 * The duration is represented separately by {@link ReadableDuration}.
028 * As a result, intervals are not comparable.
029 * To compare the length of two intervals, you should compare their durations.
030 * <p>
031 * An interval can also be converted to a {@link ReadablePeriod}.
032 * This represents the difference between the start and end points in terms of fields
033 * such as years and days.
034 * <p>
035 * Methods that are passed an interval as a parameter will treat <code>null</code>
036 * as a zero length interval at the current instant in time.
037 *
038 * @author Sean Geoghegan
039 * @author Brian S O'Neill
040 * @author Stephen Colebourne
041 * @since 1.0
042 */
043public interface ReadableInterval {
044
045    /**
046     * Gets the chronology of the interval, which is the chronology of the first datetime.
047     *
048     * @return the chronology of the interval
049     */
050    Chronology getChronology();
051
052    /**
053     * Gets the start of this time interval which is inclusive.
054     *
055     * @return the start of the time interval,
056     *  millisecond instant from 1970-01-01T00:00:00Z
057     */
058    long getStartMillis();
059
060    /**
061     * Gets the start of this time interval, which is inclusive, as a DateTime.
062     *
063     * @return the start of the time interval
064     */
065    DateTime getStart();
066
067    /** 
068     * Gets the end of this time interval which is exclusive.
069     *
070     * @return the end of the time interval,
071     *  millisecond instant from 1970-01-01T00:00:00Z
072     */
073    long getEndMillis();
074
075    /** 
076     * Gets the end of this time interval, which is exclusive, as a DateTime.
077     *
078     * @return the end of the time interval
079     */
080    DateTime getEnd();
081
082    //-----------------------------------------------------------------------
083    /**
084     * Does this time interval contain the specified instant.
085     * <p>
086     * Non-zero duration intervals are inclusive of the start instant and
087     * exclusive of the end. A zero duration interval cannot contain anything.
088     * <p>
089     * For example:
090     * <pre>
091     * [09:00 to 10:00) contains 08:59  = false (before start)
092     * [09:00 to 10:00) contains 09:00  = true
093     * [09:00 to 10:00) contains 09:59  = true
094     * [09:00 to 10:00) contains 10:00  = false (equals end)
095     * [09:00 to 10:00) contains 10:01  = false (after end)
096     * 
097     * [14:00 to 14:00) contains 14:00  = false (zero duration contains nothing)
098     * </pre>
099     *
100     * @param instant  the instant, null means now
101     * @return true if this time interval contains the instant
102     */
103    boolean contains(ReadableInstant instant);
104    
105    /**
106     * Does this time interval contain the specified time interval.
107     * <p>
108     * Non-zero duration intervals are inclusive of the start instant and
109     * exclusive of the end. The other interval is contained if this interval
110     * wholly contains, starts, finishes or equals it.
111     * A zero duration interval cannot contain anything.
112     * <p>
113     * When two intervals are compared the result is one of three states:
114     * (a) they abut, (b) there is a gap between them, (c) they overlap.
115     * The <code>contains</code> method is not related to these states.
116     * In particular, a zero duration interval is contained at the start of
117     * a larger interval, but does not overlap (it abuts instead).
118     * <p>
119     * For example:
120     * <pre>
121     * [09:00 to 10:00) contains [09:00 to 10:00)  = true
122     * [09:00 to 10:00) contains [09:00 to 09:30)  = true
123     * [09:00 to 10:00) contains [09:30 to 10:00)  = true
124     * [09:00 to 10:00) contains [09:15 to 09:45)  = true
125     * [09:00 to 10:00) contains [09:00 to 09:00)  = true
126     * 
127     * [09:00 to 10:00) contains [08:59 to 10:00)  = false (otherStart before thisStart)
128     * [09:00 to 10:00) contains [09:00 to 10:01)  = false (otherEnd after thisEnd)
129     * [09:00 to 10:00) contains [10:00 to 10:00)  = false (otherStart equals thisEnd)
130     * 
131     * [14:00 to 14:00) contains [14:00 to 14:00)  = false (zero duration contains nothing)
132     * </pre>
133     *
134     * @param interval  the time interval to compare to, null means a zero duration interval now
135     * @return true if this time interval contains the time interval
136     */
137    boolean contains(ReadableInterval interval);
138    
139    /**
140     * Does this time interval overlap the specified time interval.
141     * <p>
142     * Intervals are inclusive of the start instant and exclusive of the end.
143     * An interval overlaps another if it shares some common part of the
144     * datetime continuum. 
145     * <p>
146     * When two intervals are compared the result is one of three states:
147     * (a) they abut, (b) there is a gap between them, (c) they overlap.
148     * The abuts state takes precedence over the other two, thus a zero duration
149     * interval at the start of a larger interval abuts and does not overlap.
150     * <p>
151     * For example:
152     * <pre>
153     * [09:00 to 10:00) overlaps [08:00 to 08:30)  = false (completely before)
154     * [09:00 to 10:00) overlaps [08:00 to 09:00)  = false (abuts before)
155     * [09:00 to 10:00) overlaps [08:00 to 09:30)  = true
156     * [09:00 to 10:00) overlaps [08:00 to 10:00)  = true
157     * [09:00 to 10:00) overlaps [08:00 to 11:00)  = true
158     * 
159     * [09:00 to 10:00) overlaps [09:00 to 09:00)  = false (abuts before)
160     * [09:00 to 10:00) overlaps [09:00 to 09:30)  = true
161     * [09:00 to 10:00) overlaps [09:00 to 10:00)  = true
162     * [09:00 to 10:00) overlaps [09:00 to 11:00)  = true
163     * 
164     * [09:00 to 10:00) overlaps [09:30 to 09:30)  = true
165     * [09:00 to 10:00) overlaps [09:30 to 10:00)  = true
166     * [09:00 to 10:00) overlaps [09:30 to 11:00)  = true
167     * 
168     * [09:00 to 10:00) overlaps [10:00 to 10:00)  = false (abuts after)
169     * [09:00 to 10:00) overlaps [10:00 to 11:00)  = false (abuts after)
170     * 
171     * [09:00 to 10:00) overlaps [10:30 to 11:00)  = false (completely after)
172     * 
173     * [14:00 to 14:00) overlaps [14:00 to 14:00)  = false (abuts before and after)
174     * [14:00 to 14:00) overlaps [13:00 to 15:00)  = true
175     * </pre>
176     *
177     * @param interval  the time interval to compare to, null means a zero length interval now
178     * @return true if the time intervals overlap
179     */
180    boolean overlaps(ReadableInterval interval);
181    
182    //-----------------------------------------------------------------------
183    /**
184     * Is this time interval after the specified instant.
185     * <p>
186     * Intervals are inclusive of the start instant and exclusive of the end.
187     * 
188     * @param instant  the instant to compare to, null means now
189     * @return true if this time interval is after the instant
190     */
191    boolean isAfter(ReadableInstant instant);
192    
193    /**
194     * Is this time interval entirely after the specified interval.
195     * <p>
196     * Intervals are inclusive of the start instant and exclusive of the end.
197     * 
198     * @param interval  the interval to compare to, null means now
199     * @return true if this time interval is after the interval specified
200     */
201    boolean isAfter(ReadableInterval interval);
202    
203    /**
204     * Is this time interval before the specified instant.
205     * <p>
206     * Intervals are inclusive of the start instant and exclusive of the end.
207     * 
208     * @param instant  the instant to compare to, null means now
209     * @return true if this time interval is before the instant
210     */
211    boolean isBefore(ReadableInstant instant);
212    
213    /**
214     * Is this time interval entirely before the specified interval.
215     * <p>
216     * Intervals are inclusive of the start instant and exclusive of the end.
217     * 
218     * @param interval  the interval to compare to, null means now
219     * @return true if this time interval is before the interval specified
220     */
221    boolean isBefore(ReadableInterval interval);
222    
223    //-----------------------------------------------------------------------
224    /**
225     * Get this interval as an immutable <code>Interval</code> object.
226     * <p>
227     * This will either typecast this instance, or create a new <code>Interval</code>.
228     *
229     * @return the interval as an Interval object
230     */
231    Interval toInterval();
232
233    /**
234     * Get this time interval as a <code>MutableInterval</code>.
235     * <p>
236     * This will always return a new <code>MutableInterval</code> with the same interval.
237     *
238     * @return the time interval as a MutableInterval object
239     */
240    MutableInterval toMutableInterval();
241
242    //-----------------------------------------------------------------------
243    /**
244     * Gets the millisecond duration of this time interval.
245     *
246     * @return the millisecond duration of the time interval
247     * @throws ArithmeticException if the duration exceeds the capacity of a long
248     */
249    Duration toDuration();
250
251    /**
252     * Gets the millisecond duration of this time interval.
253     *
254     * @return the millisecond duration of the time interval
255     * @throws ArithmeticException if the duration exceeds the capacity of a long
256     */
257    long toDurationMillis();
258
259    /**
260     * Converts the duration of the interval to a period using the
261     * standard period type.
262     * <p>
263     * This method should be used to exract the field values describing the
264     * difference between the start and end instants.
265     *
266     * @return a time period derived from the interval
267     */
268    Period toPeriod();
269
270    /**
271     * Converts the duration of the interval to a period using the
272     * specified period type.
273     * <p>
274     * This method should be used to exract the field values describing the
275     * difference between the start and end instants.
276     *
277     * @param type  the requested type of the duration, null means standard
278     * @return a time period derived from the interval
279     */
280    Period toPeriod(PeriodType type);
281
282    //-----------------------------------------------------------------------
283    /**
284     * Compares this object with the specified object for equality based
285     * on start and end millis plus the chronology.
286     * All ReadableInterval instances are accepted.
287     * <p>
288     * To compare the duration of two time intervals, use {@link #toDuration()}
289     * to get the durations and compare those.
290     *
291     * @param readableInterval  a readable interval to check against
292     * @return true if the start and end millis are equal
293     */
294    boolean equals(Object readableInterval);
295
296    /**
297     * Gets a hash code for the time interval that is compatable with the 
298     * equals method.
299     * <p>
300     * The formula used must be as follows:
301     * <pre>int result = 97;
302     * result = 31 * result + ((int) (getStartMillis() ^ (getStartMillis() >>> 32)));
303     * result = 31 * result + ((int) (getEndMillis() ^ (getEndMillis() >>> 32)));
304     * result = 31 * result + getChronology().hashCode();
305     * return result;</pre>
306     *
307     * @return a hash code
308     */
309    int hashCode();
310
311    //-----------------------------------------------------------------------
312    /**
313     * Get the value as a String in the ISO8601 interval format.
314     * <p>
315     * For example, "2004-06-09T12:30:00.000/2004-07-10T13:30:00.000".
316     *
317     * @return the value as an ISO8601 string
318     */
319    String toString();
320
321}