1 | import { NumberingSystem } from './misc';
|
2 | import { ConversionAccuracy } from './datetime';
|
3 |
|
4 | export interface DurationOptions {
|
5 | locale?: string | undefined;
|
6 | numberingSystem?: NumberingSystem | undefined;
|
7 | conversionAccuracy?: ConversionAccuracy | undefined;
|
8 | }
|
9 |
|
10 | export interface DurationObjectUnits {
|
11 | years?: number | undefined;
|
12 | quarters?: number | undefined;
|
13 | months?: number | undefined;
|
14 | weeks?: number | undefined;
|
15 | days?: number | undefined;
|
16 | hours?: number | undefined;
|
17 | minutes?: number | undefined;
|
18 | seconds?: number | undefined;
|
19 | milliseconds?: number | undefined;
|
20 | }
|
21 |
|
22 | export interface DurationLikeObject extends DurationObjectUnits {
|
23 | year?: number | undefined;
|
24 | quarter?: number | undefined;
|
25 | month?: number | undefined;
|
26 | week?: number | undefined;
|
27 | day?: number | undefined;
|
28 | hour?: number | undefined;
|
29 | minute?: number | undefined;
|
30 | second?: number | undefined;
|
31 | millisecond?: number | undefined;
|
32 | }
|
33 |
|
34 | export type DurationUnit = keyof DurationLikeObject;
|
35 | export type DurationUnits = DurationUnit | DurationUnit[];
|
36 |
|
37 | export type ToISOFormat = 'basic' | 'extended';
|
38 |
|
39 | export interface ToISOTimeDurationOptions {
|
40 | /**
|
41 | * Include the `T` prefix
|
42 | * @default false
|
43 | */
|
44 | includePrefix?: boolean | undefined;
|
45 | /**
|
46 | * Exclude milliseconds from the format if they're 0
|
47 | * @default false
|
48 | */
|
49 | suppressMilliseconds?: boolean | undefined;
|
50 | /**
|
51 | * Exclude seconds from the format if they're 0
|
52 | * @default false
|
53 | */
|
54 | suppressSeconds?: boolean | undefined;
|
55 | /**
|
56 | * Choose between the basic and extended format
|
57 | * @default 'extended'
|
58 | */
|
59 | format?: ToISOFormat | undefined;
|
60 | }
|
61 |
|
62 | export interface ToHumanDurationOptions extends Intl.NumberFormatOptions {
|
63 | listStyle?: 'long' | 'short' | 'narrow' | undefined;
|
64 | }
|
65 |
|
66 | /**
|
67 | * Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()
|
68 | *
|
69 | * @deprecated Use DurationLike instead.
|
70 | */
|
71 | export type DurationInput = Duration | number | DurationLikeObject;
|
72 |
|
73 | /**
|
74 | * Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()
|
75 | */
|
76 | export type DurationLike = Duration | DurationLikeObject | number;
|
77 |
|
78 | /**
|
79 | * A Duration object represents a period of time, like "2 months" or "1 day, 1 hour".
|
80 | * 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.
|
81 | * 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.
|
82 | *
|
83 | * Here is a brief overview of commonly used methods and getters in Duration:
|
84 | *
|
85 | * * **Creation** To create a Duration, use {@link Duration.fromMillis}, {@link Duration.fromObject}, or {@link Duration.fromISO}.
|
86 | * * **Unit values** See the {@link Duration#years}, {@link Duration.months}, {@link Duration#weeks}, {@link Duration#days}, {@link Duration#hours}, {@link Duration#minutes},
|
87 | * * {@link Duration#seconds}, {@link Duration#milliseconds} accessors.
|
88 | * * **Configuration** See {@link Duration#locale} and {@link Duration#numberingSystem} accessors.
|
89 | * * **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},
|
90 | * * {@link Duration#shiftTo}, and {@link Duration#negate}.
|
91 | * * **Output** To convert the Duration into other representations, see {@link Duration#as}, {@link Duration#toISO}, {@link Duration#toFormat}, and {@link Duration#toJSON}
|
92 | *
|
93 | * There's are more methods documented below. In addition, for more information on subtler topics like internationalization and validity, see the external documentation.
|
94 | */
|
95 | export class Duration {
|
96 | /**
|
97 | * Create Duration from a number of milliseconds.
|
98 | *
|
99 | * @param count - of milliseconds
|
100 | * @param opts - options for parsing
|
101 | * @param opts.locale - the locale to use
|
102 | * @param opts.numberingSystem - the numbering system to use
|
103 | * @param opts.conversionAccuracy - the conversion system to use
|
104 | */
|
105 | static fromMillis(count: number, opts?: DurationOptions): Duration;
|
106 |
|
107 | /**
|
108 | * Create a Duration from a JavaScript object with keys like 'years' and 'hours'.
|
109 | * If this object is empty then a zero milliseconds duration is returned.
|
110 | *
|
111 | * @param obj - the object to create the DateTime from
|
112 | * @param obj.years
|
113 | * @param obj.quarters
|
114 | * @param obj.months
|
115 | * @param obj.weeks
|
116 | * @param obj.days
|
117 | * @param obj.hours
|
118 | * @param obj.minutes
|
119 | * @param obj.seconds
|
120 | * @param obj.milliseconds
|
121 | * @param opts - options for creating this Duration. Defaults to {}.
|
122 | * @param opts.locale - the locale to use. Defaults to 'en-US'.
|
123 | * @param opts.numberingSystem - the numbering system to use
|
124 | * @param opts.conversionAccuracy - the conversion system to use. Defaults to 'casual'.
|
125 | */
|
126 | static fromObject(obj: DurationLikeObject, opts?: DurationOptions): Duration;
|
127 |
|
128 | /**
|
129 | * Create a Duration from DurationLike.
|
130 | *
|
131 | * @param durationLike
|
132 | * Either a Luxon Duration, a number of milliseconds, or the object argument to Duration.fromObject()
|
133 | */
|
134 | static fromDurationLike(durationLike: DurationLike): Duration;
|
135 |
|
136 | /**
|
137 | * Create a Duration from an ISO 8601 duration string.
|
138 | * @see https://en.wikipedia.org/wiki/ISO_8601#Durations
|
139 | *
|
140 | * @param text - text to parse
|
141 | * @param opts - options for parsing
|
142 | * @param opts.locale - the locale to use. Defaults to 'en-US'.
|
143 | * @param opts.numberingSystem - the numbering system to use
|
144 | * @param opts.conversionAccuracy - the conversion system to use. Defaults to 'casual'.
|
145 | *
|
146 | * @example
|
147 | * Duration.fromISO('P3Y6M1W4DT12H30M5S').toObject() //=> { years: 3, months: 6, weeks: 1, days: 4, hours: 12, minutes: 30, seconds: 5 }
|
148 | * @example
|
149 | * Duration.fromISO('PT23H').toObject() //=> { hours: 23 }
|
150 | * @example
|
151 | * Duration.fromISO('P5Y3M').toObject() //=> { years: 5, months: 3 }
|
152 | */
|
153 | static fromISO(text: string, opts?: DurationOptions): Duration;
|
154 |
|
155 | /**
|
156 | * Create a Duration from an ISO 8601 time string.
|
157 | * @see https://en.wikipedia.org/wiki/ISO_8601#Times
|
158 | *
|
159 | * @param text - text to parse
|
160 | * @param opts - options for parsing
|
161 | * @param opts.locale - the locale to use. Defaults to 'en-US'.
|
162 | * @param opts.numberingSystem - the numbering system to use
|
163 | * @param opts.conversionAccuracy - the conversion system to use. Defaults to 'casual'.
|
164 | *
|
165 | * @example
|
166 | * Duration.fromISOTime('11:22:33.444').toObject() //=> { hours: 11, minutes: 22, seconds: 33, milliseconds: 444 }
|
167 | * @example
|
168 | * Duration.fromISOTime('11:00').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
|
169 | * @example
|
170 | * Duration.fromISOTime('T11:00').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
|
171 | * @example
|
172 | * Duration.fromISOTime('1100').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
|
173 | * @example
|
174 | * Duration.fromISOTime('T1100').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
|
175 | */
|
176 | static fromISOTime(text: string, opts?: DurationOptions): Duration;
|
177 |
|
178 | /**
|
179 | * Create an invalid Duration.
|
180 | *
|
181 | * @param reason - simple string of why this datetime is invalid. Should not contain parameters or anything else data-dependent
|
182 | * @param explanation - longer explanation, may include parameters and other useful debugging information. Defaults to null.
|
183 | */
|
184 | static invalid(reason: string, explanation?: string): Duration;
|
185 |
|
186 | /**
|
187 | * Check if an object is a Duration. Works across context boundaries
|
188 | *
|
189 | * @param o
|
190 | */
|
191 | static isDuration(o: unknown): o is Duration;
|
192 |
|
193 | private constructor(config: unknown);
|
194 |
|
195 | /**
|
196 | * Get the locale of a Duration, such 'en-GB'
|
197 | */
|
198 | get locale(): string;
|
199 |
|
200 | /**
|
201 | * Get the numbering system of a Duration, such 'beng'. The numbering system is used when formatting the Duration
|
202 | */
|
203 | get numberingSystem(): string;
|
204 |
|
205 | /**
|
206 | * Returns a string representation of this Duration formatted according to the specified format string. You may use these tokens:
|
207 | * * `S` for milliseconds
|
208 | * * `s` for seconds
|
209 | * * `m` for minutes
|
210 | * * `h` for hours
|
211 | * * `d` for days
|
212 | * * `M` for months
|
213 | * * `y` for years
|
214 | * Notes:
|
215 | * * Add padding by repeating the token, e.g. "yy" pads the years to two digits, "hhhh" pads the hours out to four digits
|
216 | * * The duration will be converted to the set of units in the format string using {@link Duration.shiftTo} and the Durations's conversion accuracy setting.
|
217 | *
|
218 | * string
fmt - the format |
219 | * opts - options
|
220 | * true.
opts.floor - floor numerical values. Defaults to |
221 | *
|
222 | *
|
223 | * Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("y d s") //=> "1 6 2"
|
224 | *
|
225 | * Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("yy dd sss") //=> "01 06 002"
|
226 | *
|
227 | * Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("M S") //=> "12 518402000"
|
228 | */
|
229 | toFormat(fmt: string, opts?: { floor?: boolean | undefined }): string;
|
230 |
|
231 | /**
|
232 | * Returns a string representation of a Duration with all units included
|
233 | * To modify its behavior use the `listStyle` and any Intl.NumberFormat option, though `unitDisplay` is especially relevant. See {@link Intl.NumberFormat}.
|
234 | * @param opts - On option object to override the formatting. Accepts the same keys as the options parameter of the native `Int.NumberFormat` constructor, as well as `listStyle`.
|
235 | * @example
|
236 | * ```js
|
237 | * var dur = Duration.fromObject({ days: 1, hours: 5, minutes: 6 })
|
238 | * dur.toHuman() //=> '1 day, 5 hours, 6 minutes'
|
239 | * dur.toHuman({ listStyle: "long" }) //=> '1 day, 5 hours, and 6 minutes'
|
240 | * dur.toHuman({ unitDisplay: "short" }) //=> '1 day, 5 hr, 6 min'
|
241 | * ```
|
242 | */
|
243 | toHuman(opts?: ToHumanDurationOptions): string;
|
244 |
|
245 | /**
|
246 | * Returns a JavaScript object with this Duration's values.
|
247 | *
|
248 | * @example
|
249 | * Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toObject() //=> { years: 1, days: 6, seconds: 2 }
|
250 | */
|
251 | toObject(): DurationObjectUnits;
|
252 |
|
253 | /**
|
254 | * Returns an ISO 8601-compliant string representation of this Duration.
|
255 | * @see https://en.wikipedia.org/wiki/ISO_8601#Durations
|
256 | *
|
257 | * @example
|
258 | * Duration.fromObject({ years: 3, seconds: 45 }).toISO() //=> 'P3YT45S'
|
259 | * @example
|
260 | * Duration.fromObject({ months: 4, seconds: 45 }).toISO() //=> 'P4MT45S'
|
261 | * @example
|
262 | * Duration.fromObject({ months: 5 }).toISO() //=> 'P5M'
|
263 | * @example
|
264 | * Duration.fromObject({ minutes: 5 }).toISO() //=> 'PT5M'
|
265 | * @example
|
266 | * Duration.fromObject({ milliseconds: 6 }).toISO() //=> 'PT0.006S'
|
267 | */
|
268 | toISO(): string;
|
269 |
|
270 | /**
|
271 | * Returns an ISO 8601-compliant string representation of this Duration, formatted as a time of day.
|
272 | * @see https://en.wikipedia.org/wiki/ISO_8601#Times
|
273 | *
|
274 | * @param opts - options
|
275 | * @param opts.suppressMilliseconds - exclude milliseconds from the format if they're 0. Defaults to false.
|
276 | * @param opts.suppressSeconds - exclude seconds from the format if they're 0. Defaults to false.
|
277 | * @param opts.includePrefix - include the `T` prefix. Defaults to false.
|
278 | * @param opts.format - choose between the basic and extended format. Defaults to 'extended'.
|
279 | *
|
280 | * @example
|
281 | * Duration.fromObject({ hours: 11 }).toISOTime() //=> '11:00:00.000'
|
282 | * @example
|
283 | * Duration.fromObject({ hours: 11 }).toISOTime({ suppressMilliseconds: true }) //=> '11:00:00'
|
284 | * @example
|
285 | * Duration.fromObject({ hours: 11 }).toISOTime({ suppressSeconds: true }) //=> '11:00'
|
286 | * @example
|
287 | * Duration.fromObject({ hours: 11 }).toISOTime({ includePrefix: true }) //=> 'T11:00:00.000'
|
288 | * @example
|
289 | * Duration.fromObject({ hours: 11 }).toISOTime({ format: 'basic' }) //=> '110000.000'
|
290 | */
|
291 | toISOTime(opts?: ToISOTimeDurationOptions): string;
|
292 |
|
293 | /**
|
294 | * Returns an ISO 8601 representation of this Duration appropriate for use in JSON.
|
295 | */
|
296 | toJSON(): string;
|
297 |
|
298 | /**
|
299 | * Returns an ISO 8601 representation of this Duration appropriate for use in debugging.
|
300 | */
|
301 | toString(): string;
|
302 |
|
303 | /**
|
304 | * Returns an milliseconds value of this Duration.
|
305 | */
|
306 | toMillis(): number;
|
307 |
|
308 | /**
|
309 | * Returns an milliseconds value of this Duration. Alias of {@link toMillis}
|
310 | */
|
311 | valueOf(): number;
|
312 |
|
313 | /**
|
314 | * Make this Duration longer by the specified amount. Return a newly-constructed Duration.
|
315 | *
|
316 | * @param duration - The amount to add. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()
|
317 | */
|
318 | plus(duration: DurationLike): Duration;
|
319 |
|
320 | /**
|
321 | * Make this Duration shorter by the specified amount. Return a newly-constructed Duration.
|
322 | *
|
323 | * @param duration - The amount to subtract. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()
|
324 | */
|
325 | minus(duration: DurationLike): Duration;
|
326 |
|
327 | /**
|
328 | * Scale this Duration by the specified amount. Return a newly-constructed Duration.
|
329 | *
|
330 | * @example
|
331 | * Duration.fromObject({ hours: 1, minutes: 30 }).mapUnit(x => x * 2) //=> { hours: 2, minutes: 60 }
|
332 | * @example
|
333 | * Duration.fromObject({ hours: 1, minutes: 30 }).mapUnit((x, u) => u === "hour" ? x * 2 : x) //=> { hours: 2, minutes: 30 }
|
334 | */
|
335 | mapUnits(fn: (x: number, u?: DurationUnit) => number): Duration;
|
336 |
|
337 | /**
|
338 | * Get the value of unit.
|
339 | *
|
340 | * @param unit - a unit such as 'minute' or 'day'
|
341 | *
|
342 | * @example
|
343 | * Duration.fromObject({years: 2, days: 3}).get('years') //=> 2
|
344 | * @example
|
345 | * Duration.fromObject({years: 2, days: 3}).get('months') //=> 0
|
346 | * @example
|
347 | * Duration.fromObject({years: 2, days: 3}).get('days') //=> 3
|
348 | */
|
349 | get(unit: DurationUnit): number;
|
350 |
|
351 | /**
|
352 | * "Set" the values of specified units. Return a newly-constructed Duration.
|
353 | *
|
354 | * @param values - a mapping of units to numbers
|
355 | *
|
356 | * @example
|
357 | * dur.set({ years: 2017 })
|
358 | * @example
|
359 | * dur.set({ hours: 8, minutes: 30 })
|
360 | */
|
361 | set(values: DurationLikeObject): Duration;
|
362 |
|
363 | /**
|
364 | * "Set" the locale and/or numberingSystem. Returns a newly-constructed Duration.
|
365 | *
|
366 | * @example
|
367 | * dur.reconfigure({ locale: 'en-GB' })
|
368 | */
|
369 | reconfigure(opts?: DurationOptions): Duration;
|
370 |
|
371 | /**
|
372 | * Return the length of the duration in the specified unit.
|
373 | *
|
374 | * @param unit - a unit such as 'minutes' or 'days'
|
375 | *
|
376 | * @example
|
377 | * Duration.fromObject({years: 1}).as('days') //=> 365
|
378 | * @example
|
379 | * Duration.fromObject({years: 1}).as('months') //=> 12
|
380 | * @example
|
381 | * Duration.fromObject({hours: 60}).as('days') //=> 2.5
|
382 | */
|
383 | as(unit: DurationUnit): number;
|
384 |
|
385 | /**
|
386 | * Reduce this Duration to its canonical representation in its current units.
|
387 | *
|
388 | * @example
|
389 | * Duration.fromObject({ years: 2, days: 5000 }).normalize().toObject() //=> { years: 15, days: 255 }
|
390 | * @example
|
391 | * Duration.fromObject({ hours: 12, minutes: -45 }).normalize().toObject() //=> { hours: 11, minutes: 15 }
|
392 | */
|
393 | normalize(): Duration;
|
394 |
|
395 | /**
|
396 | * Convert this Duration into its representation in a different set of units.
|
397 | *
|
398 | * @example
|
399 | * Duration.fromObject({ hours: 1, seconds: 30 }).shiftTo('minutes', 'milliseconds').toObject() //=> { minutes: 60, milliseconds: 30000 }
|
400 | */
|
401 | shiftTo(...units: DurationUnit[]): Duration;
|
402 |
|
403 | /**
|
404 | * Return the negative of this Duration.
|
405 | *
|
406 | * @example
|
407 | * Duration.fromObject({ hours: 1, seconds: 30 }).negate().toObject() //=> { hours: -1, seconds: -30 }
|
408 | */
|
409 | negate(): Duration;
|
410 |
|
411 | /**
|
412 | * Get the years.
|
413 | */
|
414 | get years(): number;
|
415 |
|
416 | /**
|
417 | * Get the quarters.
|
418 | */
|
419 | get quarters(): number;
|
420 |
|
421 | /**
|
422 | * Get the months.
|
423 | */
|
424 | get months(): number;
|
425 |
|
426 | /**
|
427 | * Get the weeks
|
428 | */
|
429 | get weeks(): number;
|
430 |
|
431 | /**
|
432 | * Get the days.
|
433 | */
|
434 | get days(): number;
|
435 |
|
436 | /**
|
437 | * Get the hours.
|
438 | */
|
439 | get hours(): number;
|
440 |
|
441 | /**
|
442 | * Get the minutes.
|
443 | */
|
444 | get minutes(): number;
|
445 |
|
446 | /**
|
447 | * Get the seconds.
|
448 | */
|
449 | get seconds(): number;
|
450 |
|
451 | /**
|
452 | * Get the milliseconds.
|
453 | */
|
454 | get milliseconds(): number;
|
455 |
|
456 | /**
|
457 | * Returns whether the Duration is invalid. Invalid durations are returned by diff operations
|
458 | * on invalid DateTimes or Intervals.
|
459 | */
|
460 | get isValid(): boolean;
|
461 |
|
462 | /**
|
463 | * Returns an error code if this Duration became invalid, or null if the Duration is valid
|
464 | */
|
465 | get invalidReason(): string;
|
466 |
|
467 | /**
|
468 | * Returns an explanation of why this Duration became invalid, or null if the Duration is valid
|
469 | */
|
470 | get invalidExplanation(): string;
|
471 |
|
472 | /**
|
473 | * Equality check
|
474 | * Two Durations are equal iff they have the same units and the same values for each unit.
|
475 | *
|
476 | * @param other
|
477 | */
|
478 | equals(other: Duration): boolean;
|
479 | }
|