Interval

The Interval immutable class represents a time interval between two points in time, defined by a start and end DateTime. It provides a variety of methods for creation, formatting, comparison, calculation, and conversion of interval instances.

TIP

All instances of Interval are immutable!

So all manipulation methods return a new instance of interval.

Instance Properties
Instance Methods
Static Properties
Static Methods

Instance Properties

`start`

Return the start of the interval.

Type: DateTime

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
console.log(interval.start.toString()); // 2024-12-07 13:56:19:920 UTC+01:00

`end`

Return the end of the interval.

Type: DateTime

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
console.log(interval.end.toString()); // 2024-12-09 13:56:19:920 UTC+01:00

`duration`

Return the duration of the interval.

Type: Duration

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
console.log(interval.duration.toString()); // 2 days 00:00:00

Instance Methods

`valueOf`

Returns the total interval duration in milliseconds.

typescript

valueOf(): number

Parameters: void
Returns: number
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
console.log(interval.valueOf()); // 172800000

`toString`

Returns the human-readable string representation of the interval.

typescript

toString(): string

Parameters: void
Returns: string
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
console.log(interval.toString()); // [ 2024-12-07 13:56:19.920 UTC+01:00 , 2024-12-09 13:56:19.920 UTC+01:00 )

`[Symbol.toPrimitive]`

Custom implementation to handle coercion.

typescript

[Symbol.toPrimitive](hint: string): number | string

Parameters:
- hint:
  - description: The hint type ("number" or "string")
  - Type: string
Returns: string | number
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
console.log(+interval); // 172800000
console.log(`${interval}`); // [ 2024-12-07 13:56:19.920 UTC+01:00 , 2024-12-09 13:56:19.920 UTC+01:00 )

`toJSON`

Returns the JSON serialization representation of the interval.

typescript

toJSON(): string

Parameters: void
Returns: string
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
console.log(interval.toJSON()); // "2024-12-07T13:56:19.920+01:00/2024-12-09T13:56:19.920+01:00"

`toISOString`

Returns the ISO 8601 representation of the interval.

typescript

toISOString(): string

Parameters: void
Returns: string
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
console.log(interval.toISOString()); // 2024-12-07T13:56:19.920+01:00/2024-12-09T13:56:19.920+01:00

`toObject`

Returns the object literal of the interval.

typescript

toObject(): Object

Parameters: void
Returns: Object
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
console.log(interval.toObject()); // {start: {year: 2024, month: 12, day: 7, hour: 13, minute: 56, second: 19, millisecond: 920, offset: { hour: 1 }}, end: {year: 2024, month: 12, day: 9, hour: 13, minute: 56, second: 19, millisecond: 920, offset: { hour: 1 }}}

`equals`

Returns whether the interval is equal to the other interval.

typescript

equals(other: Interval): boolean

Parameters:
- other:
  - description: The other interval to compare against.
  - Type: Interval
Returns: boolean
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval1 = Interval.between(start, end);
const interval2 = Interval.between(start, end);
console.log(interval1.equals(interval2)); // true

`withStart`

Return a new interval with start replaced.

typescript

withStart(start: DateTime): Interval

Parameters:
- start:
  - description: The start to replace the old one.
  - Type: DateTime
Returns: Interval
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
const newStart = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 4,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const intervalWithStart = interval.withStart(newStart);
console.log(intervalWithStart.toString()); // [ 2024-12-04 13:56:19.920 UTC+01:00 , 2024-12-09 13:56:19.920 UTC+01:00 )

`withEnd`

Return a new interval with end replaced.

typescript

withEnd(end: DateTime): Interval

Parameters:
- end:
  - description: The end to replace the old one.
  - Type: DateTime
Returns: Interval
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
const newEnd = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 11,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const intervalWithEnd = interval.withEnd(newEnd);
console.log(intervalWithEnd.toString()); // [ 2024-12-07 13:56:19.920 UTC+01:00 , 2024-12-11 13:56:19.920 UTC+01:00 )

Static Properties

None

Static Methods

`between`

Return a new interval between a start and an end datetime.

typescript

Interval.between(start: DateTime, end: DateTime): Interval

Parameters:
- start:
  - description: the start datetime.
  - Type: DateTime
- end:
  - description: the end datetime.
  - Type: DateTime
Returns: Interval
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.between(start, end);
console.log(interval.toString()); // [ 2024-12-07 13:56:19.920 UTC+01:00 , 2024-12-09 13:56:19.920 UTC+01:00 )

`since`

Return a new interval since a datetime until now.

typescript

Interval.since(datetime: DateTime): Interval

Parameters:
- datetime:
  - description: the datetime.
  - Type: DateTime
Returns: Interval
Throws: void

Example:

typescript

const datetime = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.since(datetime);
console.log(interval.toString()); // [ 2024-12-07 13:56:19.920 UTC+01:00 , 2024-12-09 13:56:19.920 UTC+01:00 ) - now is assumed to be "2024-12-09 13:56:19.920 UTC+01:00" in this case

`until`

Return a new interval since now until a datetime.

typescript

