import { DateTime, DateTimeLike } from "./datetime.js"; import { Duration, DurationLike } from "./duration.js"; import { ToISOTimeOptions, DateTimeOptions } from "./types/datetime.js"; import { DurationUnit, DurationOptions } from "./types/duration.js"; import { IntervalObject } from "./types/interval.js"; import { Invalid } from "./types/invalid.js"; import { LocaleOptions } from "./types/locale.js"; /** * 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 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 {@link Interval.fromDateTimes}, {@link Interval.after}, {@link Interval.before}, or {@link Interval.fromISO}. * * **Accessors** Use {@link Interval#start} and {@link Interval#end} to get the start and end. * * **Interrogation** To analyze the Interval, use {@link Interval#count}, {@link Interval#length}, {@link Interval#hasSame}, {@link Interval#contains}, {@link Interval#isAfter}, or {@link Interval#isBefore}. * * **Transformation** To create other Intervals out of this one, use {@link Interval#set}, {@link Interval#splitAt}, {@link Interval#splitBy}, {@link Interval#divideEqually}, {@link Interval.merge}, {@link Interval.xor}, {@link Interval#union}, {@link Interval#intersection}, or {@link Interval#difference}. * * **Comparison** To compare this Interval to another one, use {@link Interval#equals}, {@link Interval#overlaps}, {@link Interval#abutsStart}, {@link Interval#abutsEnd}, {@link Interval#engulfs} * * **Output** To convert the Interval into other representations, see {@link Interval#toString}, {@link Interval#toLocaleString}, {@link Interval#toISO}, {@link Interval#toISODate}, {@link Interval#toISOTime}, {@link Interval#toFormat}, and {@link Interval#toDuration}. */ export declare class Interval { /** * Returns the end of the Interval. * This is the first instant that is not part of the interval (Interval is half-open). */ get end(): DateTime | null; /** * Returns an error code if this Interval is invalid, or null if the Interval is valid */ get invalidReason(): string | null; /** * Returns whether this Interval's end is at least its start, meaning that the Interval isn't 'backwards'. */ get isValid(): boolean; /** * Returns the last DateTime included in the interval (since end is not part of the interval) * @type {DateTime} */ get lastDateTime(): DateTime | null; /** * Returns the start of the Interval */ get start(): DateTime | null; private readonly _e; private readonly _invalid; private readonly _isLuxonInterval; private readonly _s; /** * @private */ private constructor(); /** * Create an Interval from a start DateTime and a Duration to extend to. * @param {DateTime|Date|Object} start * @param {Duration|Object} duration - the length of the Interval, as a Duration object. */ static after(start: DateTimeLike, duration: DurationLike): Interval; /** * Create an Interval from an end DateTime and a Duration to extend backwards to. * @param {DateTime|Date|Object} end * @param {Duration|Object} duration - the length of the Interval, as a Duration object. */ static before(end: DateTimeLike, duration: DurationLike): Interval; /** * Create an Interval from a start DateTime and an end DateTime. Inclusive of the start but not the end. * @param {DateTime|Date|Object} start * @param {DateTime|Date|Object} end */ static fromDateTimes(start: DateTimeLike, end: DateTimeLike): Interval; /** * Create an Interval from an ISO 8601 string. * Accepts `/`, `/`, and `/` formats. * @param {string} text - the ISO string to parse * @param {Object} [opts] - options to pass {@link DateTime.fromISO} and optionally {@link Duration.fromISO} * @see https://en.wikipedia.org/wiki/ISO_8601#Time_intervals */ static fromISO(text: string, opts?: DateTimeOptions): Interval; /** * Create an invalid Interval. * @param {string} reason - simple string of why this Interval is invalid. Should not contain parameters or anything else data-dependent * @param {string} [explanation=null] - longer explanation, may include parameters and other useful debugging information */ static invalid(reason: string | Invalid, explanation?: string): Interval; /** * Check if an object is an Interval. Works across context boundaries * @param {Object} o */ static isInterval(o: unknown): o is Interval; /** * Merge an array of Intervals into an equivalent minimal set of Intervals. * Combines overlapping and adjacent Intervals. * The resulting array will contain the Intervals in ascending order, that is, starting with the earliest Interval * and ending with the latest. * @param {Interval[]} intervals */ static merge(intervals: Interval[]): Interval[]; /** * Return an array of Intervals representing the spans of time that only appear in one of the specified Intervals. * @param {Interval[]} intervals * @return {Interval[]} */ static xor(intervals: Interval[]): Interval[]; /** * Return whether this Interval's start is adjacent to the specified Interval's end. * @param {Interval} other * @return {boolean} */ abutsEnd(other: Interval): boolean; /** * Return whether this Interval's end is adjacent to the specified Interval's start. * @param {Interval} other * @return {boolean} */ abutsStart(other: Interval): boolean; /** * Return whether this Interval contains the specified DateTime. * @param {DateTime} dateTime * @return {boolean} */ contains(dateTime: DateTime): boolean; /** * Returns the count of minutes, hours, days, months, or years included in the Interval, even in part. * Unlike {@link Interval#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?' * @param {string} [unit='milliseconds'] - the unit of time to count. * @param {Object} opts - options */ count(unit?: DurationUnit, opts?: { useLocaleWeeks?: boolean; }): number; /** * Returns Intervals representing the span(s) of time in this Interval that don't overlap with any of the specified Intervals. * @param {...Interval} intervals * @return {Interval[]} */ difference(...intervals: Interval[]): Interval[]; /** * Split this Interval into the specified number of smaller intervals. * @param {number} numberOfParts - The number of Intervals to divide the Interval into. * @return {Interval[]} */ divideEqually(numberOfParts: number): Interval[]; /** * Returns true if this Interval fully contains the specified Interval, * specifically if the intersection (of this Interval and the other Interval) is equal to the other Interval; * false otherwise. * @param {Interval} other * @return {boolean} */ engulfs(other: Interval): boolean; /** * Return whether this Interval has the same start and end as the specified Interval. * @param {Interval} other * @return {boolean} */ equals(other: Interval): boolean; /** * Returns whether this Interval's start and end are both in the same unit of time * @param {string} unit - the unit of time to check sameness on * @return {boolean} */ hasSame(unit: DurationUnit): boolean; /** * 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. * @param {Interval} other * @return {Interval|null} */ intersection(other: Interval): Interval; /** * Return whether this Interval's start is after the specified DateTime. * @param {DateTime} dateTime * @return {boolean} */ isAfter(dateTime: DateTime): boolean; /** * Return whether this Interval's end is before the specified DateTime. * @param {DateTime} dateTime * @return {boolean} */ isBefore(dateTime: DateTime): boolean; /** * Return whether this Interval has the same start and end DateTimes. * @return {boolean} */ isEmpty(): boolean; /** * Returns the length of the Interval in the specified unit. * @param {string} [unit='milliseconds'] - the unit (such as 'hours' or 'days') to return the length in. */ length(unit?: DurationUnit): number; /** * Run mapFn on the interval start and end, returning a new Interval from the resulting DateTimes * @param {function} mapFn * @return {Interval} * @example Interval.fromDateTimes(dt1, dt2).mapEndpoints(endpoint => endpoint.toUTC()) * @example Interval.fromDateTimes(dt1, dt2).mapEndpoints(endpoint => endpoint.plus({ hours: 2 })) */ mapEndpoints(mapFn: (dt: DateTime) => DateTime): Interval; /** * Return whether this Interval overlaps with the specified Interval * @param {Interval} other * @return {boolean} */ overlaps(other: Interval): boolean; /** * "Sets" the start and/or end dates. Returns a newly-constructed Interval. * @param {Object} values - the values to set * @param {DateTime} values.start - the starting DateTime * @param {DateTime} values.end - the ending DateTime * @return {Interval} */ set({ start, end }?: IntervalObject): Interval; /** * Split this Interval at each of the specified DateTimes * @param {...[DateTime]} dateTimes - the unit of time to count. * @return {Interval[]} */ splitAt(...dateTimes: DateTimeLike[]): Interval[]; /** * Split this Interval into smaller Intervals, each of the specified length. * Left over time is grouped into a smaller interval * @param {Duration|Object} duration - The length of each resulting interval, as a Duration object. * @return {Interval[]} */ splitBy(duration: DurationLike): Interval[]; /** * Return a Duration representing the time spanned by this interval. * @param {string|string[]} [unit=['milliseconds']] - the unit or units (such as 'hours' or 'days') to include in the duration. * @param {Object} opts - options that affect the creation of the Duration * @param {string} [opts.conversionAccuracy='casual'] - the conversion system to use * @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 } * @return {Duration} */ toDuration(unit?: DurationUnit | DurationUnit[], opts?: DurationOptions): Duration; /** * Returns a string representation of this Interval formatted according to the specified format * string. **You may not want this.** See {@link Interval#toLocaleString} for a more flexible * formatting tool. * @param {string} dateFormat - The format string. This string formats the start and end time. * See {@link DateTime#toFormat} for details. * @param {Object} opts - Options. * @param {string} [opts.separator = ' – '] - A separator to place between the start and end * representations. * @return {string} */ toFormat(dateFormat: string, { separator }?: { separator?: string; }): string; /** * Returns an ISO 8601-compliant string representation of this Interval. * @see https://en.wikipedia.org/wiki/ISO_8601#Time_intervals * @param {Object} options - The same options as {@link DateTime#toISO} * @return {string} */ toISO(options?: ToISOTimeOptions): 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 * @return {string} */ toISODate(): 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 * @param {Object} options - The same options as {@link DateTime#toISO} * @return {string} * */ toISOTime(options?: ToISOTimeOptions): string; /** * Returns a localized string representing this Interval. Accepts the same options as the * Intl.DateTimeFormat constructor and any presets defined by Luxon, such as * {@link DateTime.DATE_FULL} or {@link DateTime.TIME_SIMPLE}. The exact behavior of this method * is browser-specific, but in general it will return an appropriate representation of the * Interval in the assigned locale. Defaults to the system's locale if no locale has been * specified. * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat * @param {Object} [formatOpts=DateTime.DATE_SHORT] - Either a DateTime preset or * Intl.DateTimeFormat constructor options. * @param {Object} opts - Options to override the configuration of the start DateTime. * @example Interval.fromISO('2022-11-07T09:00Z/2022-11-08T09:00Z').toLocaleString(); //=> 11/7/2022 – 11/8/2022 * @example Interval.fromISO('2022-11-07T09:00Z/2022-11-08T09:00Z').toLocaleString(DateTime.DATE_FULL); //=> November 7 – 8, 2022 * @example Interval.fromISO('2022-11-07T09:00Z/2022-11-08T09:00Z').toLocaleString(DateTime.DATE_FULL, { locale: 'fr-FR' }); //=> 7–8 novembre 2022 * @example Interval.fromISO('2022-11-07T17:00Z/2022-11-07T19:00Z').toLocaleString(DateTime.TIME_SIMPLE); //=> 6:00 – 8:00 PM * @example Interval.fromISO('2022-11-07T17:00Z/2022-11-07T19:00Z').toLocaleString({ weekday: 'short', month: 'short', day: '2-digit', hour: '2-digit', minute: '2-digit' }); //=> Mon, Nov 07, 6:00 – 8:00 p * @return {string} */ toLocaleString(formatOpts?: Intl.DateTimeFormatOptions & LocaleOptions, opts?: {}): string; /** * Returns a string representation of this Interval appropriate for debugging. * @return {string} */ toString(): string; /** * 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. * @param {Interval} other * @return {Interval} */ union(other: Interval): Interval; } export default Interval;