Luxon Home Reference Source Repository
import {Duration} from 'luxon/src/duration.js'
public class | source

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:

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

fromISO(text: string, opts: Object): Duration

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

Create an DateTime from a Javascript object with keys like 'years' and 'hours'.

public static

invalid(reason: string): Duration

Create an invalid Duration.

Member Summary

Public Members
public get

days: number: *

Get the days.

public get

Get the hours.

public get

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

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

as(unit: string): number

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(unit: string): number

Get the value of unit.

public

Returns a string representation of this Duration appropriate for the REPL.

public

minus(duration: Duration | number | object): Duration

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

plus(duration: Duration | number | object): Duration

Make this Duration longer by the specified amount.

public

reconfigure(objectPattern: {"locale": *, "numberingSystem": *, "conversionAccuracy": *}): Duration

"Set" the locale and/or numberingSystem.

public

set(values: object): Duration

"Set" the values of specified units.

public

shiftTo(units: ...*): Duration

Convert this Duration into its representation in a different set of units.

public

toFormat(fmt: string, opts: object): string

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

toObject(opts: *): object

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.

Params:

NameTypeAttributeDescription
text string

text to parse

opts Object

options for parsing

obj.locale string
  • optional
  • default: 'en-US'

the locale to use

obj.numberingSystem string

the numbering system to use

obj.conversionAccuracy string
  • optional
  • default: 'casual'

the conversion system to use

Return:

Duration

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 }

See:

public static fromMillis(count: number, opts: Object): Duration source

Create Duration from a number of milliseconds.

Params:

NameTypeAttributeDescription
count number

of milliseconds

opts Object

options for parsing

obj.locale string
  • optional
  • default: 'en-US'

the locale to use

obj.numberingSystem string

the numbering system to use

obj.conversionAccuracy string
  • optional
  • default: 'casual'

the conversion system to use

Return:

Duration

public static fromObject(obj: Object): Duration source

Create an DateTime from a Javascript object with keys like 'years' and 'hours'.

Params:

NameTypeAttributeDescription
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
  • optional
  • default: 'en-US'

the locale to use

obj.numberingSystem string

the numbering system to use

obj.conversionAccuracy string
  • optional
  • default: 'casual'

the conversion system to use

Return:

Duration

public static invalid(reason: string): Duration source

Create an invalid Duration.

Params:

NameTypeAttributeDescription
reason string

reason this is invalid

Return:

Duration

Public Members

public get days: number: * source

Get the days.

Return:

number

public get hours: number: * source

Get the hours.

Return:

number

public get invalidReason: string: * source

Returns an explanation of why this Duration became invalid, or null if the Duration is valid

Return:

string

public get isValid: boolean: * source

Returns whether the Duration is invalid. Invalid durations are returned by diff operations on invalid DateTimes or Intervals.

Return:

boolean

public get locale: string: * source

Get the locale of a Duration, such 'en-GB'

Return:

string

public get milliseconds: number: * source

Get the milliseconds.

Return:

number

public get minutes: number: * source

Get the minutes.

Return:

number

public get months: number: * source

Get the months.

Return:

number

public get numberingSystem: string: * source

Get the numbering system of a Duration, such 'beng'. The numbering system is used when formatting the Duration

Return:

string

public get seconds: number: * source

Get the seconds.

Return:

number

public get weeks: number: * source

Get the weeks

Return:

number

public get years: number: * source

Get the years.

Return:

number

Public Methods

public as(unit: string): number source

Return the length of the duration in the specified unit.

Params:

NameTypeAttributeDescription
unit string

a unit such as 'minutes' or 'days'

Return:

number

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:

NameTypeAttributeDescription
other Duration

Return:

boolean

public get(unit: string): number source

Get the value of unit.

Params:

NameTypeAttributeDescription
unit string

a unit such as 'minute' or 'day'

Return:

number

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 inspect(): string source

Returns a string representation of this Duration appropriate for the REPL.

Return:

string

public minus(duration: Duration | number | object): Duration source

Make this Duration shorter by the specified amount. Return a newly-constructed Duration.

Params:

NameTypeAttributeDescription
duration Duration | number | object

The amount to subtract. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()

Return:

Duration

public negate(): Duration source

Return the negative of this Duration.

Return:

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.

Return:

Duration

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.

Params:

NameTypeAttributeDescription
duration Duration | number | object

The amount to add. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()

Return:

Duration

public reconfigure(objectPattern: {"locale": *, "numberingSystem": *, "conversionAccuracy": *}): Duration source

"Set" the locale and/or numberingSystem. Returns a newly-constructed Duration.

Params:

NameTypeAttributeDescription
objectPattern {"locale": *, "numberingSystem": *, "conversionAccuracy": *}
  • optional
  • default: {}

Return:

Duration

Example:

dur.reconfigure({ locale: 'en-GB' })

public set(values: object): Duration source

"Set" the values of specified units. Return a newly-constructed Duration.

Params:

NameTypeAttributeDescription
values object

a mapping of units to numbers

Return:

Duration

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:

NameTypeAttributeDescription
units ...*

Return:

Duration

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.

Params:

NameTypeAttributeDescription
fmt string

the format string

opts object

options

opts.round boolean

round numerical values

Return:

string

public toISO(): string source

Returns an ISO 8601-compliant string representation of this Duration.

Return:

string

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'

See:

public toJSON(): string source

Returns an ISO 8601 representation of this Duration appropriate for use in JSON.

Return:

string

public toObject(opts: *): object source

Returns a Javascript object with this Duration's values.

Params:

NameTypeAttributeDescription
opts *

options for generating the object

opts.includeConfig boolean
  • optional
  • default: false

include configuration attributes in the output

Return:

object

Example:

Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toObject() //=> { years: 1, days: 6, seconds: 2 }

public toString(): string source

Returns an ISO 8601 representation of this Duration appropriate for use in debugging.

Return:

string