Interval.until(datetime: DateTime): Interval

Parameters:
- datetime:
  - description: the datetime.
  - Type: DateTime
Returns: Interval
Throws: void

Example:

typescript

const datetime = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval = Interval.until(datetime);
console.log(interval.toString()); // [ 2024-12-07 13:56:19.920 UTC+01:00 , 2024-12-09 13:56:19.920 UTC+01:00 ) - now is assumed to be "2024-12-07 13:56:19.920 UTC+01:00" in this case

`fromObject`

Return a new interval from an object literal.

typescript

Interval.fromObject(object: Object): Interval

Parameters:
- object:
  - description: the object literal.
  - Type: Object
Returns: Interval
Throws: void

Example:

typescript

const interval = Interval.fromObject({
  start: {
    year: 2024,
    month: 12,
    day: 7,
    hour: 13,
    minute: 56,
    second: 19,
    millisecond: 920,
    offset: { hour: 1 },
  },
  end: {
    year: 2024,
    month: 12,
    day: 9,
    hour: 13,
    minute: 56,
    second: 19,
    millisecond: 920,
    offset: { hour: 1 },
  },
});
console.log(interval.toString()); // [ 2024-12-07 13:56:19.920 UTC+01:00 , 2024-12-09 13:56:19.920 UTC+01:00 )

`fromString`

Return a new interval from a human-readable string representation.

typescript

Interval.fromString(str: string): Interval

Parameters:
- str:
  - description: the human-readable string representation.
  - Type: string
Returns: Interval
Throws: void

Example:

typescript

const interval = Interval.fromString(
  "[ 2024-12-07 13:56:19.920 UTC+01:00 , 2024-12-09 13:56:19.920 UTC+01:00 )"
);
console.log(interval.toObject()); // {start: {year: 2024, month: 12, day: 7, hour: 13, minute: 56, second: 19, millisecond: 920, offset: { hour: 1 }}, end: {year: 2024, month: 12, day: 9, hour: 13, minute: 56, second: 19, millisecond: 920, offset: { hour: 1 }}}

`fromISOString`

Return a new interval from an ISO 8601 representation.

typescript

Interval.fromISOString(str: string): Interval

Parameters:
- str:
  - description: the ISO 8601 representation.
  - Type: string
Returns: Interval
Throws: void

Example:

typescript

const interval = Interval.fromISOString(
  "2024-12-07T13:56:19.920+01:00/2024-12-09T13:56:19.920+01:00"
);
console.log(interval.toObject()); // {start: {year: 2024, month: 12, day: 7, hour: 13, minute: 56, second: 19, millisecond: 920, offset: { hour: 1 }}, end: {year: 2024, month: 12, day: 9, hour: 13, minute: 56, second: 19, millisecond: 920, offset: { hour: 1 }}}

`parse`

Return a new interval from any possible string.

typescript

Interval.parse(str: string): Interval

Parameters:
- str:
  - description: the string.
  - Type: string
Returns: Interval
Throws: void

Example:

typescript

const interval = Interval.parse(
  "[ 2024-12-07 13:56:19.920 UTC+01:00 , 2024-12-09 13:56:19.920 UTC+01:00 )"
);
console.log(interval.toObject()); // {start: {year: 2024, month: 12, day: 7, hour: 13, minute: 56, second: 19, millisecond: 920, offset: { hour: 1 }}, end: {year: 2024, month: 12, day: 9, hour: 13, minute: 56, second: 19, millisecond: 920, offset: { hour: 1 }}}

`compare`

Returns the difference between two intervals.

TIP

This method is useful for sorting Interval instances in an array.

typescript

Interval.compare(interval1: Interval, interval2: Interval): number

Parameters:
- interval1:
  - description: The first interval.
  - Type: Interval
- interval2:
  - description: The second interval.
  - Type: Interval
Returns: number
Throws: void

Example:

typescript

const start = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 7,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const end = DateTime.fromObject({
  year: 2024,
  month: 12,
  day: 9,
  hour: 13,
  minute: 56,
  second: 19,
  millisecond: 920,
  offset: { hour: 1 },
});
const interval1 = Interval.between(start, end);
const interval2 = Interval.between(start, end);
console.log(Interval.compare(interval1, interval2)); // 0

Interval ​

Table of Contents ​

Instance Properties ​

start ​

end ​

duration ​

Instance Methods ​

valueOf ​

toString ​

[Symbol.toPrimitive] ​

toJSON ​

toISOString ​

toObject ​

equals ​

withStart ​

withEnd ​

Static Properties ​

Static Methods ​

between ​

since ​

until ​

fromObject ​

fromString ​

fromISOString ​

parse ​

compare ​

Interval

Table of Contents

Instance Properties

`start`

`end`

`duration`

Instance Methods

`valueOf`

`toString`

`[Symbol.toPrimitive]`

`toJSON`

`toISOString`

`toObject`

`equals`

`withStart`

`withEnd`

Static Properties

Static Methods

`between`

`since`

`until`

`fromObject`

`fromString`

`fromISOString`

`parse`

`compare`