0
# Interval API
1

2
The Interval class represents time ranges between two DateTimes. It provides methods for interval relationships, set operations, splitting intervals, and converting to other representations.
3

4
## Capabilities
5

6
### Static Factory Methods
7

8
Methods for creating Interval instances.
9

10
```javascript { .api }
11
/**
12
 * Create an invalid Interval
13
 * @param reason - Reason for invalidity
14
 * @param explanation - Additional explanation
15
 */
16
static invalid(reason: string, explanation?: string): Interval;
17

18
/**
19
 * Create Interval from start and end DateTimes
20
 * @param start - Start DateTime
21
 * @param end - End DateTime
22
 */
23
static fromDateTimes(start: DateTime, end: DateTime): Interval;
24

25
/**
26
 * Create Interval from start DateTime plus Duration
27
 * @param start - Start DateTime
28
 * @param duration - Duration to add to start
29
 */
30
static after(start: DateTime, duration: Duration): Interval;
31

32
/**
33
 * Create Interval from end DateTime minus Duration
34
 * @param end - End DateTime
35
 * @param duration - Duration to subtract from end
36
 */
37
static before(end: DateTime, duration: Duration): Interval;
38

39
/**
40
 * Parse Interval from ISO 8601 interval string
41
 * @param text - ISO 8601 interval string (e.g., "2023-01-01/2023-01-31")
42
 * @param opts - Options including setZone
43
 */
44
static fromISO(text: string, opts?): Interval;
45

46
/**
47
 * Check if object is an Interval instance
48
 * @param o - Object to check
49
 */
50
static isInterval(o: any): boolean;
51
```
52

53
### Static Utility Methods
54

55
Methods for working with arrays of intervals.
56

57
```javascript { .api }
58
/**
59
 * Merge overlapping intervals in array
60
 * @param intervals - Array of intervals to merge
61
 */
62
static merge(intervals: Interval[]): Interval[];
63

64
/**
65
 * Find symmetric difference of intervals
66
 * @param intervals - Array of intervals
67
 */
68
static xor(intervals: Interval[]): Interval[];
69
```
70

71
### Instance Properties
72

73
Access interval endpoints and validation.
74

75
```javascript { .api }
76
// Endpoints
77
start: DateTime;
78
end: DateTime;
79

80
// Validation
81
isValid: boolean;
82
invalidReason: string | null;
83
invalidExplanation: string | null;
84
```
85

86
### Instance Methods
87

88
#### Length and Duration
89

90
```javascript { .api }
91
/**
92
 * Length of interval as Duration
93
 * @param unit - Unit for the length (optional)
94
 */
95
length(unit?: string): number;
96

97
/**
98
 * Count of calendar periods in interval
99
 * @param unit - Calendar unit (years, months, days, etc.)
100
 */
101
count(unit: string): number;
102

103
/**
104
 * Check if start and end are in same time unit
105
 * @param unit - Unit to check (year, month, day, etc.)
106
 */
107
hasSame(unit: string): boolean;
108

109
/**
110
 * Check if interval is empty (start equals end)
111
 */
112
isEmpty(): boolean;
113
```
114

115
#### DateTime Relationships
116

117
```javascript { .api }
118
/**
119
 * Check if interval is after specified DateTime
120
 * @param dateTime - DateTime to compare against
121
 */
122
isAfter(dateTime: DateTime): boolean;
123

124
/**
125
 * Check if interval is before specified DateTime
126
 * @param dateTime - DateTime to compare against
127
 */
128
isBefore(dateTime: DateTime): boolean;
129

130
/**
131
 * Check if interval contains specified DateTime
132
 * @param dateTime - DateTime to check
133
 */
134
contains(dateTime: DateTime): boolean;
135
```
136

137
#### Modification
138

139
```javascript { .api }
140
/**
141
 * Set start and/or end DateTime
142
 * @param values - Object with start and/or end properties
143
 */
144
set(values: {start?: DateTime, end?: DateTime}): Interval;
145
```
146

147
#### Splitting
148

149
```javascript { .api }
150
/**
151
 * Split interval at specified DateTimes
152
 * @param dateTimes - DateTimes to split at
153
 */
154
splitAt(...dateTimes: DateTime[]): Interval[];
155

156
/**
157
 * Split interval by duration increments
158
 * @param duration - Duration for each split
159
 */
160
splitBy(duration: Duration): Interval[];
161

162
/**
163
 * Divide interval into equal parts
164
 * @param numberOfParts - Number of equal parts
165
 */
166
divideEqually(numberOfParts: number): Interval[];
167
```
168

169
#### Interval Relationships
170

171
```javascript { .api }
172
/**
173
 * Check if this interval overlaps with another
174
 * @param other - Other interval to check
175
 */
176
overlaps(other: Interval): boolean;
177

178
/**
179
 * Check if this interval's end abuts other's start
180
 * @param other - Other interval to check
181
 */
182
abutsStart(other: Interval): boolean;
183

184
/**
185
 * Check if this interval's start abuts other's end
186
 * @param other - Other interval to check
187
 */
188
abutsEnd(other: Interval): boolean;
189

190
/**
191
 * Check if this interval completely contains another
192
 * @param other - Other interval to check
193
 */
194
engulfs(other: Interval): boolean;
195

196
/**
197
 * Check equality with other Interval
198
 * @param other - Interval to compare
199
 */
200
equals(other: Interval): boolean;
201
```
202

203
#### Set Operations
204

205
```javascript { .api }
206
/**
207
 * Return intersection with another interval
208
 * @param other - Other interval
209
 */
210
intersection(other: Interval): Interval | null;
211

212
/**
213
 * Return union with another interval (if they overlap or abut)
214
 * @param other - Other interval
215
 */
216
union(other: Interval): Interval | null;
217

218
/**
219
 * Return intervals representing difference from other intervals
220
 * @param intervals - Intervals to subtract from this one
221
 */
222
difference(...intervals: Interval[]): Interval[];
223
```
224

225
#### String Representation
226

227
```javascript { .api }
228
/**
229
 * String representation
230
 */
231
toString(): string;
232

233
/**
234
 * ISO 8601 interval string
235
 * @param opts - Options for formatting DateTimes
236
 */
237
toISO(opts?): string;
238

239
/**
240
 * ISO 8601 date interval string (dates only)
241
 */
242
toISODate(): string;
243

244
/**
245
 * ISO 8601 time interval string (times only)
246
 * @param opts - Options for time formatting
247
 */
248
toISOTime(opts?): string;
249

250
/**
251
 * Format interval with custom format
252
 * @param dateFormat - Format for start and end DateTimes
253
 * @param opts - Options for formatting
254
 */
255
toFormat(dateFormat: string, opts?): string;
256
```
257

258
#### Conversion
259

260
```javascript { .api }
261
/**
262
 * Convert interval to Duration
263
 * @param unit - Unit for the duration (optional)
264
 * @param opts - Options including conversionAccuracy
265
 */
266
toDuration(unit?: string, opts?): Duration;
267

268
/**
269
 * Transform endpoints with function
270
 * @param mapFn - Function to transform each endpoint
271
 */
272
mapEndpoints(mapFn: (dt: DateTime) => DateTime): Interval;
273
```
274

275
## Usage Examples
276

277
```javascript
278
import { DateTime, Duration, Interval } from "luxon";
279

280
// Creating intervals
281
const start = DateTime.local(2023, 10, 1);
282
const end = DateTime.local(2023, 10, 31);
283
const interval = Interval.fromDateTimes(start, end);
284

285
// Alternative creation methods
286
const afterStart = Interval.after(start, Duration.fromObject({ days: 30 }));
287
const beforeEnd = Interval.before(end, Duration.fromObject({ days: 30 }));
288
const fromISO = Interval.fromISO("2023-10-01/2023-10-31");
289

290
// Basic properties
291
console.log(interval.length('days')); // 30
292
console.log(interval.count('weeks')); // 4
293
console.log(interval.isEmpty()); // false
294

295
// DateTime relationships
296
const midMonth = DateTime.local(2023, 10, 15);
297
console.log(interval.contains(midMonth)); // true
298
console.log(interval.isAfter(DateTime.local(2023, 9, 30))); // true
299

300
// Splitting intervals
301
const weeklyIntervals = interval.splitBy(Duration.fromObject({ weeks: 1 }));
302
const quarters = interval.divideEqually(4);
303

304
// Interval relationships
305
const overlap = Interval.fromDateTimes(
306
  DateTime.local(2023, 10, 15), 
307
  DateTime.local(2023, 11, 15)
308
);
309
console.log(interval.overlaps(overlap)); // true
310

311
// Set operations
312
const intersection = interval.intersection(overlap);
313
const union = interval.union(overlap);
314

315
// Formatting
316
console.log(interval.toISO()); // "2023-10-01T00:00:00.000-07:00/2023-10-31T00:00:00.000-07:00"
317
console.log(interval.toFormat("yyyy-MM-dd")); // "2023-10-01 – 2023-10-31"
318

319
// Working with arrays of intervals
320
const intervals = [
321
  Interval.fromDateTimes(DateTime.local(2023, 1, 1), DateTime.local(2023, 1, 15)),
322
  Interval.fromDateTimes(DateTime.local(2023, 1, 10), DateTime.local(2023, 1, 20)),
323
  Interval.fromDateTimes(DateTime.local(2023, 1, 25), DateTime.local(2023, 1, 31))
324
];
325

326
const merged = Interval.merge(intervals); // Merges overlapping intervals
327
```
328

329
## Interval Relationships Diagram
330

331
```
332
Interval A: |-------|
333
Interval B:     |-------|  (overlaps)
334
Interval C:             |-------| (abuts)
335
Interval D:   |---|              (engulfed by A)
336
Interval E: |------------------|  (engulfs A)
337
```
338

339
## ISO 8601 Interval Formats
340

341
Luxon supports these ISO 8601 interval formats:
342

343
- `start/end`: `2023-01-01T00:00:00Z/2023-01-31T23:59:59Z`
344
- `start/duration`: `2023-01-01T00:00:00Z/P1M`
345
- `duration/end`: `P1M/2023-01-31T23:59:59Z`