1 | import { DateTime, DateObjectUnits, DateTimeOptions, DiffOptions, ToISOTimeOptions } from './datetime';
|
2 | import { Duration, DurationLike, DurationUnit } from './duration';
|
3 |
|
4 | export interface IntervalObject {
|
5 | start?: DateTime | undefined;
|
6 | end?: DateTime | undefined;
|
7 | }
|
8 |
|
9 | export type DateInput = DateTime | DateObjectUnits | Date;
|
10 |
|
11 | /**
|
12 | * An Interval object represents a half-open interval of time, where each endpoint is a {@link DateTime}. Conceptually, it's a container for those two endpoints, accompanied by methods for
|
13 | * creating, parsing, interrogating, comparing, transforming, and formatting them.
|
14 | *
|
15 | * Here is a brief overview of the most commonly used methods and getters in Interval:
|
16 | *
|
17 | * * **Creation** To create an Interval, use {@link Interval.fromDateTimes}, {@link Interval.after}, {@link Interval.before}, or {@link Interval.fromISO}.
|
18 | * * **Accessors** Use {@link Interval#start} and {@link Interval#end} to get the start and end.
|
19 | * * **Interrogation** To analyze the Interval, use {@link Interval#count}, {@link Interval#length}, {@link Interval#hasSame},
|
20 | * * {@link Interval#contains}, {@link Interval#isAfter}, or {@link Interval#isBefore}.
|
21 | * * **Transformation** To create other Intervals out of this one, use {@link Interval#set}, {@link Interval#splitAt}, {@link Interval#splitBy}, {@link Interval#divideEqually},
|
22 | * * {@link Interval#merge}, {@link Interval#xor}, {@link Interval#union}, {@link Interval#intersection}, or {@link Interval#difference}.
|
23 | * * **Comparison** To compare this Interval to another one, use {@link Interval#equals}, {@link Interval#overlaps}, {@link Interval#abutsStart}, {@link Interval#abutsEnd}, {@link Interval#engulfs}
|
24 | * * **Output** To convert the Interval into other representations, see {@link Interval#toString}, {@link Interval#toISO}, {@link Interval#toISODate}, {@link Interval#toISOTime},
|
25 | * * {@link Interval#toFormat}, and {@link Interval#toDuration}.
|
26 | */
|
27 | export class Interval {
|
28 | /**
|
29 | * Create an invalid Interval.
|
30 | *
|
31 | * @param reason - simple string of why this Interval is invalid. Should not contain parameters or anything else data-dependent
|
32 | * @param explanation - longer explanation, may include parameters and other useful debugging information. Defaults to null.
|
33 | */
|
34 | static invalid(reason: string, explanation?: string): Interval;
|
35 |
|
36 | /**
|
37 | * Create an Interval from a start DateTime and an end DateTime. Inclusive of the start but not the end.
|
38 | *
|
39 | * @param start
|
40 | * @param end
|
41 | */
|
42 | static fromDateTimes(start: DateInput, end: DateInput): Interval;
|
43 |
|
44 | /**
|
45 | * Create an Interval from a start DateTime and a Duration to extend to.
|
46 | *
|
47 | * @param start
|
48 | * @param duration - the length of the Interval.
|
49 | */
|
50 | static after(start: DateInput, duration: DurationLike): Interval;
|
51 |
|
52 | /**
|
53 | * Create an Interval from an end DateTime and a Duration to extend backwards to.
|
54 | *
|
55 | * @param end
|
56 | * @param duration - the length of the Interval.
|
57 | */
|
58 | static before(end: DateInput, duration: DurationLike): Interval;
|
59 |
|
60 | /**
|
61 | * Create an Interval from an ISO 8601 string.
|
62 | * Accepts `<start>/<end>`, `<start>/<duration>`, and `<duration>/<end>` formats.
|
63 | * @see https://en.wikipedia.org/wiki/ISO_8601#Time_intervals
|
64 | *
|
65 | * @param text - the ISO string to parse
|
66 | * @param opts - options to pass {@link DateTime.fromISO} and optionally {@link Duration.fromISO}
|
67 | */
|
68 | static fromISO(text: string, opts?: DateTimeOptions): Interval;
|
69 |
|
70 | /**
|
71 | * Check if an object is an Interval. Works across context boundaries
|
72 | *
|
73 | * @param o
|
74 | */
|
75 | static isInterval(o: unknown): o is Interval;
|
76 |
|
77 | private constructor(config: unknown);
|
78 |
|
79 | /**
|
80 | * Returns the start of the Interval
|
81 | */
|
82 | get start(): DateTime;
|
83 |
|
84 | /**
|
85 | * Returns the end of the Interval
|
86 | */
|
87 | get end(): DateTime;
|
88 |
|
89 | /**
|
90 | * Returns whether this Interval's end is at least its start, meaning that the Interval isn't 'backwards'.
|
91 | */
|
92 | get isValid(): boolean;
|
93 |
|
94 | /**
|
95 | * Returns an error code if this Interval is invalid, or null if the Interval is valid
|
96 | */
|
97 | get invalidReason(): string;
|
98 |
|
99 | /**
|
100 | * Returns an explanation of why this Interval became invalid, or null if the Interval is valid
|
101 | */
|
102 | get invalidExplanation(): string;
|
103 |
|
104 | /**
|
105 | * Returns the length of the Interval in the specified unit.
|
106 | *
|
107 | * @param unit - the unit (such as 'hours' or 'days') to return the length in.
|
108 | */
|
109 | length(unit?: DurationUnit): number;
|
110 |
|
111 | /**
|
112 | * Returns the count of minutes, hours, days, months, or years included in the Interval, even in part.
|
113 | * Unlike {this counts sections of the calendar, not periods of time, e.g. specifying 'day'
Interval#length} |
114 | * asks 'what dates are included in this interval?', not 'how many days long is this interval?'
|
115 | *
|
116 | * 'milliseconds'.
unit - the unit of time to count. Defaults to |
117 | */
|
118 | count(unit?: DurationUnit): number;
|
119 |
|
120 | /**
|
121 | * Returns whether this Interval's start and end are both in the same unit of time
|
122 | *
|
123 | * @param unit - the unit of time to check sameness on
|
124 | */
|
125 | hasSame(unit: DurationUnit): boolean;
|
126 |
|
127 | /**
|
128 | * Return whether this Interval has the same start and end DateTimes.
|
129 | */
|
130 | isEmpty(): boolean;
|
131 |
|
132 | /**
|
133 | * Return whether this Interval's start is after the specified DateTime.
|
134 | *
|
135 | * @param dateTime
|
136 | */
|
137 | isAfter(dateTime: DateTime): boolean;
|
138 |
|
139 | /**
|
140 | * Return whether this Interval's end is before the specified DateTime.
|
141 | *
|
142 | * @param dateTime
|
143 | */
|
144 | isBefore(dateTime: DateTime): boolean;
|
145 |
|
146 | /**
|
147 | * Return whether this Interval contains the specified DateTime.
|
148 | *
|
149 | * @param dateTime
|
150 | */
|
151 | contains(dateTime: DateTime): boolean;
|
152 |
|
153 | /**
|
154 | * "Sets" the start and/or end dates. Returns a newly-constructed Interval.
|
155 | *
|
156 | * @param values - the values to set
|
157 | * @param values.start - the starting DateTime
|
158 | * @param values.end - the ending DateTime
|
159 | */
|
160 | set(values?: IntervalObject): Interval;
|
161 |
|
162 | /**
|
163 | * Split this Interval at each of the specified DateTimes
|
164 | *
|
165 | * @param dateTimes - the unit of time to count.
|
166 | */
|
167 | splitAt(...dateTimes: DateTime[]): Interval[];
|
168 |
|
169 | /**
|
170 | * Split this Interval into smaller Intervals, each of the specified length.
|
171 | * Left over time is grouped into a smaller interval
|
172 | *
|
173 | * @param duration - The length of each resulting interval.
|
174 | */
|
175 | splitBy(duration: DurationLike): Interval[];
|
176 |
|
177 | /**
|
178 | * Split this Interval into the specified number of smaller intervals.
|
179 | *
|
180 | * @param numberOfParts - The number of Intervals to divide the Interval into.
|
181 | */
|
182 | divideEqually(numberOfParts: number): Interval[];
|
183 |
|
184 | /**
|
185 | * Return whether this Interval overlaps with the specified Interval
|
186 | *
|
187 | * @param other
|
188 | */
|
189 | overlaps(other: Interval): boolean;
|
190 |
|
191 | /**
|
192 | * Return whether this Interval's end is adjacent to the specified Interval's start.
|
193 | *
|
194 | * @param other
|
195 | */
|
196 | abutsStart(other: Interval): boolean;
|
197 |
|
198 | /**
|
199 | * Return whether this Interval's start is adjacent to the specified Interval's end.
|
200 | *
|
201 | * @param other
|
202 | */
|
203 | abutsEnd(other: Interval): boolean;
|
204 |
|
205 | /**
|
206 | * Return whether this Interval engulfs the start and end of the specified Interval.
|
207 | *
|
208 | * @param other
|
209 | */
|
210 | engulfs(other: Interval): boolean;
|
211 |
|
212 | /**
|
213 | * Return whether this Interval has the same start and end as the specified Interval.
|
214 | *
|
215 | * @param other
|
216 | */
|
217 | equals(other: Interval): boolean;
|
218 |
|
219 | /**
|
220 | * Return an Interval representing the intersection of this Interval and the specified Interval.
|
221 | * Specifically, the resulting Interval has the maximum start time and the minimum end time of the two Intervals.
|
222 | * Returns null if the intersection is empty, meaning, the intervals don't intersect.
|
223 | *
|
224 | * @param other
|
225 | */
|
226 | intersection(other: Interval): Interval | null;
|
227 |
|
228 | /**
|
229 | * Return an Interval representing the union of this Interval and the specified Interval.
|
230 | * Specifically, the resulting Interval has the minimum start time and the maximum end time of the two Intervals.
|
231 | *
|
232 | * @param other
|
233 | */
|
234 | union(other: Interval): Interval;
|
235 |
|
236 | /**
|
237 | * Merge an array of Intervals into a equivalent minimal set of Intervals.
|
238 | * Combines overlapping and adjacent Intervals.
|
239 | *
|
240 | * @param intervals
|
241 | */
|
242 | static merge(intervals: Interval[]): Interval[];
|
243 |
|
244 | /**
|
245 | * Return an array of Intervals representing the spans of time that only appear in one of the specified Intervals.
|
246 | *
|
247 | * @param intervals
|
248 | */
|
249 | static xor(intervals: Interval[]): Interval[];
|
250 |
|
251 | /**
|
252 | * Return an Interval representing the span of time in this Interval that doesn't overlap with any of the specified Intervals.
|
253 | *
|
254 | * @param intervals
|
255 | */
|
256 | difference(...intervals: Interval[]): Interval[];
|
257 |
|
258 | /**
|
259 | * Returns a string representation of this Interval appropriate for debugging.
|
260 | */
|
261 | toString(): string;
|
262 |
|
263 | /**
|
264 | * Returns an ISO 8601-compliant string representation of this Interval.
|
265 | * @see https://en.wikipedia.org/wiki/ISO_8601#Time_intervals
|
266 | *
|
267 | * @param opts - The same options as {@link DateTime#toISO}
|
268 | */
|
269 | toISO(opts?: ToISOTimeOptions): string;
|
270 |
|
271 | /**
|
272 | * Returns an ISO 8601-compliant string representation of date of this Interval.
|
273 | * The time components are ignored.
|
274 | * @see https://en.wikipedia.org/wiki/ISO_8601#Time_intervals
|
275 | */
|
276 | toISODate(): string;
|
277 |
|
278 | /**
|
279 | * Returns an ISO 8601-compliant string representation of time of this Interval.
|
280 | * The date components are ignored.
|
281 | * @see https://en.wikipedia.org/wiki/ISO_8601#Time_intervals
|
282 | *
|
283 | * @param opts - The same options as {@link DateTime.toISO}
|
284 | */
|
285 | toISOTime(opts?: ToISOTimeOptions): string;
|
286 |
|
287 | /**
|
288 | * Returns a string representation of this Interval formatted according to the specified format string.
|
289 | *
|
290 | * @param dateFormat - the format string. This string formats the start and end time. See {@link DateTime.toFormat} for details.
|
291 | * @param opts - options
|
292 | * @param opts.separator - a separator to place between the start and end representations. Defaults to ' - '.
|
293 | */
|
294 | toFormat(
|
295 | dateFormat: string,
|
296 | opts?: {
|
297 | separator?: string | undefined;
|
298 | },
|
299 | ): string;
|
300 |
|
301 | /**
|
302 | * Return a Duration representing the time spanned by this interval.
|
303 | *
|
304 | * @param unit - the unit or units (such as 'hours' or 'days') to include in the duration. Defaults to ['milliseconds'].
|
305 | * @param opts - options that affect the creation of the Duration
|
306 | * @param opts.conversionAccuracy - the conversion system to use. Defaults to 'casual'.
|
307 | *
|
308 | * @example
|
309 | * Interval.fromDateTimes(dt1, dt2).toDuration().toObject() //=> { milliseconds: 88489257 }
|
310 | * @example
|
311 | * Interval.fromDateTimes(dt1, dt2).toDuration('days').toObject() //=> { days: 1.0241812152777778 }
|
312 | * @example
|
313 | * Interval.fromDateTimes(dt1, dt2).toDuration(['hours', 'minutes']).toObject() //=> { hours: 24, minutes: 34.82095 }
|
314 | * @example
|
315 | * Interval.fromDateTimes(dt1, dt2).toDuration(['hours', 'minutes', 'seconds']).toObject() //=> { hours: 24, minutes: 34, seconds: 49.257 }
|
316 | * @example
|
317 | * Interval.fromDateTimes(dt1, dt2).toDuration('seconds').toObject() //=> { seconds: 88489.257 }
|
318 | */
|
319 | toDuration(unit?: DurationUnit | DurationUnit[], opts?: DiffOptions): Duration;
|
320 |
|
321 | /**
|
322 | * Run mapFn on the interval start and end, returning a new Interval from the resulting DateTimes
|
323 | *
|
324 | * @param mapFn
|
325 | *
|
326 | * @example
|
327 | * Interval.fromDateTimes(dt1, dt2).mapEndpoints(endpoint => endpoint.toUTC())
|
328 | * @example
|
329 | * Interval.fromDateTimes(dt1, dt2).mapEndpoints(endpoint => endpoint.plus({ hours: 2 }))
|
330 | */
|
331 | mapEndpoints(mapFn: (d: DateTime) => DateTime): Interval;
|
332 | }
|