- java.lang.Object
-
- org.threeten.extra.Interval
-
- All Implemented Interfaces:
Serializable
public final class Interval extends Object implements Serializable
An immutable interval of time between two instants.An interval represents the time on the time-line between two
Instant
s. The class stores the start and end instants, with the start inclusive and the end exclusive. The end instant is always greater than or equal to the start instant.The
Duration
of an interval can be obtained, but is a separate concept. An interval is connected to the time-line, whereas a duration is not.Intervals are not comparable. To compare the length of two intervals, it is generally recommended to compare their durations.
Implementation Requirements:
This class is immutable and thread-safe.This class must be treated as a value type. Do not synchronize, rely on the identity hash code or use the distinction between equals() and ==.
- See Also:
- Serialized Form
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
abuts(Interval other)
Checks if this interval abuts the specified interval.boolean
contains(Instant instant)
Checks if this interval contains the specified instant.boolean
encloses(Interval other)
Checks if this interval encloses the specified interval.static Interval
endingAt(Instant endExclusive)
Obtains an instance ofInterval
with unbounded start and the specified end instant.boolean
endsAfter(Instant instant)
Checks if this interval ends after the specified instant.boolean
endsAtOrAfter(Instant instant)
Checks if this interval ends after the specified instant.boolean
endsAtOrBefore(Instant instant)
Checks if this interval ends at or before the specified instant.boolean
endsBefore(Instant instant)
Checks if this interval ends before the specified instant.boolean
equals(Object obj)
Checks if this interval is equal to another interval.Instant
getEnd()
Gets the end of this time interval, exclusive.Instant
getStart()
Gets the start of this time interval, inclusive.int
hashCode()
A hash code for this interval.Interval
intersection(Interval other)
Calculates the interval that is the intersection of this interval and the specified interval.boolean
isAfter(Instant instant)
Checks if this interval is after the specified instant.boolean
isAfter(Interval interval)
Checks if this interval is after the specified interval.boolean
isBefore(Instant instant)
Checks if this interval is before the specified instant.boolean
isBefore(Interval interval)
Checks if this interval is before the specified interval.boolean
isConnected(Interval other)
Checks if this interval is connected to the specified interval.boolean
isEmpty()
Checks if the range is empty.boolean
isUnboundedEnd()
Checks if the end of the interval is unbounded.boolean
isUnboundedStart()
Checks if the start of the interval is unbounded.static Interval
of(Instant startInclusive, Duration duration)
Obtains an instance ofInterval
from the start and a duration.static Interval
of(Instant startInclusive, Instant endExclusive)
Obtains an instance ofInterval
from the start and end instant.boolean
overlaps(Interval other)
Checks if this interval overlaps the specified interval.static Interval
parse(CharSequence text)
Obtains an instance ofInterval
from a text string such as2007-12-03T10:15:30Z/2007-12-04T10:15:30Z
, where the end instant is exclusive.Interval
span(Interval other)
Calculates the smallest interval that encloses this interval and the specified interval.static Interval
startingAt(Instant startInclusive)
Obtains an instance ofInterval
with the specified start instant and unbounded end.boolean
startsAfter(Instant instant)
Checks if this interval starts on or after the specified instant.boolean
startsAtOrAfter(Instant instant)
Checks if this interval starts at or after the specified instant.boolean
startsAtOrBefore(Instant instant)
Checks if this interval starts at or before the specified instant.boolean
startsBefore(Instant instant)
Checks if this interval starts on or before the specified instant.Duration
toDuration()
Obtains the duration of this interval.String
toString()
Outputs this interval as aString
, such as2007-12-03T10:15:30/2007-12-04T10:15:30
.Interval
union(Interval other)
Calculates the interval that is the union of this interval and the specified interval.Interval
withEnd(Instant end)
Returns a copy of this range with the specified end instant.Interval
withStart(Instant start)
Returns a copy of this range with the specified start instant.
-
-
-
Field Detail
-
ALL
public static final Interval ALL
An interval over the whole time-line.
-
-
Method Detail
-
of
public static Interval of(Instant startInclusive, Instant endExclusive)
Obtains an instance ofInterval
from the start and end instant.The end instant must not be before the start instant.
- Parameters:
startInclusive
- the start instant, inclusive,Instant.MIN
treated as unbounded, not nullendExclusive
- the end instant, exclusive,Instant.MAX
treated as unbounded, not null- Returns:
- the half-open interval, not null
- Throws:
DateTimeException
- if the end is before the start
-
of
public static Interval of(Instant startInclusive, Duration duration)
Obtains an instance ofInterval
from the start and a duration.The end instant is calculated as the start plus the duration. The duration must not be negative.
- Parameters:
startInclusive
- the start instant, inclusive, not nullduration
- the duration from the start to the end, not null- Returns:
- the interval, not null
- Throws:
DateTimeException
- if the end is before the start, or if the duration addition cannot be madeArithmeticException
- if numeric overflow occurs when adding the duration
-
startingAt
public static Interval startingAt(Instant startInclusive)
Obtains an instance ofInterval
with the specified start instant and unbounded end.- Parameters:
startInclusive
- the start instant, inclusive, not null- Returns:
- a new
Instant
with the specified start instant.
-
endingAt
public static Interval endingAt(Instant endExclusive)
Obtains an instance ofInterval
with unbounded start and the specified end instant.- Parameters:
endExclusive
- the end instant, exclusive, not null- Returns:
- a new
Instant
with the specified end instant.
-
parse
public static Interval parse(CharSequence text)
Obtains an instance ofInterval
from a text string such as2007-12-03T10:15:30Z/2007-12-04T10:15:30Z
, where the end instant is exclusive.The string must consist of one of the following four formats:
- a representations of an
OffsetDateTime
, followed by a forward slash, followed by a representation of aOffsetDateTime
- a representations of an
OffsetDateTime
, followed by a forward slash, followed by a representation of aLocalDateTime
, where the end offset is implied. - a representation of an
OffsetDateTime
, followed by a forward slash, followed by a representation of aPeriodDuration
- a representation of a
PeriodDuration
, followed by a forward slash, followed by a representation of anOffsetDateTime
ISO-8601 supports a very wide range of possible inputs, many of which are not supported here. For example, basic format, week-based dates, ordinal dates and date-style period formats are not supported.
- Parameters:
text
- the text to parse, not null- Returns:
- the parsed interval, not null
- Throws:
DateTimeParseException
- if the text cannot be parsed
- a representations of an
-
getStart
public Instant getStart()
Gets the start of this time interval, inclusive.This will return
Instant.MIN
if the range is unbounded at the start. In this case, the range includes all dates into the far-past.- Returns:
- the start of the time interval
-
getEnd
public Instant getEnd()
Gets the end of this time interval, exclusive.This will return
Instant.MAX
if the range is unbounded at the end. In this case, the range includes all dates into the far-future.- Returns:
- the end of the time interval, exclusive
-
isEmpty
public boolean isEmpty()
Checks if the range is empty.An empty range occurs when the start date equals the inclusive end date.
- Returns:
- true if the range is empty
-
isUnboundedStart
public boolean isUnboundedStart()
Checks if the start of the interval is unbounded.- Returns:
- true if start is unbounded
-
isUnboundedEnd
public boolean isUnboundedEnd()
Checks if the end of the interval is unbounded.- Returns:
- true if end is unbounded
-
withStart
public Interval withStart(Instant start)
Returns a copy of this range with the specified start instant.- Parameters:
start
- the start instant for the new interval, not null- Returns:
- an interval with the end from this interval and the specified start
- Throws:
DateTimeException
- if the resulting interval has end before start
-
withEnd
public Interval withEnd(Instant end)
Returns a copy of this range with the specified end instant.- Parameters:
end
- the end instant for the new interval, not null- Returns:
- an interval with the start from this interval and the specified end
- Throws:
DateTimeException
- if the resulting interval has end before start
-
encloses
public boolean encloses(Interval other)
Checks if this interval encloses the specified interval.This checks if the bounds of the specified interval are within the bounds of this interval. An empty interval encloses itself.
- Parameters:
other
- the other interval, not null- Returns:
- true if this interval contains the other interval
-
abuts
public boolean abuts(Interval other)
Checks if this interval abuts the specified interval.The result is true if the end of this interval is the start of the other, or vice versa. An empty interval does not abut itself.
- Parameters:
other
- the other interval, not null- Returns:
- true if this interval abuts the other interval
-
isConnected
public boolean isConnected(Interval other)
Checks if this interval is connected to the specified interval.The result is true if the two intervals have an enclosed interval in common, even if that interval is empty. An empty interval is connected to itself.
This is equivalent to
(overlaps(other) || abuts(other))
.- Parameters:
other
- the other interval, not null- Returns:
- true if this interval is connected to the other interval
-
overlaps
public boolean overlaps(Interval other)
Checks if this interval overlaps the specified interval.The result is true if the two intervals share some part of the time-line. An empty interval overlaps itself.
This is equivalent to
(isConnected(other) && !abuts(other))
.- Parameters:
other
- the time interval to compare to, null means a zero length interval now- Returns:
- true if the time intervals overlap
-
intersection
public Interval intersection(Interval other)
Calculates the interval that is the intersection of this interval and the specified interval.This finds the intersection of two intervals. This throws an exception if the two intervals are not connected.
- Parameters:
other
- the other interval to check for, not null- Returns:
- the interval that is the intersection of the two intervals
- Throws:
DateTimeException
- if the intervals do not connect
-
union
public Interval union(Interval other)
Calculates the interval that is the union of this interval and the specified interval.This finds the union of two intervals. This throws an exception if the two intervals are not connected.
- Parameters:
other
- the other interval to check for, not null- Returns:
- the interval that is the union of the two intervals
- Throws:
DateTimeException
- if the intervals do not connect
-
span
public Interval span(Interval other)
Calculates the smallest interval that encloses this interval and the specified interval.The result of this method will enclose this interval and the specified interval.
- Parameters:
other
- the other interval to check for, not null- Returns:
- the interval that spans the two intervals
-
isAfter
public boolean isAfter(Interval interval)
Checks if this interval is after the specified interval.The result is true if this interval starts after the end of the specified interval. Since intervals do not include their end points, this will return true if the two intervals abut. An empty interval behaves as though it is an instant for comparison purposes.
- Parameters:
interval
- the other interval to compare to, not null- Returns:
- true if this interval is after the specified interval
-
isBefore
public boolean isBefore(Interval interval)
Checks if this interval is before the specified interval.The result is true if this interval ends before the start of the specified interval. Since intervals do not include their end points, this will return true if the two intervals abut. An empty interval behaves as though it is an instant for comparison purposes.
- Parameters:
interval
- the other interval to compare to, not null- Returns:
- true if this interval is before the specified interval
-
startsBefore
public boolean startsBefore(Instant instant)
Checks if this interval starts on or before the specified instant.This method compares the start of the interval to the instant. An interval with an unbounded start is considered to start at
Instant.MIN
.- Parameters:
instant
- the instant, not null- Returns:
- true if this interval starts before the instant
-
startsAtOrBefore
public boolean startsAtOrBefore(Instant instant)
Checks if this interval starts at or before the specified instant.This method compares the start of the interval to the instant. An interval with an unbounded start is considered to start at
Instant.MIN
.- Parameters:
instant
- the instant, not null- Returns:
- true if this interval starts at or before the instant
-
startsAfter
public boolean startsAfter(Instant instant)
Checks if this interval starts on or after the specified instant.This method compares the start of the interval to the instant. An interval with an unbounded start is considered to start at
Instant.MIN
.- Parameters:
instant
- the instant, not null- Returns:
- true if this interval starts after the instant
-
startsAtOrAfter
public boolean startsAtOrAfter(Instant instant)
Checks if this interval starts at or after the specified instant.This method compares the start of the interval to the instant. An interval with an unbounded start is considered to start at
Instant.MIN
.- Parameters:
instant
- the instant, not null- Returns:
- true if this interval starts at or after the instant
-
endsBefore
public boolean endsBefore(Instant instant)
Checks if this interval ends before the specified instant.This method compares the end of the interval to the instant. An interval with an unbounded end is considered to end after
Instant.MAX
.- Parameters:
instant
- the instant, not null- Returns:
- true if this interval ends before the instant
-
endsAtOrBefore
public boolean endsAtOrBefore(Instant instant)
Checks if this interval ends at or before the specified instant.This method compares the end of the interval to the instant. An interval with an unbounded end is considered to end after
Instant.MAX
.- Parameters:
instant
- the instant, not null- Returns:
- true if this interval ends at or before the instant
-
endsAfter
public boolean endsAfter(Instant instant)
Checks if this interval ends after the specified instant.This method compares the end of the interval to the instant. An interval with an unbounded end is considered to end after
Instant.MAX
.- Parameters:
instant
- the instant, not null- Returns:
- true if this interval ends after the instant
-
endsAtOrAfter
public boolean endsAtOrAfter(Instant instant)
Checks if this interval ends after the specified instant.This method compares the end of the interval to the instant. An interval with an unbounded end is considered to end after
Instant.MAX
.- Parameters:
instant
- the instant, not null- Returns:
- true if this interval ends at or after the instant
-
contains
public boolean contains(Instant instant)
Checks if this interval contains the specified instant.This checks if the specified instant is within the bounds of this interval. If this interval has an unbounded start then
contains(Instant#MIN)
returns true. If this interval has an unbounded end thencontains(Instant#MAX)
returns true. Otherwise, if this interval is empty then this method returns false.This is equivalent to
startsAtOrBefore(Instant)
&&
endsAfter(Instant)
.- Parameters:
instant
- the instant, not null- Returns:
- true if this interval contains the instant
-
isAfter
public boolean isAfter(Instant instant)
Checks if this interval is after the specified instant.The result is true if this interval starts after the specified instant. An empty interval behaves as though it is an instant for comparison purposes.
This is equivalent to
startsAfter(Instant)
.- Parameters:
instant
- the other instant to compare to, not null- Returns:
- true if the start of this interval is after the specified instant
-
isBefore
public boolean isBefore(Instant instant)
Checks if this interval is before the specified instant.The result is true if this interval ends before the specified instant. Since intervals do not include their end points, this will return true if the instant equals the end of the interval. An empty interval behaves as though it is an instant for comparison purposes.
This is equivalent to
endsAtOrBefore(Instant)
&&
startsBefore(Instant)
.- Parameters:
instant
- the other instant to compare to, not null- Returns:
- true if the end of this interval is before or equal to the specified instant
-
toDuration
public Duration toDuration()
Obtains the duration of this interval.An
Interval
is associated with two specific instants on the time-line. ADuration
is simply an amount of time, separate from the time-line.- Returns:
- the duration of the time interval
- Throws:
ArithmeticException
- if the calculation exceeds the capacity ofDuration
-
equals
public boolean equals(Object obj)
Checks if this interval is equal to another interval.Compares this
Interval
with another ensuring that the two instants are the same. Only objects of typeInterval
are compared, other types return false.
-
hashCode
public int hashCode()
A hash code for this interval.
-
toString
public String toString()
Outputs this interval as aString
, such as2007-12-03T10:15:30/2007-12-04T10:15:30
.The output will be the ISO-8601 format formed by combining the
toString()
methods of the two instants, separated by a forward slash.
-
-