import {Interval} from '@js-joda/root/packages/extra/src/Interval.js'

public class | source

Interval

An immutable interval of time between two instants.

An interval represents the time on the time-line between two Instants. 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.

Static Method Summary

Static Public Methods
public static	of(startInstant: Instant, endInstantOrDuration: Instant \| Duration): Interval function overloading for Interval.of If called without arguments, then Interval.ofInstantInstant is executed.
public static	parse(text: string): Interval Obtains an instance of `Interval` from a text string such as `2007-12-03T10:15:30Z/2007-12-04T10:15:30Z`, where the end instant is exclusive.

Static Protected Methods
protected static	ofInstantDuration(startInclusive: Instant, duration: Duration): Interval Obtains an instance of `Interval` from the start and a duration.
protected static	ofInstantInstant(startInclusive: Instant, endExclusive: Instant): Interval Obtains an instance of `Interval` from the start and end instant.

Method Summary

Public Methods
public	abuts(other: Interval): boolean Checks if this interval abuts the specified interval.
public	contains(instant: Instant): boolean Checks if this interval contains the specified instant.
public	encloses(other: Interval): boolean Checks if this interval encloses the specified interval.
public	end(): Instant Gets the end of this time interval, exclusive.
public	equals(obj: *): boolean Checks if this interval is equal to another interval.
public	hashCode(): number A hash code for this interval.
public	intersection(other: Interval): Interval Calculates the interval that is the intersection of this interval and the specified interval.
public	isAfter(instantOrInterval: Instant \| Interval): boolean Function overloading for Interval#isAfter If called with an Instant, then Interval#isAfterInstant is executed.
public	isAfterInstant(instant: Instant): boolean Checks if this interval is after the specified instant.
public	isAfterInterval(interval: Interval): boolean Checks if this interval is after the specified interval.
public	isBefore(instantOrInterval: Instant \| Interval): boolean Function overloading for Interval#isBefore If called with an Instant, then Interval#isBeforeInstant is executed.
public	isBeforeInstant(instant: Instant): boolean Checks if this interval is before the specified instant.
public	isBeforeInterval(interval: Interval): boolean Checks if this interval is before the specified interval.
public	isConnected(other: Interval): boolean Checks if this interval is connected to the specified interval.
public	isEmpty(): boolean Checks if the range is empty.
public	isUnboundedEnd(): boolean Checks if the end of the interval is unbounded.
public	isUnboundedStart(): boolean Checks if the start of the interval is unbounded.
public	overlaps(other: Interval): boolean Checks if this interval overlaps the specified interval.
public	span(other: Interval): Interval Calculates the smallest interval that encloses this interval and the specified interval.
public	start(): Instant Gets the start of this time interval, inclusive.
public	toDuration(): Duration Obtains the duration of this interval.
public	toString(): string Outputs this interval as a `String`, such as `2007-12-03T10:15:30/2007-12-04T10:15:30`.
public	union(other: Interval): Interval Calculates the interval that is the union of this interval and the specified interval.
public	withEnd(end: Instant): Interval Returns a copy of this range with the specified end instant.
public	withStart(start: Instant): Interval Returns a copy of this range with the specified start instant.

Static Public Methods

public static of(startInstant: Instant, endInstantOrDuration: Instant | Duration): Interval source

function overloading for Interval.of

If called without arguments, then Interval.ofInstantInstant is executed.
If called with 1 arguments and first argument is an instance of ZoneId, then Interval.ofInstantDuration is executed.
Otherwise Interval.ofInstantDuration is executed.

Params:

Name	Type	Attribute	Description
startInstant	Instant
endInstantOrDuration	Instant \| Duration

Return:

Interval

public static parse(text: string): Interval source

Obtains an instance of Interval from a text string such as 2007-12-03T10:15:30Z/2007-12-04T10:15:30Z, where the end instant is exclusive.

The string must consist of one of the following three formats:

a representations of an ZonedDateTime, followed by a forward slash, followed by a representation of a ZonedDateTime
a representation of an ZonedDateTime, followed by a forward slash, followed by a representation of a Duration
a representation of a Duration, followed by a forward slash, followed by a representation of an ZonedDateTime

NOTE: in contrast to the threeten-extra base we are not using OffsetDateTime but ZonedDateTime to parse the string, this does not change the format but adds the possibility to optionally specify a zone

Params:

Name	Type	Attribute	Description
text	string		the text to parse, not null

Return:

Interval

the parsed interval, not null

Throw:

DateTimeParseException

if the text cannot be parsed

Static Protected Methods

protected static ofInstantDuration(startInclusive: Instant, duration: Duration): Interval source

Obtains an instance of Interval from the start and a duration.

The end instant is calculated as the start plus the duration. The duration must not be negative.

Params:

Name	Type	Attribute	Description
startInclusive	Instant		the start instant, inclusive, not null
duration	Duration		the duration from the start to the end, not null

Return:

Interval

the interval, not null

Throw:

DateTimeException	if the end is before the start, or if the duration addition cannot be made
ArithmeticException	if numeric overflow occurs when adding the duration

protected static ofInstantInstant(startInclusive: Instant, endExclusive: Instant): Interval source

Obtains an instance of Interval from the start and end instant.

The end instant must not be before the start instant.

Params:

Name	Type	Attribute	Description
startInclusive	Instant		the start instant, inclusive, MIN_DATE treated as unbounded, not null
endExclusive	Instant		the end instant, exclusive, MAX_DATE treated as unbounded, not null

Return:

Interval

the half-open interval, not null

Throw:

DateTimeException

if the end is before the start

Public Methods

public abuts(other: Interval): boolean source

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.

Params:

Name	Type	Attribute	Description
other	Interval		the other interval, not null

Return:

boolean

true if this interval abuts the other interval

public contains(instant: Instant): boolean source

Checks if this interval contains the specified instant.

This checks if the specified instant is within the bounds of this interval. If this range has an unbounded start then contains(Instant.MIN) returns true. If this range has an unbounded end then contains(Instant.MAX) returns true. If this range is empty then this method always returns false.

Params:

Name	Type	Attribute	Description
instant	Instant		the instant, not null

Return:

boolean

true if this interval contains the instant

public encloses(other: Interval): boolean source

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.

Params:

Name	Type	Attribute	Description
other	Interval		the other interval, not null

Return:

boolean

true if this interval contains the other interval

public end(): Instant source

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.

Return:

Instant

the end of the time interval, exclusive

public equals(obj: *): boolean source

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 type Interval are compared, other types return false.

Params:

Name	Type	Attribute	Description
obj	*		the object to check, null returns false

Return:

boolean

true if this is equal to the other interval

public hashCode(): number source

A hash code for this interval.

Return:

number

a suitable hash code

public intersection(other: Interval): Interval source

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 {@linkplain #isConnected(Interval) connected}.

Params:

Name	Type	Attribute	Description
other	Interval		the other interval to check for, not null

Return:

Interval

the interval that is the intersection of the two intervals

Throw:

DateTimeException

if the intervals do not connect

public isAfter(instantOrInterval: Instant | Interval): boolean source

Function overloading for Interval#isAfter

If called with an Instant, then Interval#isAfterInstant is executed.
Otherwise Interval#isAfterInterval is executed.

Params:

Name	Type	Attribute	Description
instantOrInterval	Instant \| Interval

Return:

boolean

public isAfterInstant(instant: Instant): boolean source

Checks if this interval is after the specified instant.

The result is true if the this instant starts after the specified instant. An empty interval behaves as though it is an instant for comparison purposes.

Params:

Name	Type	Attribute	Description
instant	Instant		the other instant to compare to, not null

Return:

boolean

true if the start of this interval is after the specified instant

public isAfterInterval(interval: Interval): boolean source

Checks if this interval is after the specified interval.

The result is true if the this instant starts after the end of the specified interval. 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.

Params:

Name	Type	Attribute	Description
interval	Interval		the other interval to compare to, not null

Return:

boolean

true if this instant is after the specified instant

public isBefore(instantOrInterval: Instant | Interval): boolean source

Function overloading for Interval#isBefore

If called with an Instant, then Interval#isBeforeInstant is executed.
Otherwise Interval#isBeforeInterval is executed.

Params:

Name	Type	Attribute	Description
instantOrInterval	Instant \| Interval

Return:

boolean

public isBeforeInstant(instant: Instant): boolean source

Checks if this interval is before the specified instant.

The result is true if the this instant 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.

Params:

Name	Type	Attribute	Description
instant	Instant		the other instant to compare to, not null

Return:

boolean

true if the start of this interval is before the specified instant

public isBeforeInterval(interval: Interval): boolean source

Checks if this interval is before the specified interval.

The result is true if the this instant 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.

Params:

Name	Type	Attribute	Description
interval	Interval		the other interval to compare to, not null

Return:

boolean

true if this instant is before the specified instant

public isConnected(other: Interval): boolean source

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)).

Params:

Name	Type	Attribute	Description
other	Interval		the other interval, not null

Return:

boolean

true if this interval is connected to the other interval

public isEmpty(): boolean source

Checks if the range is empty.

An empty range occurs when the start date equals the inclusive end date.

Return:

boolean

true if the range is empty

public isUnboundedEnd(): boolean source

Checks if the end of the interval is unbounded.

Return:

boolean

true if end is unbounded

public isUnboundedStart(): boolean source

Checks if the start of the interval is unbounded.

Return:

boolean

true if start is unbounded

public overlaps(other: Interval): boolean source

Checks if this interval overlaps the specified interval.

The result is true if the the two intervals share some part of the time-line. An empty interval overlaps itself.

This is equivalent to (isConnected(other) && !abuts(other)).

Params:

Name	Type	Attribute	Description
other	Interval		the time interval to compare to, null means a zero length interval now

Return:

boolean

true if the time intervals overlap

public span(other: Interval): Interval source

Calculates the smallest interval that encloses this interval and the specified interval.

The result of this method will {@linkplain #encloses(Interval) enclose} this interval and the specified interval.

Params:

Name	Type	Attribute	Description
other	Interval		the other interval to check for, not null

Return:

Interval

the interval that spans the two intervals

public start(): Instant source

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.

Return:

Instant

the start of the time interval

public toDuration(): Duration source

Obtains the duration of this interval.

An Interval is associated with two specific instants on the time-line. A Duration is simply an amount of time, separate from the time-line.

Return:

Duration

the duration of the time interval

Throw:

ArithmeticException

if the calculation exceeds the capacity of Duration

public toString(): string source

Outputs this interval as a String, such as 2007-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.

Return:

string

a string representation of this instant, not null

public union(other: Interval): Interval source

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 {@linkplain #isConnected(Interval) connected}.

Params:

Name	Type	Attribute	Description
other	Interval		the other interval to check for, not null

Return:

Interval

the interval that is the union of the two intervals

Throw:

DateTimeException

if the intervals do not connect

public withEnd(end: Instant): Interval source

Returns a copy of this range with the specified end instant.

Params:

Name	Type	Attribute	Description
end	Instant		the end instant for the new interval, not null

Return:

Interval

an interval with the start from this interval and the specified end

Throw:

DateTimeException

if the resulting interval has end before start

public withStart(start: Instant): Interval source

Returns a copy of this range with the specified start instant.

Params:

Name	Type	Attribute	Description
start	Instant		the start instant for the new interval, not null

Return:

Interval

an interval with the end from this interval and the specified start

Throw:

DateTimeException

if the resulting interval has end before start