Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   *  Copyright 2001-2006 Stephen Colebourne
   *
   *  Licensed under the Apache License, Version 2.0 (the "License");
   *  you may not use this file except in compliance with the License.
   *  You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
  *  Unless required by applicable law or agreed to in writing, software
  *  distributed under the License is distributed on an "AS IS" BASIS,
  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  */
 package org.joda.time;
 
 
Interval is the standard implementation of an immutable time interval.

A time interval represents a period of time between two instants. Intervals are inclusive of the start instant and exclusive of the end. The end instant is always greater than or equal to the start instant.

Intervals have a fixed millisecond duration. This is the difference between the start and end instants. The duration is represented separately by ReadableDuration. As a result, intervals are not comparable. To compare the length of two intervals, you should compare their durations.

An interval can also be converted to a ReadablePeriod. This represents the difference between the start and end points in terms of fields such as years and days.

Interval is thread-safe and immutable.

Author(s):
Brian S O'Neill
Sean Geoghegan
Stephen Colebourne
Julen Parra
Since:
1.0
 
 public final class Interval
         extends BaseInterval
         implements ReadableIntervalSerializable {

    
Serialization version
 
     private static final long serialVersionUID = 4922451897541386752L;
 
     //-----------------------------------------------------------------------
     
Constructs an interval from a start and end instant with the ISO default chronology in the default time zone.

Parameters:
startInstant start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
endInstant end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
Throws:
java.lang.IllegalArgumentException if the end is before the start
 
     public Interval(long startInstantlong endInstant) {
         super(startInstantendInstantnull);
     }

    
Constructs an interval from a start and end instant with the ISO default chronology in the specified time zone.

Parameters:
startInstant start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
endInstant end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
zone the time zone to use, null means default zone
Throws:
java.lang.IllegalArgumentException if the end is before the start
Since:
1.5
 
     public Interval(long startInstantlong endInstantDateTimeZone zone) {
         super(startInstantendInstant, ISOChronology.getInstance(zone));
     }

    
Constructs an interval from a start and end instant with the specified chronology.

Parameters:
chronology the chronology to use, null is ISO default
startInstant start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
endInstant end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
Throws:
java.lang.IllegalArgumentException if the end is before the start
 
     public Interval(long startInstantlong endInstantChronology chronology) {
         super(startInstantendInstantchronology);
     }

    
Constructs an interval from a start and end instant.

The chronology used is that of the start instant.

Parameters:
start start of this interval, null means now
end end of this interval, null means now
Throws:
java.lang.IllegalArgumentException if the end is before the start
    public Interval(ReadableInstant startReadableInstant end) {
        super(startend);
    }

    
Constructs an interval from a start instant and a duration.

Parameters:
start start of this interval, null means now
duration the duration of this interval, null means zero length
Throws:
java.lang.IllegalArgumentException if the end is before the start
java.lang.ArithmeticException if the end instant exceeds the capacity of a long
    public Interval(ReadableInstant startReadableDuration duration) {
        super(startduration);
    }

    
Constructs an interval from a millisecond duration and an end instant.

Parameters:
duration the duration of this interval, null means zero length
end end of this interval, null means now
Throws:
java.lang.IllegalArgumentException if the end is before the start
java.lang.ArithmeticException if the start instant exceeds the capacity of a long
    public Interval(ReadableDuration durationReadableInstant end) {
        super(durationend);
    }

    
Constructs an interval from a start instant and a time period.

When forming the interval, the chronology from the instant is used if present, otherwise the chronology of the period is used.

Parameters:
start start of this interval, null means now
period the period of this interval, null means zero length
Throws:
java.lang.IllegalArgumentException if the end is before the start
java.lang.ArithmeticException if the end instant exceeds the capacity of a long
    public Interval(ReadableInstant startReadablePeriod period) {
        super(startperiod);
    }

    
Constructs an interval from a time period and an end instant.

When forming the interval, the chronology from the instant is used if present, otherwise the chronology of the period is used.

Parameters:
period the period of this interval, null means zero length
end end of this interval, null means now
Throws:
java.lang.IllegalArgumentException if the end is before the start
java.lang.ArithmeticException if the start instant exceeds the capacity of a long
    public Interval(ReadablePeriod periodReadableInstant end) {
        super(periodend);
    }

    
Constructs a time interval by converting or copying from another object.

The recognised object types are defined in ConverterManager and include ReadableInterval and String. The String formats are described by org.joda.time.format.ISODateTimeFormat.dateTimeParser() and org.joda.time.format.ISOPeriodFormat.standard(), and may be 'datetime/datetime', 'datetime/period' or 'period/datetime'.

Parameters:
interval the time interval to copy
Throws:
java.lang.IllegalArgumentException if the interval is invalid
    public Interval(Object interval) {
        super(intervalnull);
    }

    
Constructs a time interval by converting or copying from another object, overriding the chronology.

The recognised object types are defined in ConverterManager and include ReadableInterval and String. The String formats are described by org.joda.time.format.ISODateTimeFormat.dateTimeParser() and org.joda.time.format.ISOPeriodFormat.standard(), and may be 'datetime/datetime', 'datetime/period' or 'period/datetime'.

Parameters:
interval the time interval to copy
chronology the chronology to use, null means ISO default
Throws:
java.lang.IllegalArgumentException if the interval is invalid
    public Interval(Object intervalChronology chronology) {
        super(intervalchronology);
    }
    //-----------------------------------------------------------------------
    
Get this interval as an immutable Interval object by returning this.

Returns:
this
    public Interval toInterval() {
        return this;
    }
    //-----------------------------------------------------------------------
    
Gets the overlap between this interval and another interval.

Intervals are inclusive of the start instant and exclusive of the end. An interval overlaps another if it shares some common part of the datetime continuum. This method returns the amount of the overlap, only if the intervals actually do overlap. If the intervals do not overlap, then null is returned.

When two intervals are compared the result is one of three states: (a) they abut, (b) there is a gap between them, (c) they overlap. The abuts state takes precedence over the other two, thus a zero duration interval at the start of a larger interval abuts and does not overlap.

The chronology of the returned interval is the same as that of this interval (the chronology of the interval parameter is not used). Note that the use of the chronology was only correctly implemented in version 1.3.

Parameters:
interval the interval to examine, null means now
Returns:
the overlap interval, null if no overlap
Since:
1.1
    public Interval overlap(ReadableInterval interval) {
        interval = DateTimeUtils.getReadableInterval(interval);
        if (overlaps(interval) == false) {
            return null;
        }
        long start = Math.max(getStartMillis(), interval.getStartMillis());
        long end = Math.min(getEndMillis(), interval.getEndMillis());
        return new Interval(startendgetChronology());
    }
    //-----------------------------------------------------------------------
    
Gets the gap between this interval and another interval. The other interval can be either before or after this interval.

Intervals are inclusive of the start instant and exclusive of the end. An interval has a gap to another interval if there is a non-zero duration between them. This method returns the amount of the gap only if the intervals do actually have a gap between them. If the intervals overlap or abut, then null is returned.

When two intervals are compared the result is one of three states: (a) they abut, (b) there is a gap between them, (c) they overlap. The abuts state takes precedence over the other two, thus a zero duration interval at the start of a larger interval abuts and does not overlap.

The chronology of the returned interval is the same as that of this interval (the chronology of the interval parameter is not used). Note that the use of the chronology was only correctly implemented in version 1.3.

Parameters:
interval the interval to examine, null means now
Returns:
the gap interval, null if no gap
Since:
1.1
    public Interval gap(ReadableInterval interval) {
        interval = DateTimeUtils.getReadableInterval(interval);
        long otherStart = interval.getStartMillis();
        long otherEnd = interval.getEndMillis();
        long thisStart = getStartMillis();
        long thisEnd = getEndMillis();
        if (thisStart > otherEnd) {
            return new Interval(otherEndthisStartgetChronology());
        } else if (otherStart > thisEnd) {
            return new Interval(thisEndotherStartgetChronology());
        } else {
            return null;
        }
    }
    //-----------------------------------------------------------------------
    
Does this interval abut with the interval specified.

Intervals are inclusive of the start instant and exclusive of the end. An interval abuts if it starts immediately after, or ends immediately before this interval without overlap. A zero duration interval abuts with itself.

When two intervals are compared the result is one of three states: (a) they abut, (b) there is a gap between them, (c) they overlap. The abuts state takes precedence over the other two, thus a zero duration interval at the start of a larger interval abuts and does not overlap.

For example:

 [09:00 to 10:00) abuts [08:00 to 08:30)  = false (completely before)
 [09:00 to 10:00) abuts [08:00 to 09:00)  = true
 [09:00 to 10:00) abuts [08:00 to 09:01)  = false (overlaps)
 
 [09:00 to 10:00) abuts [09:00 to 09:00)  = true
 [09:00 to 10:00) abuts [09:00 to 09:01)  = false (overlaps)
 
 [09:00 to 10:00) abuts [10:00 to 10:00)  = true
 [09:00 to 10:00) abuts [10:00 to 10:30)  = true
 
 [09:00 to 10:00) abuts [10:30 to 11:00)  = false (completely after)
 
 [14:00 to 14:00) abuts [14:00 to 14:00)  = true
 [14:00 to 14:00) abuts [14:00 to 15:00)  = true
 [14:00 to 14:00) abuts [13:00 to 14:00)  = true
 

Parameters:
interval the interval to examine, null means now
Returns:
true if the interval abuts
Since:
1.1
    public boolean abuts(ReadableInterval interval) {
        if (interval == null) {
            long now = DateTimeUtils.currentTimeMillis();
            return (getStartMillis() == now || getEndMillis() == now);
        } else {
            return (interval.getEndMillis() == getStartMillis() ||
                    getEndMillis() == interval.getStartMillis());
        }
    }
    //-----------------------------------------------------------------------
    
Creates a new interval with the same start and end, but a different chronology.

Parameters:
chronology the chronology to use, null means ISO default
Returns:
an interval with a different chronology
    public Interval withChronology(Chronology chronology) {
        if (getChronology() == chronology) {
            return this;
        }
        return new Interval(getStartMillis(), getEndMillis(), chronology);
    }

    
Creates a new interval with the specified start millisecond instant.

Parameters:
startInstant the start instant for the new interval
Returns:
an interval with the end from this interval and the specified start
Throws:
java.lang.IllegalArgumentException if the resulting interval has end before start
    public Interval withStartMillis(long startInstant) {
        if (startInstant == getStartMillis()) {
            return this;
        }
        return new Interval(startInstantgetEndMillis(), getChronology());
    }

    
Creates a new interval with the specified start instant.

Parameters:
start the start instant for the new interval, null means now
Returns:
an interval with the end from this interval and the specified start
Throws:
java.lang.IllegalArgumentException if the resulting interval has end before start
    public Interval withStart(ReadableInstant start) {
        long startMillis = DateTimeUtils.getInstantMillis(start);
        return withStartMillis(startMillis);
    }

    
Creates a new interval with the specified start millisecond instant.

Parameters:
endInstant the end instant for the new interval
Returns:
an interval with the start from this interval and the specified end
Throws:
java.lang.IllegalArgumentException if the resulting interval has end before start
    public Interval withEndMillis(long endInstant) {
        if (endInstant == getEndMillis()) {
            return this;
        }
        return new Interval(getStartMillis(), endInstantgetChronology());
    }

    
Creates a new interval with the specified end instant.

Parameters:
end the end instant for the new interval, null means now
Returns:
an interval with the start from this interval and the specified end
Throws:
java.lang.IllegalArgumentException if the resulting interval has end before start
    public Interval withEnd(ReadableInstant end) {
        long endMillis = DateTimeUtils.getInstantMillis(end);
        return withEndMillis(endMillis);
    }
    //-----------------------------------------------------------------------
    
Creates a new interval with the specified duration after the start instant.

Parameters:
duration the duration to add to the start to get the new end instant, null means zero
Returns:
an interval with the start from this interval and a calculated end
Throws:
java.lang.IllegalArgumentException if the duration is negative
    public Interval withDurationAfterStart(ReadableDuration duration) {
        long durationMillis = DateTimeUtils.getDurationMillis(duration);
        if (durationMillis == toDurationMillis()) {
            return this;
        }
        Chronology chrono = getChronology();
        long startMillis = getStartMillis();
        long endMillis = chrono.add(startMillisdurationMillis, 1);
        return new Interval(startMillisendMillischrono);
    }

    
Creates a new interval with the specified duration before the end instant.

Parameters:
duration the duration to add to the start to get the new end instant, null means zero
Returns:
an interval with the start from this interval and a calculated end
Throws:
java.lang.IllegalArgumentException if the duration is negative
    public Interval withDurationBeforeEnd(ReadableDuration duration) {
        long durationMillis = DateTimeUtils.getDurationMillis(duration);
        if (durationMillis == toDurationMillis()) {
            return this;
        }
        Chronology chrono = getChronology();
        long endMillis = getEndMillis();
        long startMillis = chrono.add(endMillisdurationMillis, -1);
        return new Interval(startMillisendMillischrono);
    }
    //-----------------------------------------------------------------------
    
Creates a new interval with the specified period after the start instant.

Parameters:
period the period to add to the start to get the new end instant, null means zero
Returns:
an interval with the start from this interval and a calculated end
Throws:
java.lang.IllegalArgumentException if the period is negative
    public Interval withPeriodAfterStart(ReadablePeriod period) {
        if (period == null) {
            return withDurationAfterStart(null);
        }
        Chronology chrono = getChronology();
        long startMillis = getStartMillis();
        long endMillis = chrono.add(periodstartMillis, 1);
        return new Interval(startMillisendMillischrono);
    }

    
Creates a new interval with the specified period before the end instant.

Parameters:
period the period to add to the start to get the new end instant, null means zero
Returns:
an interval with the start from this interval and a calculated end
Throws:
java.lang.IllegalArgumentException if the period is negative
    public Interval withPeriodBeforeEnd(ReadablePeriod period) {
        if (period == null) {
            return withDurationBeforeEnd(null);
        }
        Chronology chrono = getChronology();
        long endMillis = getEndMillis();
        long startMillis = chrono.add(periodendMillis, -1);
        return new Interval(startMillisendMillischrono);
    }
New to GrepCode? Check out our FAQ X