Duration
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 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 fromMillis, fromObject, or fromISO.
- Unit values See the years, months, weeks, days, hours, minutes, seconds, milliseconds accessors.
- Configuration See locale and numberingSystem accessors.
- Transformation To create new Durations out of old ones use plus, minus, normalize, set, reconfigure, shiftTo, and negate.
- Output To convert the Duration into other representations, see as, toISO, toFormat, and toJSON
There's are more methods documented below. In addition, for more information on subtler topics like internationalization and validity, see the external documentation.
Static Method Summary
Static Public Methods | ||
public static |
Create a DateTime from an ISO 8601 duration string. |
|
public static |
fromMillis(count: number, opts: Object): Duration Create Duration from a number of milliseconds. |
|
public static |
fromObject(obj: Object): Duration Create an DateTime from a Javascript object with keys like 'years' and 'hours'. |
|
public static |
Create an invalid Duration. |
Member Summary
Public Members | ||
public get |
days: *: * Get the days. |
|
public get |
Get the hours. |
|
public get |
invalidReason: string: * Returns an explanation of why this Duration became invalid, or null if the Duration is valid |
|
public get |
Returns whether the Duration is invalid. |
|
public get |
Get the locale of a Duration, such 'en-GB' |
|
public get |
milliseconds: number: * Get the milliseconds. |
|
public get |
Get the minutes. |
|
public get |
Get the months. |
|
public get |
Get the numbering system of a Duration, such 'beng'. |
|
public get |
Get the seconds. |
|
public get |
Get the weeks |
|
public get |
Get the years. |
Method Summary
Public Methods | ||
public |
Return the length of the duration in the specified unit. |
|
public |
Equality check Two Durations are equal iff they have the same units and the same values for each unit. |
|
public |
Get the value of unit. |
|
public |
Make this Duration shorter by the specified amount. |
|
public |
Return the negative of this Duration. |
|
public |
Reduce this Duration to its canonical representation in its current units. |
|
public |
Make this Duration longer by the specified amount. |
|
public |
reconfigure(objectPattern: {"locale": *, "numberingSystem": *, "conversionAccuracy": *}): Duration "Set" the locale and/or numberingSystem. |
|
public |
"Set" the values of specified units. |
|
public |
Convert this Duration into its representation in a different set of units. |
|
public |
Returns a string representation of this Duration formatted according to the specified format string. |
|
public |
Returns an ISO 8601-compliant string representation of this Duration. |
|
public |
Returns an ISO 8601 representation of this Duration appropriate for use in JSON. |
|
public |
Returns a Javascript object with this Duration's values. |
|
public |
Returns an ISO 8601 representation of this Duration appropriate for use in debugging. |
Static Public Methods
public static fromISO(text: string, opts: Object): Duration source
Create a DateTime from an ISO 8601 duration string.
Example:
Duration.fromISO('P3Y6M4DT12H30M5S').toObject() //=> { years: 3, months: 6, day: 4, hours: 12, minutes: 30, seconds: 5 }
Duration.fromISO('PT23H').toObject() //=> { hours: 23 }
Duration.fromISO('P5Y3M').toObject() //=> { years: 5, months: 3 }
public static fromMillis(count: number, opts: Object): Duration source
Create Duration from a number of milliseconds.
Params:
Name | Type | Attribute | Description |
count | number | of milliseconds |
|
opts | Object | options for parsing |
|
obj.locale | string |
|
the locale to use |
obj.numberingSystem | string | the numbering system to use |
|
obj.conversionAccuracy | string |
|
the conversion system to use |
public static fromObject(obj: Object): Duration source
Create an DateTime from a Javascript object with keys like 'years' and 'hours'.
Params:
Name | Type | Attribute | Description |
obj | Object | the object to create the DateTime from |
|
obj.years | number | ||
obj.months | number | ||
obj.weeks | number | ||
obj.days | number | ||
obj.hours | number | ||
obj.minutes | number | ||
obj.seconds | number | ||
obj.milliseconds | number | ||
obj.locale | string |
|
the locale to use |
obj.numberingSystem | string | the numbering system to use |
|
obj.conversionAccuracy | string |
|
the conversion system to use |
Public Members
public get invalidReason: string: * source
Returns an explanation of why this Duration became invalid, or null if the Duration is valid
public get isValid: boolean: * source
Returns whether the Duration is invalid. Invalid durations are returned by diff operations on invalid DateTimes or Intervals.
Public Methods
public as(unit: string): number source
Return the length of the duration in the specified unit.
Params:
Name | Type | Attribute | Description |
unit | string | a unit such as 'minutes' or 'days' |
Example:
Duration.fromObject({years: 1}).as('days') //=> 365
Duration.fromObject({years: 1}).as('months') //=> 12
Duration.fromObject({hours: 60}).as('days') //=> 2.5
public equals(other: Duration): boolean source
Equality check Two Durations are equal iff they have the same units and the same values for each unit.
Params:
Name | Type | Attribute | Description |
other | Duration |
public get(unit: string): number source
Get the value of unit.
Params:
Name | Type | Attribute | Description |
unit | string | a unit such as 'minute' or 'day' |
Example:
Duration.fromObject({years: 2, days: 3}).years //=> 2
Duration.fromObject({years: 2, days: 3}).months //=> 0
Duration.fromObject({years: 2, days: 3}).days //=> 3
public minus(duration: Duration | number | object): Duration source
Make this Duration shorter by the specified amount. Return a newly-constructed Duration.
public negate(): Duration source
Return the negative of this Duration.
Example:
Duration.fromObject({ hours: 1, seconds: 30 }).negate().toObject() //=> { hours: -1, seconds: -30 }
public normalize(): Duration source
Reduce this Duration to its canonical representation in its current units.
Example:
Duration.fromObject({ years: 2, days: 5000 }).normalize().toObject() //=> { years: 15, days: 255 }
Duration.fromObject({ hours: 12, minutes: -45 }).normalize().toObject() //=> { hours: 11, minutes: 15 }
public plus(duration: Duration | number | object): Duration source
Make this Duration longer by the specified amount. Return a newly-constructed Duration.
public reconfigure(objectPattern: {"locale": *, "numberingSystem": *, "conversionAccuracy": *}): Duration source
"Set" the locale and/or numberingSystem. Returns a newly-constructed Duration.
Params:
Name | Type | Attribute | Description |
objectPattern | {"locale": *, "numberingSystem": *, "conversionAccuracy": *} |
|
Example:
dur.reconfigure({ locale: 'en-GB' })
public set(values: object): Duration source
"Set" the values of specified units. Return a newly-constructed Duration.
Params:
Name | Type | Attribute | Description |
values | object | a mapping of units to numbers |
Example:
dur.set({ years: 2017 })
dur.set({ hours: 8, minutes: 30 })
public shiftTo(units: ...*): Duration source
Convert this Duration into its representation in a different set of units.
Params:
Name | Type | Attribute | Description |
units | ...* |
Example:
Duration.fromObject({ hours: 1, seconds: 30 }).shiftTo('minutes', 'milliseconds').toObject() //=> { minutes: 60, milliseconds: 30000 }
public toFormat(fmt: string, opts: object): string source
Returns a string representation of this Duration formatted according to the specified format string.
public toISO(): string source
Returns an ISO 8601-compliant string representation of this Duration.
Example:
Duration.fromObject({ years: 3, seconds: 45 }).toISO() //=> 'P3YT45S'
Duration.fromObject({ months: 4, seconds: 45 }).toISO() //=> 'P4MT45S'
Duration.fromObject({ months: 5 }).toISO() //=> 'P5M'
Duration.fromObject({ minutes: 5 }).toISO() //=> 'PT5M'
public toJSON(): string source
Returns an ISO 8601 representation of this Duration appropriate for use in JSON.
public toObject(opts: *): object source
Returns a Javascript object with this Duration's values.
Params:
Name | Type | Attribute | Description |
opts | * | options for generating the object |
|
opts.includeConfig | boolean |
|
include configuration attributes in the output |
Example:
Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toObject() //=> { years: 1, days: 6, seconds: 2 }