import { DurationObject, DurationOptions, DurationToFormatOptions, DurationUnit, UnparsedDurationObject, NormalizedDurationUnit, NormalizedDurationObject, DurationToHumanOptions, NormalizedHumanDurationUnit, ConversionMatrix } from "./types/duration.js"; import { ConversionAccuracy } from "./types/common.js"; import { Invalid } from "./types/invalid.js"; import { NumberingSystem } from "./types/locale.js"; import { ToISOTimeOptions } from "./types/datetime.js"; export declare const lowOrderMatrix: { weeks: { days: number; hours: number; minutes: number; seconds: number; milliseconds: number; }; days: { hours: number; minutes: number; seconds: number; milliseconds: number; }; hours: { minutes: number; seconds: number; milliseconds: number; }; minutes: { seconds: number; milliseconds: number; }; seconds: { milliseconds: number; }; }; export declare const casualMatrix: ConversionMatrix; /** * A Duration object represents a period of time, like "2 months" or "1 day, 1 hour". Conceptually, it's just a map of units to their quantities, accompanied by some additional configuration and methods for creating, parsing, interrogating, transforming, and formatting them. They can be used on their own or in conjunction with other Luxon types; for example, you can use {@link DateTime#plus} to add a Duration object to a DateTime, producing another DateTime. * * Here is a brief overview of commonly used methods and getters in Duration: * * * **Creation** To create a Duration, use {@link Duration.fromMillis}, {@link Duration.fromObject}, or {@link Duration.fromISO}. * * **Unit values** See the {@link Duration#years}, {@link Duration#months}, {@link Duration#weeks}, {@link Duration#days}, {@link Duration#hours}, {@link Duration#minutes}, {@link Duration#seconds}, {@link Duration#milliseconds} accessors. * * **Configuration** See {@link Duration#locale} and {@link Duration#numberingSystem} accessors. * * **Transformation** To create new Durations out of old ones use {@link Duration#plus}, {@link Duration#minus}, {@link Duration#normalize}, {@link Duration#set}, {@link Duration#reconfigure}, {@link Duration#shiftTo}, and {@link Duration#negate}. * * **Output** To convert the Duration into other representations, see {@link Duration#as}, {@link Duration#toISO}, {@link Duration#toFormat}, and {@link Duration#toJSON} * * There are more methods documented below. In addition, for more information on subtler topics like internationalization and validity, see the external documentation. */ export declare class Duration implements NormalizedDurationObject { private static get _INVALID(); /** * Returns the conversion system to use * @type {ConversionAccuracy} */ get conversionAccuracy(): ConversionAccuracy; /** * Get the days. * @type {number} */ get days(): number; /** * Get the hours. * @type {number} */ get hours(): number; /** * Returns an explanation of why this Duration became invalid, or null if the Duration is valid * @type {string} */ get invalidExplanation(): string | null; /** * Returns an error code if this Duration became invalid, or null if the Duration is valid * @return {string} */ get invalidReason(): string | null; /** * Returns whether the Duration is invalid. Invalid durations are returned by diff operations * on invalid DateTimes or Intervals. * @return {boolean} */ get isValid(): boolean; /** * Get the locale of a Duration, such 'en-GB' * @type {string} */ get locale(): string | void; /** * Get the conversion matrix of a Duration * @type {ConversionMatrix} */ get matrix(): ConversionMatrix; /** * Get the milliseconds. * @return {number} */ get milliseconds(): number; /** * Get the minutes. * @type {number} */ get minutes(): number; /** * Get the months. * @type {number} */ get months(): number; /** * Get the numbering system of a Duration, such 'beng'. The numbering system is used when formatting the Duration * * @type {NumberingSystem} */ get numberingSystem(): NumberingSystem | void; /** * Get the quarters. * @type {number} */ get quarters(): number; /** * Get the seconds. * @return {number} */ get seconds(): number; /** * Get the weeks * @type {number} */ get weeks(): number; /** * Get the years. * @type {number} */ get years(): number; private readonly _conversionAccuracy; private readonly _invalid; private readonly _isLuxonDuration; private _loc; private readonly _matrix; private readonly _values; /** * @private */ private constructor(); /** * Create a Duration from DurationLike. * * @param {Object | number | Duration} durationLike * One of: * - object with keys like 'years' and 'hours'. * - number representing milliseconds * - Duration instance * @return {Duration} */ static fromDurationLike(durationLike: number | DurationLike): Duration; /** * Create a Duration from an ISO 8601 duration string. * @param {string} text - text to parse * @param {Object} opts - options for parsing * @param {string} [opts.locale='en-US'] - the locale to use * @param {string} opts.numberingSystem - the numbering system to use * @param {string} [opts.conversionAccuracy='casual'] - the preset conversion system to use * @param {string} [opts.matrix=Object] - the preset conversion system to use * @see https://en.wikipedia.org/wiki/ISO_8601#Durations * @example Duration.fromISO('P3Y6M1W4DT12H30M5S').toObject() //=> { years: 3, months: 6, weeks: 1, days: 4, hours: 12, minutes: 30, seconds: 5 } * @example Duration.fromISO('PT23H').toObject() //=> { hours: 23 } * @example Duration.fromISO('P5Y3M').toObject() //=> { years: 5, months: 3 } * @return {Duration} */ static fromISO(text: string, opts?: DurationOptions): Duration; /** * Create a Duration from an ISO 8601 time string. * @param {string} text - text to parse * @param {Object} opts - options for parsing * @param {string} [opts.locale='en-US'] - the locale to use * @param {string} opts.numberingSystem - the numbering system to use * @param {string} [opts.conversionAccuracy='casual'] - the preset conversion system to use * @param {string} [opts.matrix=Object] - the conversion system to use * @see https://en.wikipedia.org/wiki/ISO_8601#Times * @example Duration.fromISOTime('11:22:33.444').toObject() //=> { hours: 11, minutes: 22, seconds: 33, milliseconds: 444 } * @example Duration.fromISOTime('11:00').toObject() //=> { hours: 11, minutes: 0, seconds: 0 } * @example Duration.fromISOTime('T11:00').toObject() //=> { hours: 11, minutes: 0, seconds: 0 } * @example Duration.fromISOTime('1100').toObject() //=> { hours: 11, minutes: 0, seconds: 0 } * @example Duration.fromISOTime('T1100').toObject() //=> { hours: 11, minutes: 0, seconds: 0 } * @return {Duration} */ static fromISOTime(text: string, opts?: DurationOptions): Duration; /** * Create Duration from a number of milliseconds. * @param {number} milliseconds of milliseconds * @param {Object} opts - options for parsing * @param {string} [opts.locale='en-US'] - the locale to use * @param {string} opts.numberingSystem - the numbering system to use * @param {string} [opts.conversionAccuracy='casual'] - the conversion system to use * @return {Duration} */ static fromMillis(milliseconds: number, opts?: DurationOptions): Duration; /** * Create a Duration from a JavaScript object with keys like 'years' and 'hours'. * If this object is empty then a zero milliseconds duration is returned. * @param {Object} obj - the object to create the DateTime from * @param {number} obj.years * @param {number} obj.quarters * @param {number} obj.months * @param {number} obj.weeks * @param {number} obj.days * @param {number} obj.hours * @param {number} obj.minutes * @param {number} obj.seconds * @param {number} obj.milliseconds * @param {Object} [opts=[]] - options for creating this Duration * @param {string} [opts.locale='en-US'] - the locale to use * @param {string} opts.numberingSystem - the numbering system to use * @param {string} [opts.conversionAccuracy='casual'] - the preset conversion system to use * @param {string} [opts.matrix=Object] - the custom conversion system to use * @return {Duration} */ static fromObject(obj: UnparsedDurationObject | null, opts?: DurationOptions): Duration; /** * Create an invalid Duration. * @param {string} reason - simple string of why this datetime 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 * @return {Duration} */ static invalid(reason: Invalid | string, explanation?: string): Duration; /** * Check if an object is a Duration. Works across context boundaries * @param {Object} o * @return {boolean} */ static isDuration(o: unknown): o is Duration; /** * @private */ static normalizeUnit(unit: string): keyof NormalizedDurationObject; /** * Return the length of the duration in the specified unit. * @param {string} unit - a unit such as 'minutes' or 'days' * @example Duration.fromObject({years: 1}).as('days') //=> 365 * @example Duration.fromObject({years: 1}).as('months') //=> 12 * @example Duration.fromObject({hours: 60}).as('days') //=> 2.5 * @return {number} */ as(unit: DurationUnit): number; /** * Equality check * Two Durations are equal iff they have the same units and the same values for each unit. * @param {Duration} other * @return {boolean} */ equals(other: Duration): boolean; /** * Get the value of unit. * @param {string} unit - a unit such as 'minute' or 'day' * @example Duration.fromObject({years: 2, days: 3}).get('years') //=> 2 * @example Duration.fromObject({years: 2, days: 3}).get('months') //=> 0 * @example Duration.fromObject({years: 2, days: 3}).get('days') //=> 3 * @return {number} */ get(unit: DurationUnit): number; /** * Returns the max unit in the duration, forcing the shifting to the max possible. * Forcing solves having bigger units at 0, when creating with a smaller unit. * Es. Duration.fromMillis(4945676146971854) * By default it uses all the units, but a flag can be passed to use only Human duration units (all except quarters and weeks) * @param onlyHuman - Choose if using ORDERED_UNITS (default) or HUMAN_ORDERED_UNITS * @example * ```js * var dur = Duration.fromObject({ minutes: 61 }) * dur.getMaxUnit() //=> 'hours' * ``` */ getMaxUnit(onlyHuman: false): NormalizedDurationUnit; getMaxUnit(onlyHuman: true): NormalizedHumanDurationUnit; /** * Scale this Duration by the specified amount. Return a newly-constructed Duration. * @param {function} fn - The function to apply to each unit. Arity is 1 or 2: the value of the unit and, optionally, the unit name. Must return a number. * @example Duration.fromObject({ hours: 1, minutes: 30 }).mapUnits(x => x * 2) //=> { hours: 2, minutes: 60 } * @example Duration.fromObject({ hours: 1, minutes: 30 }).mapUnits((x, u) => u === "hours" ? x * 2 : x) //=> { hours: 2, minutes: 30 } * @return {Duration} */ mapUnits(fn: (x: number, unit: DurationUnit) => number): Duration; /** * Make this Duration shorter by the specified amount. Return a newly-constructed Duration. * @param {Duration|Object} duration - The amount to subtract. Either a Luxon Duration or the object argument to Duration.fromObject() * @return {Duration} */ minus(duration: DurationLike): Duration; /** * Return the negative of this Duration. * @example Duration.fromObject({ hours: 1, seconds: 30 }).negate().toObject() //=> { hours: -1, seconds: -30 } * @return {Duration} */ negate(): Duration; /** * Reduce this Duration to its canonical representation in its current units. * Assuming the overall value of the Duration is positive, this means: * - excessive values for lower-order units are converted to higher order units (if possible, see first and second example) * - negative lower-order units are converted to higher order units (there must be such a higher order unit, otherwise * the overall value would be negative, see third example) * * If the overall value is negative, the result of this method is equivalent to `this.negate().normalize().negate()`. * @example Duration.fromObject({ years: 2, days: 5000 }).normalize().toObject() //=> { years: 15, days: 255 } * @example Duration.fromObject({ days: 5000 }).normalize().toObject() //=> { days: 5000 } * @example Duration.fromObject({ hours: 12, minutes: -45 }).normalize().toObject() //=> { hours: 11, minutes: 15 } * @return {Duration} */ normalize(): Duration; /** * Make this Duration longer by the specified amount. Return a newly-constructed Duration. * @param {Duration|Object} duration - The amount to add. Either a Luxon Duration or the object argument to Duration.fromObject() * @return {Duration} */ plus(duration: DurationLike): Duration; /** * "Set" the locale and/or numberingSystem and/or conversionAccuracy. Returns a newly-constructed Duration. * @example dur.reconfigure({ locale: 'en-GB' }) * @return {Duration} */ reconfigure({ locale, numberingSystem, conversionAccuracy, matrix }?: DurationOptions): Duration; /** * Removes all units with values equal to 0 from this Duration. * @example Duration.fromObject({ years: 2, days: 0, hours: 0, minutes: 0 }).removeZeros().toObject() //=> { years: 2 } * @return {Duration} */ removeZeroes(): Duration; /** * Rescale units to its largest representation * @example Duration.fromObject({ milliseconds: 90000 }).rescale().toObject() //=> { minutes: 1, seconds: 30 } * @return {Duration} */ rescale(): Duration; /** * "Set" the values of specified units. Non-specified units stay unchanged. Return a newly-constructed Duration. * @param {Object} values - a mapping of units to numbers * @example dur.set({ years: 2017 }) * @example dur.set({ hours: 8, minutes: 30 }) * @return {Duration} */ set(values: DurationObject): Duration; /** * Convert this Duration into its representation in a different set of units. * @example Duration.fromObject({ hours: 1, seconds: 30 }).shiftTo('minutes', 'milliseconds').toObject() //=> { minutes: 60, milliseconds: 30000 } * @return {Duration} */ shiftTo(...units: DurationUnit[]): Duration; /** * Shift this Duration to all available units. * Same as shiftTo("years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds") * @return {Duration} */ shiftToAll(): Duration; /** * Returns a string representation of this Duration formatted according to the specified format string. You may use these tokens: * * `S` for milliseconds * * `s` for seconds * * `m` for minutes * * `h` for hours * * `d` for days * * `w` for weeks * * `M` for months * * `y` for years * Notes: * Add padding by repeating the token, e.g. "yy" pads the years to two digits, "hhhh" pads the hours out to four digits * Tokens can be escaped by wrapping with single quotes. * The duration will be converted to the set of units in the format string using {@link Duration#shiftTo} and the Durations' conversion accuracy setting. * @param {string} fmt - the format string * @param {Object} opts - options * @param {boolean} [opts.floor=true] - floor numerical values * @param {"negative"|"all"|"negativeLargestOnly"} [opts.signMode=negative] - How to handle signs * @example Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("y d s") //=> "1 6 2" * @example Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("yy dd sss") //=> "01 06 002" * @example Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("M S") //=> "12 518402000" * @example Duration.fromObject({ days: 6, seconds: 2 }).toFormat("d s", { signMode: "all" }) //=> "+6 +2" * @example Duration.fromObject({ days: -6, seconds: -2 }).toFormat("d s", { signMode: "all" }) //=> "-6 -2" * @example Duration.fromObject({ days: -6, seconds: -2 }).toFormat("d s", { signMode: "negativeLargestOnly" }) //=> "-6 2" * @return {string} */ toFormat(fmt: string, opts?: DurationToFormatOptions): string; /** * Returns a string representation of a Duration with all units included. * To modify its behavior, use `listStyle` and any Intl.NumberFormat option, though `unitDisplay` is especially relevant. * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options * @param {Object} opts - Formatting options. Accepts the same keys as the options parameter of the native `Intl.NumberFormat` constructor, as well as `listStyle`. * @param {string} [opts.listStyle='narrow'] - How to format the merged list. Corresponds to the `style` property of the options parameter of the native `Intl.ListFormat` constructor. * @param {boolean} [opts.showZeroes=true] - Show all units previously used by the duration even if they are zero * @example * ```js * var dur = Duration.fromObject({ months: 1, weeks: 0, hours: 5, minutes: 6 }) * dur.toHuman() //=> '1 month, 0 weeks, 5 hours, 6 minutes' * dur.toHuman({ listStyle: "long" }) //=> '1 month, 0 weeks, 5 hours, and 6 minutes' * dur.toHuman({ unitDisplay: "short" }) //=> '1 mth, 0 wks, 5 hr, 6 min' * dur.toHuman({ showZeros: false }) //=> '1 month, 5 hours, 6 minutes' * ``` */ toHuman(opts?: Intl.NumberFormatOptions & DurationToHumanOptions): string; /** * Returns an ISO 8601-compliant string representation of this Duration. * @see https://en.wikipedia.org/wiki/ISO_8601#Durations * @example Duration.fromObject({ years: 3, seconds: 45 }).toISO() //=> 'P3YT45S' * @example Duration.fromObject({ months: 4, seconds: 45 }).toISO() //=> 'P4MT45S' * @example Duration.fromObject({ months: 5 }).toISO() //=> 'P5M' * @example Duration.fromObject({ minutes: 5 }).toISO() //=> 'PT5M' * @example Duration.fromObject({ milliseconds: 6 }).toISO() //=> 'PT0.006S' * @return {string} */ toISO(): string | null; /** * Returns an ISO 8601-compliant string representation of this Duration, formatted as a time of day. * Note that this will return null if the duration is invalid, negative, or equal to or greater than 24 hours. * @see https://en.wikipedia.org/wiki/ISO_8601#Times * @param {Object} opts - options * @param {boolean} [opts.suppressMilliseconds=false] - exclude milliseconds from the format if they're 0 * @param {boolean} [opts.suppressSeconds=false] - exclude seconds from the format if they're 0 * @param {boolean} [opts.includePrefix=false] - include the `T` prefix * @param {string} [opts.format='extended'] - choose between the basic and extended format * @example Duration.fromObject({ hours: 11 }).toISOTime() //=> '11:00:00.000' * @example Duration.fromObject({ hours: 11 }).toISOTime({ suppressMilliseconds: true }) //=> '11:00:00' * @example Duration.fromObject({ hours: 11 }).toISOTime({ suppressSeconds: true }) //=> '11:00' * @example Duration.fromObject({ hours: 11 }).toISOTime({ includePrefix: true }) //=> 'T11:00:00.000' * @example Duration.fromObject({ hours: 11 }).toISOTime({ format: 'basic' }) //=> '110000.000' * @return {string} */ toISOTime(opts?: ToISOTimeOptions): string | null; /** * Returns an ISO 8601 representation of this Duration appropriate for use in JSON. * @return {string} */ toJSON(): string | null; /** * Returns the value of this Duration in milliseconds. * @return {number} */ toMillis(): number; /** * Returns a JavaScript object with this Duration's values. * @example Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toObject() //=> { years: 1, days: 6, seconds: 2 } * @return {Object} */ toObject(): DurationObject & Partial; /** * Returns an ISO 8601 representation of this Duration appropriate for use in debugging. * @return {string} */ toString(): string | null; /** * Returns a milliseconds value of this Duration. Alias of {@link toMillis} * @return {number} */ valueOf(): number; /** * @private */ private _clone; } export type DurationLike = Duration | UnparsedDurationObject; export default Duration;