Options
All
  • Public
  • Public/Protected
  • All
Menu

Class 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 {@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 Duration.fromMillis, Duration.fromObject, or Duration.fromISO.
  • Unit values See the {@link Duration#years}, 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's are more methods documented below. In addition, for more information on subtler topics like internationalization and validity, see the external documentation.

Hierarchy

  • Duration

Index

Constructors

Accessors

Methods

Constructors

constructor

Accessors

days

  • get days(): number

  • Get the days.

    Returns number

hours

  • get hours(): number

  • Get the hours.

    Returns number

invalidExplanation

  • get invalidExplanation(): string

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

    Returns string

invalidReason

  • get invalidReason(): string

  • Returns an error code if this Duration became invalid, or null if the Duration is valid

    Returns string

isValid

  • get isValid(): boolean

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

    Returns boolean

locale

  • get locale(): string

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

    Returns string

milliseconds

  • get milliseconds(): number

  • Get the milliseconds.

    Returns number

minutes

  • get minutes(): number

  • Get the minutes.

    Returns number

months

  • get months(): number

  • Get the months.

    Returns number

numberingSystem

  • get numberingSystem(): string

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

    Returns string

quarters

  • get quarters(): number

  • Get the quarters.

    Returns number

seconds

  • get seconds(): number

  • Get the seconds.

    Returns number

weeks

  • get weeks(): number

  • Get the weeks

    Returns number

years

  • get years(): number

  • Get the years.

    Returns number

Methods

as

  • Return the length of the duration in the specified unit.

    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

    Parameters

    Returns number

equals

  • Equality check Two Durations are equal iff they have the same units and the same values for each unit.

    Parameters

    Returns boolean

get

  • Get the value of unit.

    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

    Parameters

    Returns number

mapUnits

  • Scale this Duration by the specified amount. Return a newly-constructed Duration.

    example

    Duration.fromObject({ hours: 1, minutes: 30 }).mapUnit(x => x * 2) //=> { hours: 2, minutes: 60 }

    example

    Duration.fromObject({ hours: 1, minutes: 30 }).mapUnit((x, u) => u === "hour" ? x * 2 : x) //=> { hours: 2, minutes: 30 }

    Parameters

    Returns Duration

minus

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

    Parameters

    • duration: DurationLike

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

    Returns Duration

negate

  • Return the negative of this Duration.

    example

    Duration.fromObject({ hours: 1, seconds: 30 }).negate().toObject() //=> { hours: -1, seconds: -30 }

    Returns Duration

normalize

  • Reduce this Duration to its canonical representation in its current units.

    example

    Duration.fromObject({ years: 2, days: 5000 }).normalize().toObject() //=> { years: 15, days: 255 }

    example

    Duration.fromObject({ hours: 12, minutes: -45 }).normalize().toObject() //=> { hours: 11, minutes: 15 }

    Returns Duration

plus

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

    Parameters

    • duration: DurationLike

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

    Returns Duration

reconfigure

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

    example

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

    Parameters

    Returns Duration

set

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

    example

    dur.set({ years: 2017 })

    example

    dur.set({ hours: 8, minutes: 30 })

    Parameters

    Returns Duration

shiftTo

  • 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 }

    Parameters

    Returns Duration

toFormat

  • toFormat(fmt: string, opts?: { floor?: boolean }): string

  • 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
    • 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
    • The duration will be converted to the set of units in the format string using Duration.shiftTo and the Durations's conversion accuracy setting.
    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"

    Parameters

    • fmt: string

      the format string

    • Optional opts: { floor?: boolean }

      options

      • Optional floor?: boolean

        floor numerical values. Defaults to true.

    Returns string

toISO

  • toISO(): 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'

    Returns string

toISOTime

  • Returns an ISO 8601-compliant string representation of this Duration, formatted as a time of day.

    see

    https://en.wikipedia.org/wiki/ISO_8601#Times

    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'

    Parameters

    Returns string

toJSON

  • toJSON(): string

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

    Returns string

toMillis

  • toMillis(): number

  • Returns an milliseconds value of this Duration.

    Returns number

toObject

  • 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 }

    Returns DurationObjectUnits

toString

  • toString(): string

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

    Returns string

valueOf

  • valueOf(): number

  • Returns an milliseconds value of this Duration. Alias of toMillis

    Returns number

Static fromISO

  • Create a Duration from an ISO 8601 duration string.

    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 }

    Parameters

    • text: string

      text to parse

    • Optional opts: DurationOptions

      options for parsing

    Returns Duration

Static fromISOTime

  • Create a Duration from an ISO 8601 time string.

    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 }

    Parameters

    Returns Duration

Static fromMillis

  • Create Duration from a number of milliseconds.

    Parameters

    • count: number

      of milliseconds

    • Optional opts: DurationOptions

      options for parsing

    Returns Duration

Static fromObject

  • 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.

    Parameters

    Returns Duration

Static invalid

  • invalid(reason: string, explanation?: string): Duration

  • Create an invalid Duration.

    Parameters

    • reason: string

      simple string of why this datetime is invalid. Should not contain parameters or anything else data-dependent

    • Optional explanation: string

      longer explanation, may include parameters and other useful debugging information. Defaults to null.

    Returns Duration

Static isDuration

  • Check if an object is a Duration. Works across context boundaries

    Parameters

    • o: unknown

    Returns o is Duration

Generated using TypeDoc