org.joda.time
Class Interval

java.lang.Object
  extended by org.joda.time.base.AbstractInterval
      extended by org.joda.time.base.BaseInterval
          extended by org.joda.time.Interval
All Implemented Interfaces:
Serializable, ReadableInterval

public final class Interval
extends BaseInterval
implements ReadableInterval, Serializable

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.

Since:
1.0
Author:
Brian S O'Neill, Sean Geoghegan, Stephen Colebourne, Julen Parra
See Also:
Serialized Form

Constructor Summary
Interval(long startInstant, long endInstant)
          Constructs an interval from a start and end instant with the ISO default chronology in the default time zone.
Interval(long startInstant, long endInstant, Chronology chronology)
          Constructs an interval from a start and end instant with the specified chronology.
Interval(long startInstant, long endInstant, DateTimeZone zone)
          Constructs an interval from a start and end instant with the ISO default chronology in the specified time zone.
Interval(Object interval)
          Constructs a time interval by converting or copying from another object.
Interval(Object interval, Chronology chronology)
          Constructs a time interval by converting or copying from another object, overriding the chronology.
Interval(ReadableDuration duration, ReadableInstant end)
          Constructs an interval from a millisecond duration and an end instant.
Interval(ReadableInstant start, ReadableDuration duration)
          Constructs an interval from a start instant and a duration.
Interval(ReadableInstant start, ReadableInstant end)
          Constructs an interval from a start and end instant.
Interval(ReadableInstant start, ReadablePeriod period)
          Constructs an interval from a start instant and a time period.
Interval(ReadablePeriod period, ReadableInstant end)
          Constructs an interval from a time period and an end instant.
 
Method Summary
 boolean abuts(ReadableInterval interval)
          Does this interval abut with the interval specified.
 Interval gap(ReadableInterval interval)
          Gets the gap between this interval and another interval.
 Interval overlap(ReadableInterval interval)
          Gets the overlap between this interval and another interval.
static Interval parse(String str)
          Parses a Interval from the specified string.
 Interval toInterval()
          Get this interval as an immutable Interval object by returning this.
 Interval withChronology(Chronology chronology)
          Creates a new interval with the same start and end, but a different chronology.
 Interval withDurationAfterStart(ReadableDuration duration)
          Creates a new interval with the specified duration after the start instant.
 Interval withDurationBeforeEnd(ReadableDuration duration)
          Creates a new interval with the specified duration before the end instant.
 Interval withEnd(ReadableInstant end)
          Creates a new interval with the specified end instant.
 Interval withEndMillis(long endInstant)
          Creates a new interval with the specified start millisecond instant.
 Interval withPeriodAfterStart(ReadablePeriod period)
          Creates a new interval with the specified period after the start instant.
 Interval withPeriodBeforeEnd(ReadablePeriod period)
          Creates a new interval with the specified period before the end instant.
 Interval withStart(ReadableInstant start)
          Creates a new interval with the specified start instant.
 Interval withStartMillis(long startInstant)
          Creates a new interval with the specified start millisecond instant.
 
Methods inherited from class org.joda.time.base.BaseInterval
getChronology, getEndMillis, getStartMillis, setInterval
 
Methods inherited from class org.joda.time.base.AbstractInterval
checkInterval, contains, contains, contains, containsNow, equals, getEnd, getStart, hashCode, isAfter, isAfter, isAfter, isAfterNow, isBefore, isBefore, isBefore, isBeforeNow, overlaps, toDuration, toDurationMillis, toMutableInterval, toPeriod, toPeriod, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.joda.time.ReadableInterval
contains, contains, equals, getChronology, getEnd, getEndMillis, getStart, getStartMillis, hashCode, isAfter, isAfter, isBefore, isBefore, overlaps, toDuration, toDurationMillis, toMutableInterval, toPeriod, toPeriod, toString
 

Constructor Detail

Interval

public Interval(long startInstant,
                long endInstant)
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:
IllegalArgumentException - if the end is before the start

Interval

public Interval(long startInstant,
                long endInstant,
                DateTimeZone zone)
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:
IllegalArgumentException - if the end is before the start
Since:
1.5

Interval

public Interval(long startInstant,
                long endInstant,
                Chronology chronology)
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:
IllegalArgumentException - if the end is before the start

Interval

public Interval(ReadableInstant start,
                ReadableInstant end)
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:
IllegalArgumentException - if the end is before the start

Interval

public Interval(ReadableInstant start,
                ReadableDuration duration)
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:
IllegalArgumentException - if the end is before the start
ArithmeticException - if the end instant exceeds the capacity of a long

Interval

public Interval(ReadableDuration duration,
                ReadableInstant end)
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:
IllegalArgumentException - if the end is before the start
ArithmeticException - if the start instant exceeds the capacity of a long

Interval

public Interval(ReadableInstant start,
                ReadablePeriod period)
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:
IllegalArgumentException - if the end is before the start
ArithmeticException - if the end instant exceeds the capacity of a long

Interval

public Interval(ReadablePeriod period,
                ReadableInstant end)
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:
IllegalArgumentException - if the end is before the start
ArithmeticException - if the start instant exceeds the capacity of a long

Interval

public Interval(Object interval)
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 ISODateTimeFormat.dateTimeParser() and ISOPeriodFormat.standard(), and may be 'datetime/datetime', 'datetime/period' or 'period/datetime'.

Parameters:
interval - the time interval to copy
Throws:
IllegalArgumentException - if the interval is invalid

Interval

public Interval(Object interval,
                Chronology chronology)
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 ISODateTimeFormat.dateTimeParser() and 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:
IllegalArgumentException - if the interval is invalid
Method Detail

parse

public static Interval parse(String str)
Parses a Interval from the specified string.

The String formats are described by ISODateTimeFormat.dateTimeParser() and ISOPeriodFormat.standard(), and may be 'datetime/datetime', 'datetime/period' or 'period/datetime'.

Parameters:
str - the string to parse, not null
Since:
2.0

toInterval

public Interval toInterval()
Get this interval as an immutable Interval object by returning this.

Specified by:
toInterval in interface ReadableInterval
Overrides:
toInterval in class AbstractInterval
Returns:
this

overlap

public Interval overlap(ReadableInterval interval)
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

gap

public Interval gap(ReadableInterval interval)
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

abuts

public boolean abuts(ReadableInterval interval)
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

withChronology

public Interval withChronology(Chronology chronology)
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

withStartMillis

public Interval withStartMillis(long startInstant)
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:
IllegalArgumentException - if the resulting interval has end before start

withStart

public Interval withStart(ReadableInstant start)
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:
IllegalArgumentException - if the resulting interval has end before start

withEndMillis

public Interval withEndMillis(long endInstant)
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:
IllegalArgumentException - if the resulting interval has end before start

withEnd

public Interval withEnd(ReadableInstant end)
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:
IllegalArgumentException - if the resulting interval has end before start

withDurationAfterStart

public Interval withDurationAfterStart(ReadableDuration duration)
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:
IllegalArgumentException - if the duration is negative

withDurationBeforeEnd

public Interval withDurationBeforeEnd(ReadableDuration duration)
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:
IllegalArgumentException - if the duration is negative

withPeriodAfterStart

public Interval withPeriodAfterStart(ReadablePeriod period)
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:
IllegalArgumentException - if the period is negative

withPeriodBeforeEnd

public Interval withPeriodBeforeEnd(ReadablePeriod period)
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:
IllegalArgumentException - if the period is negative


Copyright © 2002-2011 Joda.org. All Rights Reserved.