Interval


1   /*
2    *  Copyright 2001-2006 Stephen Colebourne
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   */
16  package org.joda.time;
17  
18  import java.io.Serializable  ;
19  
20  import org.joda.time.base.BaseInterval;
21  
22  /**
23   * Interval is the standard implementation of an immutable time interval.
24   * <p>
25   * A time interval represents a period of time between two instants.
26   * Intervals are inclusive of the start instant and exclusive of the end.
27   * The end instant is always greater than or equal to the start instant.
28   * <p>
29   * Intervals have a fixed millisecond duration.
30   * This is the difference between the start and end instants.
31   * The duration is represented separately by {@link ReadableDuration}.
32   * As a result, intervals are not comparable.
33   * To compare the length of two intervals, you should compare their durations.
34   * <p>
35   * An interval can also be converted to a {@link ReadablePeriod}.
36   * This represents the difference between the start and end points in terms of fields
37   * such as years and days.
38   * <p>
39   * Interval is thread-safe and immutable.
40   *
41   * @author Brian S O'Neill
42   * @author Sean Geoghegan
43   * @author Stephen Colebourne
44   * @author Julen Parra
45   * @since 1.0
46   */
47  public final class Interval
48          extends BaseInterval
49          implements ReadableInterval, Serializable   {
50  
51      /** Serialization version */
52      private static final long serialVersionUID = 4922451897541386752L;
53  
54      //-----------------------------------------------------------------------
55      /**
56       * Constructs an interval from a start and end instant with the ISO default chronology.
57       * 
58       * @param startInstant  start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
59       * @param endInstant  end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
60       * @throws IllegalArgumentException if the end is before the start
61       */
62      public Interval(long startInstant, long endInstant) {
63          super(startInstant, endInstant, null);
64      }
65  
66      /**
67       * Constructs an interval from a start and end instant with a chronology.
68       * 
69       * @param chronology  the chronology to use, null is ISO default
70       * @param startInstant  start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
71       * @param endInstant  end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
72       * @throws IllegalArgumentException if the end is before the start
73       */
74      public Interval(long startInstant, long endInstant, Chronology chronology) {
75          super(startInstant, endInstant, chronology);
76      }
77  
78      /**
79       * Constructs an interval from a start and end instant.
80       * <p>
81       * The chronology used is that of the start instant.
82       * 
83       * @param start  start of this interval, null means now
84       * @param end  end of this interval, null means now
85       * @throws IllegalArgumentException if the end is before the start
86       */
87      public Interval(ReadableInstant start, ReadableInstant end) {
88          super(start, end);
89      }
90  
91      /**
92       * Constructs an interval from a start instant and a duration.
93       * 
94       * @param start  start of this interval, null means now
95       * @param duration  the duration of this interval, null means zero length
96       * @throws IllegalArgumentException if the end is before the start
97       * @throws ArithmeticException if the end instant exceeds the capacity of a long
98       */
99      public Interval(ReadableInstant start, ReadableDuration duration) {
100         super(start, duration);
101     }
102 
103     /**
104      * Constructs an interval from a millisecond duration and an end instant.
105      * 
106      * @param duration  the duration of this interval, null means zero length
107      * @param end  end of this interval, null means now
108      * @throws IllegalArgumentException if the end is before the start
109      * @throws ArithmeticException if the start instant exceeds the capacity of a long
110      */
111     public Interval(ReadableDuration duration, ReadableInstant end) {
112         super(duration, end);
113     }
114 
115     /**
116      * Constructs an interval from a start instant and a time period.
117      * <p>
118      * When forming the interval, the chronology from the instant is used
119      * if present, otherwise the chronology of the period is used.
120      * 
121      * @param start  start of this interval, null means now
122      * @param period  the period of this interval, null means zero length
123      * @throws IllegalArgumentException if the end is before the start
124      * @throws ArithmeticException if the end instant exceeds the capacity of a long
125      */
126     public Interval(ReadableInstant start, ReadablePeriod period) {
127         super(start, period);
128     }
129 
130     /**
131      * Constructs an interval from a time period and an end instant.
132      * <p>
133      * When forming the interval, the chronology from the instant is used
134      * if present, otherwise the chronology of the period is used.
135      * 
136      * @param period  the period of this interval, null means zero length
137      * @param end  end of this interval, null means now
138      * @throws IllegalArgumentException if the end is before the start
139      * @throws ArithmeticException if the start instant exceeds the capacity of a long
140      */
141     public Interval(ReadablePeriod period, ReadableInstant end) {
142         super(period, end);
143     }
144 
145     /**
146      * Constructs a time interval by converting or copying from another object.
147      * 
148      * @param interval  the time interval to copy
149      * @throws IllegalArgumentException if the interval is invalid
150      */
151     public Interval(Object   interval) {
152         super(interval, null);
153     }
154 
155     /**
156      * Constructs a time interval by converting or copying from another object,
157      * overriding the chronology.
158      * 
159      * @param interval  the time interval to copy
160      * @param chronology  the chronology to use, null means ISO default
161      * @throws IllegalArgumentException if the interval is invalid
162      */
163     public Interval(Object   interval, Chronology chronology) {
164         super(interval, chronology);
165     }
166 
167     //-----------------------------------------------------------------------
168     /**
169      * Get this interval as an immutable <code>Interval</code> object
170      * by returning <code>this</code>.
171      *
172      * @return <code>this</code>
173      */
174     public Interval toInterval() {
175         return this;
176     }
177 
178     //-----------------------------------------------------------------------
179     /**
180      * Gets the overlap between this interval and another interval.
181      * <p>
182      * Intervals are inclusive of the start instant and exclusive of the end.
183      * An interval overlaps another if it shares some common part of the
184      * datetime continuum. This method returns the amount of the overlap,
185      * only if the intervals actually do overlap.
186      * If the intervals do not overlap, then null is returned.
187      * <p>
188      * When two intervals are compared the result is one of three states:
189      * (a) they abut, (b) there is a gap between them, (c) they overlap.
190      * The abuts state takes precedence over the other two, thus a zero duration
191      * interval at the start of a larger interval abuts and does not overlap.
192      * <p>
193      * The chronology of the returned interval is the same as that of
194      * this interval (the chronology of the interval parameter is not used).
195      * Note that the use of the chronology was only correctly implemented
196      * in version 1.3.
197      *
198      * @param interval  the interval to examine, null means now
199      * @return the overlap interval, null if no overlap
200      * @since 1.1
201      */
202     public Interval overlap(ReadableInterval interval) {
203         interval = DateTimeUtils.getReadableInterval(interval);
204         if (overlaps(interval) == false) {
205             return null;
206         }
207         long start = Math.max(getStartMillis(), interval.getStartMillis());
208         long end = Math.min(getEndMillis(), interval.getEndMillis());
209         return new Interval(start, end, getChronology());
210     }
211 
212     //-----------------------------------------------------------------------
213     /**
214      * Gets the gap between this interval and another interval.
215      * The other interval can be either before or after this interval.
216      * <p>
217      * Intervals are inclusive of the start instant and exclusive of the end.
218      * An interval has a gap to another interval if there is a non-zero
219      * duration between them. This method returns the amount of the gap only
220      * if the intervals do actually have a gap between them.
221      * If the intervals overlap or abut, then null is returned.
222      * <p>
223      * When two intervals are compared the result is one of three states:
224      * (a) they abut, (b) there is a gap between them, (c) they overlap.
225      * The abuts state takes precedence over the other two, thus a zero duration
226      * interval at the start of a larger interval abuts and does not overlap.
227      * <p>
228      * The chronology of the returned interval is the same as that of
229      * this interval (the chronology of the interval parameter is not used).
230      * Note that the use of the chronology was only correctly implemented
231      * in version 1.3.
232      *
233      * @param interval  the interval to examine, null means now
234      * @return the gap interval, null if no gap
235      * @since 1.1
236      */
237     public Interval gap(ReadableInterval interval) {
238         interval = DateTimeUtils.getReadableInterval(interval);
239         long otherStart = interval.getStartMillis();
240         long otherEnd = interval.getEndMillis();
241         long thisStart = getStartMillis();
242         long thisEnd = getEndMillis();
243         if (thisStart > otherEnd) {
244             return new Interval(otherEnd, thisStart, getChronology());
245         } else if (otherStart > thisEnd) {
246             return new Interval(thisEnd, otherStart, getChronology());
247         } else {
248             return null;
249         }
250     }
251 
252     //-----------------------------------------------------------------------
253     /**
254      * Does this interval abut with the interval specified.
255      * <p>
256      * Intervals are inclusive of the start instant and exclusive of the end.
257      * An interval abuts if it starts immediately after, or ends immediately
258      * before this interval without overlap.
259      * A zero duration interval abuts with itself.
260      * <p>
261      * When two intervals are compared the result is one of three states:
262      * (a) they abut, (b) there is a gap between them, (c) they overlap.
263      * The abuts state takes precedence over the other two, thus a zero duration
264      * interval at the start of a larger interval abuts and does not overlap.
265      * <p>
266      * For example:
267      * <pre>
268      * [09:00 to 10:00) abuts [08:00 to 08:30)  = false (completely before)
269      * [09:00 to 10:00) abuts [08:00 to 09:00)  = true
270      * [09:00 to 10:00) abuts [08:00 to 09:01)  = false (overlaps)
271      * 
272      * [09:00 to 10:00) abuts [09:00 to 09:00)  = true
273      * [09:00 to 10:00) abuts [09:00 to 09:01)  = false (overlaps)
274      * 
275      * [09:00 to 10:00) abuts [10:00 to 10:00)  = true
276      * [09:00 to 10:00) abuts [10:00 to 10:30)  = true
277      * 
278      * [09:00 to 10:00) abuts [10:30 to 11:00)  = false (completely after)
279      * 
280      * [14:00 to 14:00) abuts [14:00 to 14:00)  = true
281      * [14:00 to 14:00) abuts [14:00 to 15:00)  = true
282      * [14:00 to 14:00) abuts [13:00 to 14:00)  = true
283      * </pre>
284      *
285      * @param interval  the interval to examine, null means now
286      * @return true if the interval abuts
287      * @since 1.1
288      */
289     public boolean abuts(ReadableInterval interval) {
290         if (interval == null) {
291             long now = DateTimeUtils.currentTimeMillis();
292             return (getStartMillis() == now || getEndMillis() == now);
293         } else {
294             return (interval.getEndMillis() == getStartMillis() ||
295                     getEndMillis() == interval.getStartMillis());
296         }
297     }
298 
299     //-----------------------------------------------------------------------
300     /**
301      * Creates a new interval with the same start and end, but a different chronology.
302      *
303      * @param chronology  the chronology to use, null means ISO default
304      * @return an interval with a different chronology
305      */
306     public Interval withChronology(Chronology chronology) {
307         if (getChronology() == chronology) {
308             return this;
309         }
310         return new Interval(getStartMillis(), getEndMillis(), chronology);
311     }
312 
313     /**
314      * Creates a new interval with the specified start millisecond instant.
315      *
316      * @param startInstant  the start instant for the new interval
317      * @return an interval with the end from this interval and the specified start
318      * @throws IllegalArgumentException if the resulting interval has end before start
319      */
320     public Interval withStartMillis(long startInstant) {
321         if (startInstant == getStartMillis()) {
322             return this;
323         }
324         return new Interval(startInstant, getEndMillis(), getChronology());
325     }
326 
327     /**
328      * Creates a new interval with the specified start instant.
329      *
330      * @param start  the start instant for the new interval, null means now
331      * @return an interval with the end from this interval and the specified start
332      * @throws IllegalArgumentException if the resulting interval has end before start
333      */
334     public Interval withStart(ReadableInstant start) {
335         long startMillis = DateTimeUtils.getInstantMillis(start);
336         return withStartMillis(startMillis);
337     }
338 
339     /**
340      * Creates a new interval with the specified start millisecond instant.
341      *
342      * @param endInstant  the end instant for the new interval
343      * @return an interval with the start from this interval and the specified end
344      * @throws IllegalArgumentException if the resulting interval has end before start
345      */
346     public Interval withEndMillis(long endInstant) {
347         if (endInstant == getEndMillis()) {
348             return this;
349         }
350         return new Interval(getStartMillis(), endInstant, getChronology());
351     }
352 
353     /**
354      * Creates a new interval with the specified end instant.
355      *
356      * @param end  the end instant for the new interval, null means now
357      * @return an interval with the start from this interval and the specified end
358      * @throws IllegalArgumentException if the resulting interval has end before start
359      */
360     public Interval withEnd(ReadableInstant end) {
361         long endMillis = DateTimeUtils.getInstantMillis(end);
362         return withEndMillis(endMillis);
363     }
364 
365     //-----------------------------------------------------------------------
366     /**
367      * Creates a new interval with the specified duration after the start instant.
368      *
369      * @param duration  the duration to add to the start to get the new end instant, null means zero
370      * @return an interval with the start from this interval and a calculated end
371      * @throws IllegalArgumentException if the duration is negative
372      */
373     public Interval withDurationAfterStart(ReadableDuration duration) {
374         long durationMillis = DateTimeUtils.getDurationMillis(duration);
375         if (durationMillis == toDurationMillis()) {
376             return this;
377         }
378         Chronology chrono = getChronology();
379         long startMillis = getStartMillis();
380         long endMillis = chrono.add(startMillis, durationMillis, 1);
381         return new Interval(startMillis, endMillis, chrono);
382     }
383 
384     /**
385      * Creates a new interval with the specified duration before the end instant.
386      *
387      * @param duration  the duration to add to the start to get the new end instant, null means zero
388      * @return an interval with the start from this interval and a calculated end
389      * @throws IllegalArgumentException if the duration is negative
390      */
391     public Interval withDurationBeforeEnd(ReadableDuration duration) {
392         long durationMillis = DateTimeUtils.getDurationMillis(duration);
393         if (durationMillis == toDurationMillis()) {
394             return this;
395         }
396         Chronology chrono = getChronology();
397         long endMillis = getEndMillis();
398         long startMillis = chrono.add(endMillis, durationMillis, -1);
399         return new Interval(startMillis, endMillis, chrono);
400     }
401 
402     //-----------------------------------------------------------------------
403     /**
404      * Creates a new interval with the specified period after the start instant.
405      *
406      * @param period  the period to add to the start to get the new end instant, null means zero
407      * @return an interval with the start from this interval and a calculated end
408      * @throws IllegalArgumentException if the period is negative
409      */
410     public Interval withPeriodAfterStart(ReadablePeriod period) {
411         if (period == null) {
412             return withDurationAfterStart(null);
413         }
414         Chronology chrono = getChronology();
415         long startMillis = getStartMillis();
416         long endMillis = chrono.add(period, startMillis, 1);
417         return new Interval(startMillis, endMillis, chrono);
418     }
419 
420     /**
421      * Creates a new interval with the specified period before the end instant.
422      *
423      * @param period  the period to add to the start to get the new end instant, null means zero
424      * @return an interval with the start from this interval and a calculated end
425      * @throws IllegalArgumentException if the period is negative
426      */
427     public Interval withPeriodBeforeEnd(ReadablePeriod period) {
428         if (period == null) {
429             return withDurationBeforeEnd(null);
430         }
431         Chronology chrono = getChronology();
432         long endMillis = getEndMillis();
433         long startMillis = chrono.add(period, endMillis, -1);
434         return new Interval(startMillis, endMillis, chrono);
435     }
436 
437 }
438
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags