Class Interval

An Interval object represents a half-open interval of time, where each endpoint is a DateTime. Conceptually, it's a container for those two endpoints, accompanied by methods for creating, parsing, interrogating, comparing, transforming, and formatting them.

Here is a brief overview of the most commonly used methods and getters in Interval:

Creation To create an Interval, use fromDateTimes, after, before, or fromISO.
Accessors Use start and end to get the start and end.
Interrogation To analyze the Interval, use count, length, hasSame, contains, isAfter, or isBefore.
Transformation To create other Intervals out of this one, use set, splitAt, splitBy, divideEqually, merge, xor, union, intersection, or difference.
Comparison To compare this Interval to another one, use equals, overlaps, abutsStart, abutsEnd, engulfs
Output To convert the Interval into other representations, see toString, toISO, toISODate, toISOTime, toFormat, and toDuration.

Hierarchy

Interval

Accessors

end

get end(): null | DateTime
Returns the end of the Interval

Returns null | DateTime
- Defined in interval.ts:127

invalidReason

get invalidReason(): null | string
Returns an error code if this Interval is invalid, or null if the Interval is valid

Returns null | string
- Defined in interval.ts:75

isValid

get isValid(): boolean
Returns whether this Interval's end is at least its start, meaning that the Interval isn't 'backwards'.

Returns boolean
- Defined in interval.ts:83

start

get start(): null | DateTime
Returns the start of the Interval

Returns null | DateTime
- Defined in interval.ts:119

Methods

abutsEnd

abutsEnd(other: Interval): boolean
Return whether this Interval's start is adjacent to the specified Interval's end.

Returns
Parameters
- other: Interval
Returns boolean
- Defined in interval.ts:502

abutsStart

abutsStart(other: Interval): boolean
Return whether this Interval's end is adjacent to the specified Interval's start.

Returns
Parameters
- other: Interval
Returns boolean
- Defined in interval.ts:493

contains

contains(dateTime: DateTime): boolean
Return whether this Interval contains the specified DateTime.

Returns
Parameters
- dateTime: DateTime
Returns boolean
- Defined in interval.ts:396

count

count(unit??: keyof DurationObject): number
Returns the count of minutes, hours, days, months, or years included in the Interval, even in part. Unlike length this counts sections of the calendar, not periods of time, e.g. specifying 'day' asks 'what dates are included in this interval?', not 'how many days long is this interval?'

Returns
Parameters
- Optional unit: keyof DurationObject = "milliseconds"
  
  the unit of time to count.
Returns number
- Defined in interval.ts:337

difference

difference(...intervals: Interval[]): Interval[]
Returns Intervals representing the span(s) of time in this Interval that don't overlap with any of the specified Intervals.

Returns
Parameters
- Rest ...intervals: Interval[]
Returns Interval[]
- Defined in interval.ts:574

divideEqually

divideEqually(numberOfParts: number): Interval[]
Split this Interval into the specified number of smaller intervals.

Returns
Parameters
- numberOfParts: number
  
  The number of Intervals to divide the Interval into.
Returns Interval[]
- Defined in interval.ts:472

engulfs

engulfs(other: Interval): boolean
Return whether this Interval engulfs the start and end of the specified Interval.

Returns
Parameters
- other: Interval
Returns boolean
- Defined in interval.ts:511

equals

equals(other: Interval): boolean
Return whether this Interval has the same start and end as the specified Interval.

Returns
Parameters
- other: Interval
Returns boolean
- Defined in interval.ts:524

hasSame

hasSame(unit: keyof DurationObject): boolean
Returns whether this Interval's start and end are both in the same unit of time

Returns
Parameters
- unit: keyof DurationObject
  
  the unit of time to check sameness on
Returns boolean
- Defined in interval.ts:353

intersection

intersection(other: Interval): null | Interval
Return an Interval representing the intersection of this Interval and the specified Interval. Specifically, the resulting Interval has the maximum start time and the minimum end time of the two Intervals. Returns null if the intersection is empty, meaning, the intervals don't intersect.

Returns
Parameters
- other: Interval
Returns null | Interval
- Defined in interval.ts:539

isAfter

isAfter(dateTime: DateTime): boolean
Return whether this Interval's start is after the specified DateTime.

Returns
Parameters
- dateTime: DateTime
Returns boolean
- Defined in interval.ts:370

isBefore

isBefore(dateTime: DateTime): boolean
Return whether this Interval's end is before the specified DateTime.

Returns
Parameters
- dateTime: DateTime
Returns boolean
- Defined in interval.ts:383

isEmpty

isEmpty(): boolean
Return whether this Interval has the same start and end DateTimes.

Returns

Returns boolean
- Defined in interval.ts:361

length

length(unit??: keyof DurationObject): number
Returns the length of the Interval in the specified unit.

Returns
Parameters
- Optional unit: keyof DurationObject = "milliseconds"
  
  the unit (such as 'hours' or 'days') to return the length in.
Returns number
- Defined in interval.ts:326

mapEndpoints

mapEndpoints(mapFn: ((dt: DateTime) => DateTime)): Interval
Run mapFn on the interval start and end, returning a new Interval from the resulting DateTimes

Returns

Example
```
Interval.fromDateTimes(dt1, dt2).mapEndpoints(endpoint => endpoint.toUTC())
```
Example
```
Interval.fromDateTimes(dt1, dt2).mapEndpoints(endpoint => endpoint.plus({ hours: 2 }))
```
Parameters
- mapFn: ((dt: DateTime) => DateTime)
  - - (dt: DateTime): DateTime
    - Parameters
      
      dt: DateTime
      
      Returns DateTime
Returns Interval
- Defined in interval.ts:675

overlaps

overlaps(other: Interval): boolean
Return whether this Interval overlaps with the specified Interval

Returns
Parameters
- other: Interval
Returns boolean
- Defined in interval.ts:484

set

set(values?: IntervalObject): Interval
"Sets" the start and/or end dates. Returns a newly-constructed Interval.

Returns
Parameters
- values: IntervalObject = {}
  
  the values to set
Returns Interval
- Defined in interval.ts:407

splitAt

splitAt(...dateTimes: DateTimeLike[]): Interval[]
Split this Interval at each of the specified DateTimes

Returns
Parameters
- Rest ...dateTimes: DateTimeLike[]
  
  the unit of time to count.
Returns Interval[]
- Defined in interval.ts:419

splitBy

splitBy(duration: DurationLike): Interval[]
Split this Interval into smaller Intervals, each of the specified length. Left over time is grouped into a smaller interval

Returns
Parameters
- duration: DurationLike
  
  The length of each resulting interval, as a Duration object.
Returns Interval[]
- Defined in interval.ts:445

toDuration

toDuration(unit??: keyof DurationObject | (keyof DurationObject)[], opts?: DurationOptions): Duration

Return a Duration representing the time spanned by this interval.

Example

Interval.fromDateTimes(dt1, dt2).toDuration().toObject() //=> { milliseconds: 88489257 }

Example

Interval.fromDateTimes(dt1, dt2).toDuration('days').toObject() //=> { days: 1.0241812152777778 }

Example

Interval.fromDateTimes(dt1, dt2).toDuration(['hours', 'minutes']).toObject() //=> { hours: 24, minutes: 34.82095 }

Example

Interval.fromDateTimes(dt1, dt2).toDuration(['hours', 'minutes', 'seconds']).toObject() //=> { hours: 24, minutes: 34, seconds: 49.257 }

Example

Interval.fromDateTimes(dt1, dt2).toDuration('seconds').toObject() //=> { seconds: 88489.257 }

Returns

Parameters

Optional unit: keyof DurationObject | (keyof DurationObject)[] = "milliseconds"

the unit or units (such as 'hours' or 'days') to include in the duration.
opts: DurationOptions = {}

options that affect the creation of the Duration

Returns Duration

toFormat

toFormat(dateFormat: string, options?: {
separator: string;
}): string
Returns a string representation of this Interval formatted according to the specified format string.

Returns
Parameters
- dateFormat: string
  
  the format string. This string formats the start and end time. See toFormat for details.
- options: {
  separator: string;
  } = ...
  
  options
  - separator: string
Returns string
- Defined in interval.ts:640

toISO

toISO(options?: ToISOTimeOptions): string
Returns an ISO 8601-compliant string representation of this Interval.

See
https://en.wikipedia.org/wiki/ISO_8601#Time_intervals

Returns
Parameters
- options: ToISOTimeOptions = {}
  
  The same options as toISO
Returns string
- Defined in interval.ts:598

toISODate

toISODate(): string
Returns an ISO 8601-compliant string representation of date of this Interval. The time components are ignored.

See
https://en.wikipedia.org/wiki/ISO_8601#Time_intervals

Returns

Returns string
- Defined in interval.ts:611

toISOTime

toISOTime(options?: ToISOTimeOptions): string
Returns an ISO 8601-compliant string representation of time of this Interval. The date components are ignored.

See
https://en.wikipedia.org/wiki/ISO_8601#Time_intervals

Returns
Parameters
- options: ToISOTimeOptions = {}
  
  The same options as toISO
Returns string
- Defined in interval.ts:626

toString

toString(): string
Returns a string representation of this Interval appropriate for debugging.

Returns

Returns string
- Defined in interval.ts:584

union

union(other: Interval): Interval
Return an Interval representing the union of this Interval and the specified Interval. Specifically, the resulting Interval has the minimum start time and the maximum end time of the two Intervals.

Returns
Parameters
- other: Interval
Returns Interval
- Defined in interval.ts:560

`Static` after

after(start: DateTimeLike, duration: DurationLike): Interval
Create an Interval from a start DateTime and a Duration to extend to.

Returns
Parameters
- start: DateTimeLike
- duration: DurationLike
  
  the length of the Interval, as a Duration object.
Returns Interval
- Defined in interval.ts:155

`Static` before

before(end: DateTimeLike, duration: DurationLike): Interval
Create an Interval from an end DateTime and a Duration to extend backwards to.

Returns
Parameters
- end: DateTimeLike
- duration: DurationLike
  
  the length of the Interval, as a Duration object.
Returns Interval
- Defined in interval.ts:171

`Static` fromDateTimes

fromDateTimes(start: DateTimeLike, end: DateTimeLike): Interval
Create an Interval from a start DateTime and an end DateTime. Inclusive of the start but not the end.

Returns
Parameters
- start: DateTimeLike
- end: DateTimeLike
Returns Interval
- Defined in interval.ts:137

`Static` fromISO

fromISO(text: string, opts??: DateTimeOptions): Interval
Create an Interval from an ISO 8601 string. Accepts <start>/<end>, <start>/<duration>, and <duration>/<end> formats.

See
https://en.wikipedia.org/wiki/ISO_8601#Time_intervals

Returns
Parameters
- text: string
  
  the ISO string to parse
- Optional opts: DateTimeOptions = {}
  
  options to pass fromISO and optionally fromISO
Returns Interval
- Defined in interval.ts:189

`Static` invalid

invalid(reason: string | Invalid, explanation?: string): Interval
Create an invalid Interval.

Returns
Parameters
- reason: string | Invalid
  
  simple string of why this Interval is invalid. Should not contain parameters or anything else data-dependent
- Optional explanation: string
  
  longer explanation, may include parameters and other useful debugging information
Returns Interval
- Defined in interval.ts:234

`Static` isInterval

isInterval(o: unknown): o is Interval
Check if an object is an Interval. Works across context boundaries

Returns
Parameters
- o: unknown
Returns o is Interval
- Defined in interval.ts:254

`Static` merge

merge(intervals: Interval[]): Interval[]
Merge an array of Intervals into a equivalent minimal set of Intervals. Combines overlapping and adjacent Intervals.

Returns
Parameters
- intervals: Interval[]
Returns Interval[]
- Defined in interval.ts:264

`Static` xor

xor(intervals: Interval[]): Interval[]
Return an array of Intervals representing the spans of time that only appear in one of the specified Intervals.

Returns
Parameters
- intervals: Interval[]
Returns Interval[]
- Defined in interval.ts:292

Class Interval

Hierarchy

Index

Accessors

Methods

Accessors

end

Returns null | DateTime

invalidReason

Returns null | string

isValid

Returns boolean

start

Returns null | DateTime

Methods

abutsEnd

Returns

Parameters

other: Interval

Returns boolean

abutsStart

Returns

Parameters

other: Interval

Returns boolean

contains

Returns

Parameters

dateTime: DateTime

Returns boolean

count

Returns

Parameters

Optional unit: keyof DurationObject = "milliseconds"

Returns number

difference

Returns

Parameters

Rest ...intervals: Interval[]

Returns Interval[]

divideEqually

Returns

Parameters

numberOfParts: number

Returns Interval[]

engulfs

Returns

Parameters

other: Interval

Returns boolean

equals

Returns

Parameters

other: Interval

Returns boolean

hasSame

Returns

Parameters

unit: keyof DurationObject

Returns boolean

intersection

Returns

Parameters

other: Interval

Returns null | Interval

isAfter

Returns

Parameters

dateTime: DateTime

Returns boolean

isBefore

Returns

Parameters

dateTime: DateTime

Returns boolean

isEmpty

Returns

Returns boolean

length

Returns

`Optional` unit: keyof DurationObject = "milliseconds"

`Rest` ...intervals: Interval[]

`Optional` unit: keyof DurationObject = "milliseconds"

`Rest` ...dateTimes: DateTimeLike[]

`Optional` unit: keyof DurationObject | (keyof DurationObject)[] = "milliseconds"

options: {
separator: string;
} = ...