3.7.2(DateTime)
(DateTime)
(Zone)
number:
Timestamp to use for cached zone offset guesses (exposed for test)
Cache for zone offset guesses (exposed for test).
This optimizes quickDT via guessOffsetForZone to avoid repeated calls of zone.offset().
A DateTime is an immutable data structure representing a specific date and time and accompanying methods. It contains class and instance methods for creating, parsing, interrogating, transforming, and formatting them.
A DateTime comprises of:
locale, numberingSystem, and outputCalendar.Here is a brief overview of the most commonly used functionality it provides:
There's plenty others documented below. In addition, for more information on subtler topics like internationalization, time zones, alternative calendars, validity, and so on, see the external documentation.
(any)
Create a local DateTime
(number?)
The calendar year. If omitted (as in, call
local()
with no arguments), the current time will be used
(number
= 1)
The month, 1-indexed
(number
= 1)
The day of the month, 1-indexed
(number
= 0)
The hour of the day, in 24-hour time
(number
= 0)
The minute of the hour, meaning a number between 0 and 59
(number
= 0)
The second of the minute, meaning a number between 0 and 59
(number
= 0)
The millisecond of the second, meaning a number between 0 and 999
DateTime:
DateTime.local() //~> now
DateTime.local({ zone: "America/New_York" }) //~> now, in US east coast time
DateTime.local(2017) //~> 2017-01-01T00:00:00
DateTime.local(2017, 3) //~> 2017-03-01T00:00:00
DateTime.local(2017, 3, 12, { locale: "fr" }) //~> 2017-03-12T00:00:00, with a French locale
DateTime.local(2017, 3, 12, 5) //~> 2017-03-12T05:00:00
DateTime.local(2017, 3, 12, 5, { zone: "utc" }) //~> 2017-03-12T05:00:00, in UTC
DateTime.local(2017, 3, 12, 5, 45) //~> 2017-03-12T05:45:00
DateTime.local(2017, 3, 12, 5, 45, 10) //~> 2017-03-12T05:45:10
DateTime.local(2017, 3, 12, 5, 45, 10, 765) //~> 2017-03-12T05:45:10.765
Create a DateTime in UTC
(number?)
The calendar year. If omitted (as in, call
utc()
with no arguments), the current time will be used
(number
= 1)
The month, 1-indexed
(number
= 1)
The day of the month
(number
= 0)
The hour of the day, in 24-hour time
(number
= 0)
The minute of the hour, meaning a number between 0 and 59
(number
= 0)
The second of the minute, meaning a number between 0 and 59
(number
= 0)
The millisecond of the second, meaning a number between 0 and 999
(Object)
configuration options for the DateTime
| Name | Description |
|---|---|
options.locale string?
|
a locale to set on the resulting DateTime instance |
options.outputCalendar string?
|
the output calendar to set on the resulting DateTime instance |
options.numberingSystem string?
|
the numbering system to set on the resulting DateTime instance |
options.weekSettings string?
|
the week settings to set on the resulting DateTime instance |
DateTime:
DateTime.utc() //~> now
DateTime.utc(2017) //~> 2017-01-01T00:00:00Z
DateTime.utc(2017, 3) //~> 2017-03-01T00:00:00Z
DateTime.utc(2017, 3, 12) //~> 2017-03-12T00:00:00Z
DateTime.utc(2017, 3, 12, 5) //~> 2017-03-12T05:00:00Z
DateTime.utc(2017, 3, 12, 5, 45) //~> 2017-03-12T05:45:00Z
DateTime.utc(2017, 3, 12, 5, 45, { locale: "fr" }) //~> 2017-03-12T05:45:00Z with a French locale
DateTime.utc(2017, 3, 12, 5, 45, 10) //~> 2017-03-12T05:45:10Z
DateTime.utc(2017, 3, 12, 5, 45, 10, 765, { locale: "fr" }) //~> 2017-03-12T05:45:10.765Z with a French locale
Create a DateTime from a number of milliseconds since the epoch (meaning since 1 January 1970 00:00:00 UTC). Uses the default zone.
(number)
a number of milliseconds since 1970 UTC
(Object
= {})
configuration options for the DateTime
| Name | Description |
|---|---|
options.zone (string | Zone)
(default 'local')
|
the zone to place the DateTime into |
options.locale string?
|
a locale to set on the resulting DateTime instance |
options.outputCalendar string
|
the output calendar to set on the resulting DateTime instance |
options.numberingSystem string
|
the numbering system to set on the resulting DateTime instance |
options.weekSettings string
|
the week settings to set on the resulting DateTime instance |
DateTime:
Create a DateTime from a number of seconds since the epoch (meaning since 1 January 1970 00:00:00 UTC). Uses the default zone.
(number)
a number of seconds since 1970 UTC
(Object
= {})
configuration options for the DateTime
| Name | Description |
|---|---|
options.zone (string | Zone)
(default 'local')
|
the zone to place the DateTime into |
options.locale string?
|
a locale to set on the resulting DateTime instance |
options.outputCalendar string
|
the output calendar to set on the resulting DateTime instance |
options.numberingSystem string
|
the numbering system to set on the resulting DateTime instance |
options.weekSettings string
|
the week settings to set on the resulting DateTime instance |
DateTime:
Create a DateTime from a JavaScript object with keys like 'year' and 'hour' with reasonable defaults.
(Object)
the object to create the DateTime from
| Name | Description |
|---|---|
obj.year number
|
a year, such as 1987 |
obj.month number
|
a month, 1-12 |
obj.day number
|
a day of the month, 1-31, depending on the month |
obj.ordinal number
|
day of the year, 1-365 or 366 |
obj.weekYear number
|
an ISO week year |
obj.weekNumber number
|
an ISO week number, between 1 and 52 or 53, depending on the year |
obj.weekday number
|
an ISO weekday, 1-7, where 1 is Monday and 7 is Sunday |
obj.localWeekYear number
|
a week year, according to the locale |
obj.localWeekNumber number
|
a week number, between 1 and 52 or 53, depending on the year, according to the locale |
obj.localWeekday number
|
a weekday, 1-7, where 1 is the first and 7 is the last day of the week, according to the locale |
obj.hour number
|
hour of the day, 0-23 |
obj.minute number
|
minute of the hour, 0-59 |
obj.second number
|
second of the minute, 0-59 |
obj.millisecond number
|
millisecond of the second, 0-999 |
(Object
= {})
options for creating this DateTime
| Name | Description |
|---|---|
opts.zone (string | Zone)
(default 'local')
|
interpret the numbers in the context of a particular zone. Can take any value taken as the first argument to setZone() |
opts.locale string
(default 'system\'slocale')
|
a locale to set on the resulting DateTime instance |
opts.outputCalendar string
|
the output calendar to set on the resulting DateTime instance |
opts.numberingSystem string
|
the numbering system to set on the resulting DateTime instance |
opts.weekSettings string
|
the week settings to set on the resulting DateTime instance |
DateTime:
DateTime.fromObject({ year: 1982, month: 5, day: 25}).toISODate() //=> '1982-05-25'
DateTime.fromObject({ year: 1982 }).toISODate() //=> '1982-01-01'
DateTime.fromObject({ hour: 10, minute: 26, second: 6 }) //~> today at 10:26:06
DateTime.fromObject({ hour: 10, minute: 26, second: 6 }, { zone: 'utc' }),
DateTime.fromObject({ hour: 10, minute: 26, second: 6 }, { zone: 'local' })
DateTime.fromObject({ hour: 10, minute: 26, second: 6 }, { zone: 'America/New_York' })
DateTime.fromObject({ weekYear: 2016, weekNumber: 2, weekday: 3 }).toISODate() //=> '2016-01-13'
DateTime.fromObject({ localWeekYear: 2022, localWeekNumber: 1, localWeekday: 1 }, { locale: "en-US" }).toISODate() //=> '2021-12-26'
Create a DateTime from an ISO 8601 string
(string)
the ISO string
(Object
= {})
options to affect the creation
| Name | Description |
|---|---|
opts.zone (string | Zone)
(default 'local')
|
use this zone if no offset is specified in the input string itself. Will also convert the time to this zone |
opts.setZone boolean
(default false)
|
override the zone with a fixed-offset zone specified in the string itself, if it specifies one |
opts.locale string
(default 'system'slocale')
|
a locale to set on the resulting DateTime instance |
opts.outputCalendar string?
|
the output calendar to set on the resulting DateTime instance |
opts.numberingSystem string?
|
the numbering system to set on the resulting DateTime instance |
opts.weekSettings string?
|
the week settings to set on the resulting DateTime instance |
DateTime:
DateTime.fromISO('2016-05-25T09:08:34.123')
DateTime.fromISO('2016-05-25T09:08:34.123+06:00')
DateTime.fromISO('2016-05-25T09:08:34.123+06:00', {setZone: true})
DateTime.fromISO('2016-05-25T09:08:34.123', {zone: 'utc'})
DateTime.fromISO('2016-W05-4')
Create a DateTime from an RFC 2822 string
(string)
the RFC 2822 string
(Object
= {})
options to affect the creation
| Name | Description |
|---|---|
opts.zone (string | Zone)
(default 'local')
|
convert the time to this zone. Since the offset is always specified in the string itself, this has no effect on the interpretation of string, merely the zone the resulting DateTime is expressed in. |
opts.setZone boolean
(default false)
|
override the zone with a fixed-offset zone specified in the string itself, if it specifies one |
opts.locale string
(default 'system'slocale')
|
a locale to set on the resulting DateTime instance |
opts.outputCalendar string
|
the output calendar to set on the resulting DateTime instance |
opts.numberingSystem string
|
the numbering system to set on the resulting DateTime instance |
opts.weekSettings string
|
the week settings to set on the resulting DateTime instance |
DateTime:
DateTime.fromRFC2822('25 Nov 2016 13:23:12 GMT')
DateTime.fromRFC2822('Fri, 25 Nov 2016 13:23:12 +0600')
DateTime.fromRFC2822('25 Nov 2016 13:23 Z')
Create a DateTime from an HTTP header date
(string)
the HTTP header date
(Object
= {})
options to affect the creation
| Name | Description |
|---|---|
opts.zone (string | Zone)
(default 'local')
|
convert the time to this zone. Since HTTP dates are always in UTC, this has no effect on the interpretation of string, merely the zone the resulting DateTime is expressed in. |
opts.setZone boolean
(default false)
|
override the zone with the fixed-offset zone specified in the string. For HTTP dates, this is always UTC, so this option is equivalent to setting the
zone
option to 'utc', but this option is included for consistency with similar methods.
|
opts.locale string
(default 'system'slocale')
|
a locale to set on the resulting DateTime instance |
opts.outputCalendar string
|
the output calendar to set on the resulting DateTime instance |
opts.numberingSystem string
|
the numbering system to set on the resulting DateTime instance |
opts.weekSettings string
|
the week settings to set on the resulting DateTime instance |
DateTime:
DateTime.fromHTTP('Sun, 06 Nov 1994 08:49:37 GMT')
DateTime.fromHTTP('Sunday, 06-Nov-94 08:49:37 GMT')
DateTime.fromHTTP('Sun Nov 6 08:49:37 1994')
Create a DateTime from an input string and format string. Defaults to en-US if no locale has been specified, regardless of the system's locale. For a table of tokens and their interpretations, see here.
(string)
the string to parse
(string)
the format the string is expected to be in (see the link below for the formats)
(Object
= {})
options to affect the creation
| Name | Description |
|---|---|
opts.zone (string | Zone)
(default 'local')
|
use this zone if no offset is specified in the input string itself. Will also convert the DateTime to this zone |
opts.setZone boolean
(default false)
|
override the zone with a zone specified in the string itself, if it specifies one |
opts.locale string
(default 'en-US')
|
a locale string to use when parsing. Will also set the DateTime to this locale |
opts.numberingSystem string
|
the numbering system to use when parsing. Will also set the resulting DateTime to this numbering system |
opts.weekSettings string
|
the week settings to set on the resulting DateTime instance |
opts.outputCalendar string
|
the output calendar to set on the resulting DateTime instance |
DateTime:
(any)
(any)
(any
= {})
Create a DateTime from a SQL date, time, or datetime Defaults to en-US if no locale has been specified, regardless of the system's locale
(string)
the string to parse
(Object
= {})
options to affect the creation
| Name | Description |
|---|---|
opts.zone (string | Zone)
(default 'local')
|
use this zone if no offset is specified in the input string itself. Will also convert the DateTime to this zone |
opts.setZone boolean
(default false)
|
override the zone with a zone specified in the string itself, if it specifies one |
opts.locale string
(default 'en-US')
|
a locale string to use when parsing. Will also set the DateTime to this locale |
opts.numberingSystem string
|
the numbering system to use when parsing. Will also set the resulting DateTime to this numbering system |
opts.weekSettings string
|
the week settings to set on the resulting DateTime instance |
opts.outputCalendar string
|
the output calendar to set on the resulting DateTime instance |
DateTime:
DateTime.fromSQL('2017-05-15')
DateTime.fromSQL('2017-05-15 09:12:34')
DateTime.fromSQL('2017-05-15 09:12:34.342')
DateTime.fromSQL('2017-05-15 09:12:34.342+06:00')
DateTime.fromSQL('2017-05-15 09:12:34.342 America/Los_Angeles')
DateTime.fromSQL('2017-05-15 09:12:34.342 America/Los_Angeles', { setZone: true })
DateTime.fromSQL('2017-05-15 09:12:34.342', { zone: 'America/Los_Angeles' })
DateTime.fromSQL('09:12:34.342')
(any)
(any)
(any
= {})
Build a parser for fmt using the given locale. This parser can be passed
to DateTime.fromFormatParser to a parse a date in this format. This
can be used to optimize cases where many dates need to be parsed in a
specific format.
(String)
the format the string is expected to be in (see
description)
(Object
= {})
options used to set locale and numberingSystem
for parser
TokenParser:
opaque object to be used
DateTime#toLocaleString format like 10/14/1983
Type: Object
DateTime#toLocaleString format like 'Oct 14, 1983'
Type: Object
DateTime#toLocaleString format like 'Fri, Oct 14, 1983'
Type: Object
DateTime#toLocaleString format like 'October 14, 1983'
Type: Object
DateTime#toLocaleString format like 'Tuesday, October 14, 1983'
Type: Object
DateTime#toLocaleString format like '09:30 AM'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like '09:30:23 AM'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like '09:30:23 AM EDT'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like '09:30:23 AM Eastern Daylight Time'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like '09:30', always 24-hour.
Type: Object
DateTime#toLocaleString format like '09:30:23', always 24-hour.
Type: Object
DateTime#toLocaleString format like '09:30:23 EDT', always 24-hour.
Type: Object
DateTime#toLocaleString format like '09:30:23 Eastern Daylight Time', always 24-hour.
Type: Object
DateTime#toLocaleString format like '10/14/1983, 9:30 AM'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like '10/14/1983, 9:30:33 AM'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like 'Oct 14, 1983, 9:30 AM'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like 'Oct 14, 1983, 9:30:33 AM'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like 'Fri, 14 Oct 1983, 9:30 AM'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like 'October 14, 1983, 9:30 AM EDT'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like 'October 14, 1983, 9:30:33 AM EDT'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like 'Friday, October 14, 1983, 9:30 AM Eastern Daylight Time'. Only 12-hour if the locale is.
Type: Object
DateTime#toLocaleString format like 'Friday, October 14, 1983, 9:30:33 AM Eastern Daylight Time'. Only 12-hour if the locale is.
Type: Object
Returns whether the DateTime is valid. Invalid DateTimes occur when:
Type: boolean
Returns an error code if this DateTime is invalid, or null if the DateTime is valid
Type: string
Returns an explanation of why this DateTime became invalid, or null if the DateTime is valid
Type: string
Get the locale of a DateTime, such 'en-GB'. The locale is used when formatting the DateTime
Type: string
Get the numbering system of a DateTime, such 'beng'. The numbering system is used when formatting the DateTime
Type: string
Get the output calendar of a DateTime, such 'islamic'. The output calendar is used when formatting the DateTime
Type: string
Get the day of the month (1-30ish).
Type: number
DateTime.local(2017, 5, 25).day //=> 25
Get the hour of the day (0-23).
Type: number
DateTime.local(2017, 5, 25, 9).hour //=> 9
Get the minute of the hour (0-59).
Type: number
DateTime.local(2017, 5, 25, 9, 30).minute //=> 30
Get the second of the minute (0-59).
Type: number
DateTime.local(2017, 5, 25, 9, 30, 52).second //=> 52
Get the millisecond of the second (0-999).
Type: number
DateTime.local(2017, 5, 25, 9, 30, 52, 654).millisecond //=> 654
Get the week year
Type: number
DateTime.local(2014, 12, 31).weekYear //=> 2015
Get the week number of the week year (1-52ish).
Type: number
DateTime.local(2017, 5, 25).weekNumber //=> 21
Get the day of the week. 1 is Monday and 7 is Sunday
Type: number
DateTime.local(2014, 11, 31).weekday //=> 4
Returns true if this date is on a weekend according to the locale, false otherwise
boolean:
Get the day of the week according to the locale. 1 is the first day of the week and 7 is the last day of the week. If the locale assigns Sunday as the first day of the week, then a date which is a Sunday will return 1,
number:
Get the week number of the week year according to the locale. Different locales assign week numbers differently, because the week can start on different days of the week (see localWeekday) and because a different number of days is required for a week to count as the first week of a year.
number:
Get the week year according to the locale. Different locales assign week numbers (and therefor week years) differently, see localWeekNumber.
number:
Get the human readable short month name, such as 'Oct'. Defaults to the system's locale if no locale has been specified
Type: string
DateTime.local(2017, 10, 30).monthShort //=> Oct
Get the human readable long month name, such as 'October'. Defaults to the system's locale if no locale has been specified
Type: string
DateTime.local(2017, 10, 30).monthLong //=> October
Get the human readable short weekday, such as 'Mon'. Defaults to the system's locale if no locale has been specified
Type: string
DateTime.local(2017, 10, 30).weekdayShort //=> Mon
Get the human readable long weekday, such as 'Monday'. Defaults to the system's locale if no locale has been specified
Type: string
DateTime.local(2017, 10, 30).weekdayLong //=> Monday
Get the UTC offset of this DateTime in minutes
Type: number
DateTime.now().offset //=> -240
DateTime.utc().offset //=> 0
Get the short human name for the zone's current offset, for example "EST" or "EDT". Defaults to the system's locale if no locale has been specified
Type: string
Get the long human name for the zone's current offset, for example "Eastern Standard Time" or "Eastern Daylight Time". Defaults to the system's locale if no locale has been specified
Type: string
Get whether this zone's offset ever changes, as in a DST.
Type: boolean
Get those DateTimes which have the same local time as this DateTime, but a different offset from UTC
in this DateTime's zone. During DST changes local time can be ambiguous, for example
2023-10-29T02:30:00 in Europe/Berlin can have offset +01:00 or +02:00.
This method will return both possible DateTimes if this DateTime's local time is ambiguous.
Array<DateTime>:
Returns true if this DateTime is in a leap year, false otherwise
Type: boolean
DateTime.local(2016).isInLeapYear //=> true
DateTime.local(2013).isInLeapYear //=> false
Returns the number of days in this DateTime's month
Type: number
DateTime.local(2016, 2).daysInMonth //=> 29
DateTime.local(2016, 3).daysInMonth //=> 31
Returns the number of days in this DateTime's year
Type: number
DateTime.local(2016).daysInYear //=> 366
DateTime.local(2013).daysInYear //=> 365
Returns the number of weeks in this DateTime's year
Type: number
DateTime.local(2004).weeksInWeekYear //=> 53
DateTime.local(2013).weeksInWeekYear //=> 52
Returns the number of weeks in this DateTime's local week year
Type: number
DateTime.local(2020, 6, {locale: 'en-US'}).weeksInLocalWeekYear //=> 52
DateTime.local(2020, 6, {locale: 'de-DE'}).weeksInLocalWeekYear //=> 53
"Set" the DateTime's zone to specified zone. Returns a newly-constructed DateTime.
By default, the setter keeps the underlying time the same (as in, the same timestamp), but the new instance will report different local times and consider DSTs when making computations, as with DateTime#plus. You may wish to use DateTime#toLocal and DateTime#toUTC which provide simple convenience wrappers for commonly used zones.
((string | Zone)
= 'local')
a zone identifier. As a string, that can be any IANA zone supported by the host environment, or a fixed-offset name of the form 'UTC+3', or the strings 'local' or 'utc'. You may also supply an instance of a
DateTime#Zone
class.
DateTime:
"Set" the locale, numberingSystem, or outputCalendar. Returns a newly-constructed DateTime.
(Object
= {})
the properties to set
| Name | Description |
|---|---|
properties.locale any
|
|
properties.numberingSystem any
|
|
properties.outputCalendar any
|
DateTime:
DateTime.local(2017, 5, 25).reconfigure({ locale: 'en-GB' })
"Set" the values of specified units. Returns a newly-constructed DateTime. You can only set units with this method; for "setting" metadata, see DateTime#reconfigure and DateTime#setZone.
This method also supports setting locale-based week units, i.e. localWeekday, localWeekNumber and localWeekYear.
They cannot be mixed with ISO-week units like weekday.
(Object)
a mapping of units to numbers
DateTime:
dt.set({ year: 2017 })
dt.set({ hour: 8, minute: 30 })
dt.set({ weekday: 5 })
dt.set({ year: 2005, ordinal: 234 })
Add a period of time to this DateTime and return the resulting DateTime
Adding hours, minutes, seconds, or milliseconds increases the timestamp by the right number of milliseconds. Adding days, months, or years shifts the calendar, accounting for DSTs and leap years along the way. Thus, dt.plus({ hours: 24 }) may result in a different time than dt.plus({ days: 1 }) if there's a DST shift in between.
DateTime:
DateTime.now().plus(123) //~> in 123 milliseconds
DateTime.now().plus({ minutes: 15 }) //~> in 15 minutes
DateTime.now().plus({ days: 1 }) //~> this time tomorrow
DateTime.now().plus({ days: -1 }) //~> this time yesterday
DateTime.now().plus({ hours: 3, minutes: 13 }) //~> in 3 hr, 13 min
DateTime.now().plus(Duration.fromObject({ hours: 3, minutes: 13 })) //~> in 3 hr, 13 min
Subtract a period of time to this DateTime and return the resulting DateTime See DateTime#plus
DateTime:
"Set" this DateTime to the beginning of a unit of time.
(string)
The unit to go to the beginning of. Can be 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second', or 'millisecond'.
DateTime:
DateTime.local(2014, 3, 3).startOf('month').toISODate(); //=> '2014-03-01'
DateTime.local(2014, 3, 3).startOf('year').toISODate(); //=> '2014-01-01'
DateTime.local(2014, 3, 3).startOf('week').toISODate(); //=> '2014-03-03', weeks always start on Mondays
DateTime.local(2014, 3, 3, 5, 30).startOf('day').toISOTime(); //=> '00:00.000-05:00'
DateTime.local(2014, 3, 3, 5, 30).startOf('hour').toISOTime(); //=> '05:00:00.000-05:00'
"Set" this DateTime to the end (meaning the last millisecond) of a unit of time
(string)
The unit to go to the end of. Can be 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second', or 'millisecond'.
DateTime:
DateTime.local(2014, 3, 3).endOf('month').toISO(); //=> '2014-03-31T23:59:59.999-05:00'
DateTime.local(2014, 3, 3).endOf('year').toISO(); //=> '2014-12-31T23:59:59.999-05:00'
DateTime.local(2014, 3, 3).endOf('week').toISO(); // => '2014-03-09T23:59:59.999-05:00', weeks start on Mondays
DateTime.local(2014, 3, 3, 5, 30).endOf('day').toISO(); //=> '2014-03-03T23:59:59.999-05:00'
DateTime.local(2014, 3, 3, 5, 30).endOf('hour').toISO(); //=> '2014-03-03T05:59:59.999-05:00'
Returns a string representation of this DateTime formatted according to the specified format string. You may not want this. See DateTime#toLocaleString for a more flexible formatting tool. For a table of tokens and their interpretations, see here. Defaults to en-US if no locale has been specified, regardless of the system's locale.
(string)
the format string
(Object
= {})
opts to override the configuration options on this DateTime
string:
DateTime.now().toFormat('yyyy LLL dd') //=> '2017 Apr 22'
DateTime.now().setLocale('fr').toFormat('yyyy LLL dd') //=> '2017 avr. 22'
DateTime.now().toFormat('yyyy LLL dd', { locale: "fr" }) //=> '2017 avr. 22'
DateTime.now().toFormat("HH 'hours and' mm 'minutes'") //=> '20 hours and 55 minutes'
Returns a localized string representing this date. Accepts the same options as the Intl.DateTimeFormat constructor and any presets defined by Luxon, such as DateTime.DATE_FULL or DateTime.TIME_SIMPLE.
The exact behavior of this method is browser-specific, but in general it will return an appropriate representation
of the DateTime in the assigned locale.
Defaults to the system's locale if no locale has been specified
(any
= Formats.DATE_SHORT)
{Object} - Intl.DateTimeFormat constructor options and configuration options
(Object
= {})
opts to override the configuration options on this DateTime
string:
DateTime.now().toLocaleString(); //=> 4/20/2017
DateTime.now().setLocale('en-gb').toLocaleString(); //=> '20/04/2017'
DateTime.now().toLocaleString(DateTime.DATE_FULL); //=> 'April 20, 2017'
DateTime.now().toLocaleString(DateTime.DATE_FULL, { locale: 'fr' }); //=> '28 août 2022'
DateTime.now().toLocaleString(DateTime.TIME_SIMPLE); //=> '11:32 AM'
DateTime.now().toLocaleString(DateTime.DATETIME_SHORT); //=> '4/20/2017, 11:32 AM'
DateTime.now().toLocaleString({ weekday: 'long', month: 'long', day: '2-digit' }); //=> 'Thursday, April 20'
DateTime.now().toLocaleString({ weekday: 'short', month: 'short', day: '2-digit', hour: '2-digit', minute: '2-digit' }); //=> 'Thu, Apr 20, 11:27 AM'
DateTime.now().toLocaleString({ hour: '2-digit', minute: '2-digit', hourCycle: 'h23' }); //=> '11:32'
Returns an array of format "parts", meaning individual tokens along with metadata. This is allows callers to post-process individual sections of the formatted output. Defaults to the system's locale if no locale has been specified
(any
= {})
{Object} - Intl.DateTimeFormat constructor options, same as
toLocaleString
.
DateTime.now().toLocaleParts(); //=> [
//=> { type: 'day', value: '25' },
//=> { type: 'literal', value: '/' },
//=> { type: 'month', value: '05' },
//=> { type: 'literal', value: '/' },
//=> { type: 'year', value: '1982' }
//=> ]
Returns an ISO 8601-compliant string representation of this DateTime
(Object
= {})
options
| Name | Description |
|---|---|
opts.format string
(default 'extended')
|
choose between the basic and extended format |
opts.suppressSeconds boolean
(default false)
|
exclude seconds from the format if they're 0 |
opts.suppressMilliseconds boolean
(default false)
|
exclude milliseconds from the format if they're 0 |
opts.includeOffset boolean
(default true)
|
include the offset, such as 'Z' or '-04:00' |
opts.extendedZone boolean
(default false)
|
add the time zone format extension |
opts.precision string
(default 'milliseconds')
|
truncate output to desired presicion: 'years', 'months', 'days', 'hours', 'minutes', 'seconds' or 'milliseconds'. When precision and suppressSeconds or suppressMilliseconds are used together, precision sets the maximum unit shown in the output, however seconds or milliseconds will still be suppressed if they are 0. |
(string | null):
DateTime.utc(1983, 5, 25).toISO() //=> '1982-05-25T00:00:00.000Z'
DateTime.now().toISO() //=> '2017-04-22T20:47:05.335-04:00'
DateTime.now().toISO({ includeOffset: false }) //=> '2017-04-22T20:47:05.335'
DateTime.now().toISO({ format: 'basic' }) //=> '20170422T204705.335-0400'
DateTime.now().toISO({ precision: 'day' }) //=> '2017-04-22Z'
DateTime.now().toISO({ precision: 'minute' }) //=> '2017-04-22T20:47Z'
Returns an ISO 8601-compliant string representation of this DateTime's date component
(string | null):
DateTime.utc(1982, 5, 25).toISODate() //=> '1982-05-25'
DateTime.utc(1982, 5, 25).toISODate({ format: 'basic' }) //=> '19820525'
DateTime.utc(1982, 5, 25).toISODate({ precision: 'month' }) //=> '1982-05'
Returns an ISO 8601-compliant string representation of this DateTime's time component
(Object
= {})
options
| Name | Description |
|---|---|
opts.suppressMilliseconds boolean
(default false)
|
exclude milliseconds from the format if they're 0 |
opts.suppressSeconds boolean
(default false)
|
exclude seconds from the format if they're 0 |
opts.includeOffset boolean
(default true)
|
include the offset, such as 'Z' or '-04:00' |
opts.includePrefix boolean
(default false)
|
include the
T
prefix
|
opts.extendedZone boolean
(default true)
|
add the time zone format extension |
opts.format string
(default 'extended')
|
choose between the basic and extended format |
opts.precision string
(default 'milliseconds')
|
truncate output to desired presicion: 'hours', 'minutes', 'seconds' or 'milliseconds'. When precision and suppressSeconds or suppressMilliseconds are used together, precision sets the maximum unit shown in the output, however seconds or milliseconds will still be suppressed if they are 0. |
string:
DateTime.utc().set({ hour: 7, minute: 34 }).toISOTime() //=> '07:34:19.361Z'
DateTime.utc().set({ hour: 7, minute: 34, seconds: 0, milliseconds: 0 }).toISOTime({ suppressSeconds: true }) //=> '07:34Z'
DateTime.utc().set({ hour: 7, minute: 34 }).toISOTime({ format: 'basic' }) //=> '073419.361Z'
DateTime.utc().set({ hour: 7, minute: 34 }).toISOTime({ includePrefix: true }) //=> 'T07:34:19.361Z'
DateTime.utc().set({ hour: 7, minute: 34, second: 56 }).toISOTime({ precision: 'minute' }) //=> '07:34Z'
Returns a string representation of this DateTime appropriate for use in HTTP headers. The output is always expressed in GMT. Specifically, the string conforms to RFC 1123.
string:
DateTime.utc(2014, 7, 13).toHTTP() //=> 'Sun, 13 Jul 2014 00:00:00 GMT'
DateTime.utc(2014, 7, 13, 19).toHTTP() //=> 'Sun, 13 Jul 2014 19:00:00 GMT'
Returns a string representation of this DateTime appropriate for use in SQL Time
(Object
= {})
options
| Name | Description |
|---|---|
opts.includeOffset boolean
(default true)
|
include the offset, such as 'Z' or '-04:00' |
opts.includeZone boolean
(default false)
|
include the zone, such as 'America/New_York'. Overrides includeOffset. |
opts.includeOffsetSpace boolean
(default true)
|
include the space between the time and the offset, such as '05:15:16.345 -04:00' |
string:
DateTime.utc().toSQL() //=> '05:15:16.345'
DateTime.now().toSQL() //=> '05:15:16.345 -04:00'
DateTime.now().toSQL({ includeOffset: false }) //=> '05:15:16.345'
DateTime.now().toSQL({ includeZone: false }) //=> '05:15:16.345 America/New_York'
Returns a string representation of this DateTime appropriate for use in SQL DateTime
(Object
= {})
options
| Name | Description |
|---|---|
opts.includeZone boolean
(default false)
|
include the zone, such as 'America/New_York'. Overrides includeOffset. |
opts.includeOffset boolean
(default true)
|
include the offset, such as 'Z' or '-04:00' |
opts.includeOffsetSpace boolean
(default true)
|
include the space between the time and the offset, such as '05:15:16.345 -04:00' |
string:
DateTime.utc(2014, 7, 13).toSQL() //=> '2014-07-13 00:00:00.000 Z'
DateTime.local(2014, 7, 13).toSQL() //=> '2014-07-13 00:00:00.000 -04:00'
DateTime.local(2014, 7, 13).toSQL({ includeOffset: false }) //=> '2014-07-13 00:00:00.000'
DateTime.local(2014, 7, 13).toSQL({ includeZone: true }) //=> '2014-07-13 00:00:00.000 America/New_York'
Returns the epoch milliseconds of this DateTime. Alias of DateTime#toMillis
number:
Returns a JavaScript object with this DateTime's year, month, day, and so on.
(any
= {})
options for generating the object
| Name | Description |
|---|---|
opts.includeConfig boolean
(default false)
|
include configuration attributes in the output |
Object:
DateTime.now().toObject() //=> { year: 2017, month: 4, day: 22, hour: 20, minute: 49, second: 42, millisecond: 268 }
Return the difference between two DateTimes as a Duration.
(DateTime)
the DateTime to compare this one to
Duration:
var i1 = DateTime.fromISO('1982-05-25T09:45'),
i2 = DateTime.fromISO('1983-10-14T10:30');
i2.diff(i1).toObject() //=> { milliseconds: 43807500000 }
i2.diff(i1, 'hours').toObject() //=> { hours: 12168.75 }
i2.diff(i1, ['months', 'days']).toObject() //=> { months: 16, days: 19.03125 }
i2.diff(i1, ['months', 'days', 'hours']).toObject() //=> { months: 16, days: 19, hours: 0.75 }
Return the difference between this DateTime and right now. See DateTime#diff
Duration:
Return whether this DateTime is in the same unit of time as another DateTime.
Higher-order units must also be identical for this function to return true.
Note that time zones are ignored in this comparison, which compares the local calendar time. Use DateTime#setZone to convert one of the dates if needed.
boolean:
DateTime.now().hasSame(otherDT, 'day'); //~> true if otherDT is in the same current calendar day
Returns a string representation of a this time relative to now, such as "in two days". Can only internationalize if your platform supports Intl.RelativeTimeFormat. Rounds towards zero by default.
(Object
= {})
options that affect the output
| Name | Description |
|---|---|
options.base DateTime
(default DateTime.now())
|
the DateTime to use as the basis to which this time is compared. Defaults to now. |
options.style string
(default "long")
|
the style of units, must be "long", "short", or "narrow" |
options.unit (string | Array<string>)
|
use a specific unit or array of units; if omitted, or an array, the method will pick the best unit. Use an array or one of "years", "quarters", "months", "weeks", "days", "hours", "minutes", or "seconds" |
options.round boolean
(default true)
|
whether to round the numbers in the output. |
options.rounding string
(default "trunc")
|
rounding method to use when rounding the numbers in the output. Can be "trunc" (toward zero), "expand" (away from zero), "round", "floor", or "ceil". |
options.padding number
(default 0)
|
padding in milliseconds. This allows you to round up the result if it fits inside the threshold. Don't use in combination with {round: false} because the decimal output will include the padding. |
options.locale string
|
override the locale of this DateTime |
options.numberingSystem string
|
override the numberingSystem of this DateTime. The Intl system may choose not to honor this |
DateTime.now().plus({ days: 1 }).toRelative() //=> "in 1 day"
DateTime.now().setLocale("es").toRelative({ days: 1 }) //=> "dentro de 1 día"
DateTime.now().plus({ days: 1 }).toRelative({ locale: "fr" }) //=> "dans 23 heures"
DateTime.now().minus({ days: 2 }).toRelative() //=> "2 days ago"
DateTime.now().minus({ days: 2 }).toRelative({ unit: "hours" }) //=> "48 hours ago"
DateTime.now().minus({ hours: 36 }).toRelative({ round: false }) //=> "1.5 days ago"
Returns a string representation of this date relative to today, such as "yesterday" or "next month". Only internationalizes on platforms that supports Intl.RelativeTimeFormat.
(Object
= {})
options that affect the output
| Name | Description |
|---|---|
options.base DateTime
(default DateTime.now())
|
the DateTime to use as the basis to which this time is compared. Defaults to now. |
options.locale string
|
override the locale of this DateTime |
options.unit string
|
use a specific unit; if omitted, the method will pick the unit. Use one of "years", "quarters", "months", "weeks", or "days" |
options.numberingSystem string
|
override the numberingSystem of this DateTime. The Intl system may choose not to honor this |
DateTime.now().plus({ days: 1 }).toRelativeCalendar() //=> "tomorrow"
DateTime.now().setLocale("es").plus({ days: 1 }).toRelative() //=> ""mañana"
DateTime.now().plus({ days: 1 }).toRelativeCalendar({ locale: "fr" }) //=> "demain"
DateTime.now().minus({ days: 2 }).toRelativeCalendar() //=> "2 days ago"
(any)
(Locale)
Check if local week units like localWeekday are used in obj. If so, validates that they are not mixed with ISO week units and then copies them to the normal week unit properties. Modifies obj in-place!
(any)
the object values
(any)
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.
(any)
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.
(Object)
the object to create the DateTime from
| Name | Description |
|---|---|
obj.years number
|
|
obj.quarters number
|
|
obj.months number
|
|
obj.weeks number
|
|
obj.days number
|
|
obj.hours number
|
|
obj.minutes number
|
|
obj.seconds number
|
|
obj.milliseconds number
|
(Object
= [])
options for creating this Duration
| Name | Description |
|---|---|
opts.locale string
(default 'en-US')
|
the locale to use |
opts.numberingSystem string
|
the numbering system to use |
opts.conversionAccuracy string
(default 'casual')
|
the preset conversion system to use |
opts.matrix string
(default Object)
|
the custom conversion system to use |
Duration:
Create a Duration from an ISO 8601 duration string.
(string)
text to parse
(Object)
options for parsing
| Name | Description |
|---|---|
opts.locale string
(default 'en-US')
|
the locale to use |
opts.numberingSystem string
|
the numbering system to use |
opts.conversionAccuracy string
(default 'casual')
|
the preset conversion system to use |
opts.matrix string
(default Object)
|
the preset conversion system to use |
Duration:
Duration.fromISO('P3Y6M1W4DT12H30M5S').toObject() //=> { years: 3, months: 6, weeks: 1, days: 4, hours: 12, minutes: 30, seconds: 5 }
Duration.fromISO('PT23H').toObject() //=> { hours: 23 }
Duration.fromISO('P5Y3M').toObject() //=> { years: 5, months: 3 }
Create a Duration from an ISO 8601 time string.
(string)
text to parse
(Object)
options for parsing
| Name | Description |
|---|---|
opts.locale string
(default 'en-US')
|
the locale to use |
opts.numberingSystem string
|
the numbering system to use |
opts.conversionAccuracy string
(default 'casual')
|
the preset conversion system to use |
opts.matrix string
(default Object)
|
the conversion system to use |
Duration:
Duration.fromISOTime('11:22:33.444').toObject() //=> { hours: 11, minutes: 22, seconds: 33, milliseconds: 444 }
Duration.fromISOTime('11:00').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
Duration.fromISOTime('T11:00').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
Duration.fromISOTime('1100').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
Duration.fromISOTime('T1100').toObject() //=> { hours: 11, minutes: 0, seconds: 0 }
Get the numbering system of a Duration, such 'beng'. The numbering system is used when formatting the Duration
Type: string
Returns a string representation of this Duration formatted according to the specified format string. You may use these tokens:
S for millisecondss for secondsm for minutesh for hoursd for daysw for weeksM for monthsy for years
Notes:(string)
the format string
string:
Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("y d s") //=> "1 6 2"
Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("yy dd sss") //=> "01 06 002"
Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("M S") //=> "12 518402000"
Duration.fromObject({ days: 6, seconds: 2 }).toFormat("d s", { signMode: "all" }) //=> "+6 +2"
Duration.fromObject({ days: -6, seconds: -2 }).toFormat("d s", { signMode: "all" }) //=> "-6 -2"
Duration.fromObject({ days: -6, seconds: -2 }).toFormat("d s", { signMode: "negativeLargestOnly" }) //=> "-6 2"
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.
(Object
= {})
Formatting options. Accepts the same keys as the options parameter of the native
Intl.NumberFormat
constructor, as well as
listStyle
.
| Name | Description |
|---|---|
opts.listStyle string
(default 'narrow')
|
How to format the merged list. Corresponds to the
style
property of the options parameter of the native
Intl.ListFormat
constructor.
|
opts.showZeros boolean
(default true)
|
Show all units previously used by the duration even if they are zero |
```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'
```
Returns an ISO 8601-compliant string representation of this Duration.
string:
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'
Duration.fromObject({ milliseconds: 6 }).toISO() //=> 'PT0.006S'
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.
(Object
= {})
options
| Name | Description |
|---|---|
opts.suppressMilliseconds boolean
(default false)
|
exclude milliseconds from the format if they're 0 |
opts.suppressSeconds boolean
(default false)
|
exclude seconds from the format if they're 0 |
opts.includePrefix boolean
(default false)
|
include the
T
prefix
|
opts.format string
(default 'extended')
|
choose between the basic and extended format |
string:
Duration.fromObject({ hours: 11 }).toISOTime() //=> '11:00:00.000'
Duration.fromObject({ hours: 11 }).toISOTime({ suppressMilliseconds: true }) //=> '11:00:00'
Duration.fromObject({ hours: 11 }).toISOTime({ suppressSeconds: true }) //=> '11:00'
Duration.fromObject({ hours: 11 }).toISOTime({ includePrefix: true }) //=> 'T11:00:00.000'
Duration.fromObject({ hours: 11 }).toISOTime({ format: 'basic' }) //=> '110000.000'
Make this Duration longer by the specified amount. Return a newly-constructed Duration.
Duration:
Make this Duration shorter by the specified amount. Return a newly-constructed Duration.
Duration:
Scale this Duration by the specified amount. Return a newly-constructed Duration.
(function)
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.
Duration:
Duration.fromObject({ hours: 1, minutes: 30 }).mapUnits(x => x * 2) //=> { hours: 2, minutes: 60 }
Duration.fromObject({ hours: 1, minutes: 30 }).mapUnits((x, u) => u === "hours" ? x * 2 : x) //=> { hours: 2, minutes: 30 }
Reduce this Duration to its canonical representation in its current units. Assuming the overall value of the Duration is positive, this means:
If the overall value is negative, the result of this method is equivalent to this.negate().normalize().negate().
Duration:
Duration.fromObject({ years: 2, days: 5000 }).normalize().toObject() //=> { years: 15, days: 255 }
Duration.fromObject({ days: 5000 }).normalize().toObject() //=> { days: 5000 }
Duration.fromObject({ hours: 12, minutes: -45 }).normalize().toObject() //=> { hours: 11, minutes: 15 }
Duration.fromObject({ years: 2.5, days: 0, hours: 0 }).normalize().toObject() //=> { years: 2, days: 182, hours: 12 }
Returns whether the Duration is invalid. Invalid durations are returned by diff operations on invalid DateTimes or Intervals.
boolean:
Returns an error code if this Duration became invalid, or null if the Duration is valid
string:
Returns the offset's value as a string
(any)
(string)
What style of offset to return.
Accepts 'narrow', 'short', or 'techie'. Returning '+6', '+06:00', or '+0600' respectively
(number)
Epoch milliseconds for which to get the offset
string:
An Interval object represents a half-open interval of time, where each endpoint is a DateTime. Conceptually, it's a container for those two endpoints, accompanied by methods for creating, parsing, interrogating, comparing, transforming, and formatting them.
Here is a brief overview of the most commonly used methods and getters in Interval:
(any)
Create an Interval from an ISO 8601 string.
Accepts <start>/<end>, <start>/<duration>, and <duration>/<end> formats.
(string)
the ISO string to parse
Interval:
Merge an array of Intervals into an equivalent minimal set of Intervals. Combines overlapping and adjacent Intervals. The resulting array will contain the Intervals in ascending order, that is, starting with the earliest Interval and ending with the latest.
(Array)
Array:
Returns the end of the Interval. This is the first instant which is not part of the interval (Interval is half-open).
Type: DateTime
Returns the last DateTime included in the interval (since end is not part of the interval)
Type: DateTime
Returns whether this Interval's end is at least its start, meaning that the Interval isn't 'backwards'.
Type: boolean
Returns an error code if this Interval is invalid, or null if the Interval is valid
Type: string
Returns an explanation of why this Interval became invalid, or null if the Interval is valid
Type: string
Returns the count of minutes, hours, days, months, or years included in the Interval, even in part. Unlike Interval#length this counts sections of the calendar, not periods of time, e.g. specifying 'day' asks 'what dates are included in this interval?', not 'how many days long is this interval?'
(string
= 'milliseconds')
the unit of time to count.
number:
Return an Interval representing the intersection of this Interval and the specified Interval. Specifically, the resulting Interval has the maximum start time and the minimum end time of the two Intervals. Returns null if the intersection is empty, meaning, the intervals don't intersect.
(Interval)
Interval:
Returns a localized string representing this Interval. Accepts the same options as the Intl.DateTimeFormat constructor and any presets defined by Luxon, such as DateTime.DATE_FULL or DateTime.TIME_SIMPLE. The exact behavior of this method is browser-specific, but in general it will return an appropriate representation of the Interval in the assigned locale. Defaults to the system's locale if no locale has been specified.
(Object
= DateTime.DATE_SHORT)
Either a DateTime preset or
Intl.DateTimeFormat constructor options.
(Object
= {})
Options to override the configuration of the start DateTime.
string:
Interval.fromISO('2022-11-07T09:00Z/2022-11-08T09:00Z').toLocaleString(); //=> 11/7/2022 – 11/8/2022
Interval.fromISO('2022-11-07T09:00Z/2022-11-08T09:00Z').toLocaleString(DateTime.DATE_FULL); //=> November 7 – 8, 2022
Interval.fromISO('2022-11-07T09:00Z/2022-11-08T09:00Z').toLocaleString(DateTime.DATE_FULL, { locale: 'fr-FR' }); //=> 7–8 novembre 2022
Interval.fromISO('2022-11-07T17:00Z/2022-11-07T19:00Z').toLocaleString(DateTime.TIME_SIMPLE); //=> 6:00 – 8:00 PM
Interval.fromISO('2022-11-07T17:00Z/2022-11-07T19:00Z').toLocaleString({ weekday: 'short', month: 'short', day: '2-digit', hour: '2-digit', minute: '2-digit' }); //=> Mon, Nov 07, 6:00 – 8:00 p
Returns an ISO 8601-compliant string representation of this Interval.
string:
Returns an ISO 8601-compliant string representation of date of this Interval. The time components are ignored.
string:
Returns an ISO 8601-compliant string representation of time of this Interval. The date components are ignored.
string:
Returns a string representation of this Interval formatted according to the specified format string. You may not want this. See Interval#toLocaleString for a more flexible formatting tool.
(string)
The format string. This string formats the start and end time.
See
DateTime#toFormat
for details.
string:
Return a Duration representing the time spanned by this interval.
Duration:
Interval.fromDateTimes(dt1, dt2).toDuration().toObject() //=> { milliseconds: 88489257 }
Interval.fromDateTimes(dt1, dt2).toDuration('days').toObject() //=> { days: 1.0241812152777778 }
Interval.fromDateTimes(dt1, dt2).toDuration(['hours', 'minutes']).toObject() //=> { hours: 24, minutes: 34.82095 }
Interval.fromDateTimes(dt1, dt2).toDuration(['hours', 'minutes', 'seconds']).toObject() //=> { hours: 24, minutes: 34, seconds: 49.257 }
Interval.fromDateTimes(dt1, dt2).toDuration('seconds').toObject() //=> { seconds: 88489.257 }
Run mapFn on the interval start and end, returning a new Interval from the resulting DateTimes
(function)
Interval:
Interval.fromDateTimes(dt1, dt2).mapEndpoints(endpoint => endpoint.toUTC())
Interval.fromDateTimes(dt1, dt2).mapEndpoints(endpoint => endpoint.plus({ hours: 2 }))
The Info class contains static methods for retrieving general time and date related data. For example, it has methods for finding out if a time zone has a DST, for listing the months in any supported locale, and for discovering which of Luxon features are available in the current environment.
Converts the input into a Zone instance.
input is already a Zone instance, it is returned unchanged.input is a string containing a valid time zone name, a Zone instance
with that name is returned.input is a string that doesn't refer to a known time zone, a Zone
instance with Zone#isValid == false is returned.input is null or undefined, the default zone is returned.Zone:
Get the weekday on which the week starts according to the given locale.
number:
the start of the week, 1 for Monday through 7 for Sunday
Get the minimum number of days necessary in a week before it is considered part of the next year according to the given locale.
number:
Return an array of standalone month names.
(string
= 'long')
the length of the month representation, such as "numeric", "2-digit", "narrow", "short", "long"
Array:
Info.months()[0] //=> 'January'
Info.months('short')[0] //=> 'Jan'
Info.months('numeric')[0] //=> '1'
Info.months('short', { locale: 'fr-CA' } )[0] //=> 'janv.'
Info.months('numeric', { locale: 'ar' })[0] //=> '١'
Info.months('long', { outputCalendar: 'islamic' })[0] //=> 'Rabiʻ I'
Return an array of format month names. Format months differ from standalone months in that they're meant to appear next to the day of the month. In some languages, that changes the string. See Info#months
(string
= 'long')
the length of the month representation, such as "numeric", "2-digit", "narrow", "short", "long"
Array:
Return an array of standalone week names.
(string
= 'long')
the length of the weekday representation, such as "narrow", "short", "long".
Array:
Info.weekdays()[0] //=> 'Monday'
Info.weekdays('short')[0] //=> 'Mon'
Info.weekdays('short', { locale: 'fr-CA' })[0] //=> 'lun.'
Info.weekdays('short', { locale: 'ar' })[0] //=> 'الاثنين'
Return an array of format week names. Format weekdays differ from standalone weekdays in that they're meant to appear next to more date information. In some languages, that changes the string. See Info#weekdays
(string
= 'long')
the length of the month representation, such as "narrow", "short", "long".
Array:
Return an array of eras, such as ['BC', 'AD']. The locale can be specified, but the calendar system is always Gregorian.
(string
= 'short')
the length of the era representation, such as "short" or "long".
Array:
Info.eras() //=> [ 'BC', 'AD' ]
Info.eras('long') //=> [ 'Before Christ', 'Anno Domini' ]
Info.eras('long', { locale: 'fr' }) //=> [ 'avant Jésus-Christ', 'après Jésus-Christ' ]
Return the set of available features in this environment. Some features of Luxon are not available in all environments. For example, on older browsers, relative time formatting support is not available. Use this function to figure out if that's the case. Keys:
relative: whether this environment supports relative time formattinglocaleWeek: whether this environment supports different weekdays for the start of the week based on the localeObject:
Info.features() //=> { relative: false, localeWeek: true }
The IANA name of this zone.
Defaults to name if not overwritten by a subclass.
Type: string
Returns whether the offset is known to be fixed for the whole year.
Type: boolean
A zone with a fixed offset (meaning no DST)
Extends Zone
(any)
Get a singleton instance of UTC
FixedOffsetZone:
Get an instance with a specified offset
(number)
The offset in minutes
FixedOffsetZone:
Get an instance of FixedOffsetZone from a UTC offset string, like "UTC+6"
(string)
The offset string to parse
FixedOffsetZone:
FixedOffsetZone.parseSpecifier("UTC+6")
FixedOffsetZone.parseSpecifier("UTC+06")
FixedOffsetZone.parseSpecifier("UTC-6:00")
The name of this zone. All fixed zones' names always start with "UTC" (plus optional offset)
Type: string
Returns the offset's common name at the specified timestamp.
For fixed offset zones this equals to the zone name.
Returns whether the offset is known to be fixed for the whole year: Always returns true for all fixed offset zones.
Type: boolean
A zone identified by an IANA identifier, like America/New_York
Extends Zone
(any)
Reset local caches. Should only be necessary in testing scenarios.
void:
Returns whether the provided string is a valid specifier. This only checks the string's format, not that the specifier identifies a known zone; see isValidZone for that.
isValidZone()
directly instead.
(string)
The string to check validity on
boolean:
IANAZone.isValidSpecifier("America/New_York") //=> true
IANAZone.isValidSpecifier("Sport~~blorp") //=> false
Returns whether the offset is known to be fixed for the whole year: Always returns false for all IANA zones.
Type: boolean
A zone that failed to parse. You should never need to instantiate this.
Extends Zone
(any)
Represents the local zone for this JavaScript environment.
Extends Zone
Get a singleton instance of the local zone
SystemZone:
(any)
(any)
(any)
(any)
Settings contains static getters and setters that control Luxon's overall behavior. Luxon is a simple library with few options, but the ones it does have live here.
Set the callback for returning the current timestamp. The function should return a number, which will be interpreted as an Epoch millisecond count
Type: function
(any)
Settings.now = () => Date.now() + 3000 // pretend it is 3 seconds in the future
Settings.now = () => 0 // always pretend it's Jan 1, 1970 at midnight in UTC time
Set the default time zone to create DateTimes in. Does not affect existing instances. Use the value "system" to reset this value to the system's time zone.
Type: string
(any)
Get the default time zone object currently used to create DateTimes. Does not affect existing instances. The default value is the system's time zone (the one set on the machine that runs this code).
Type: Zone
Get the default locale to create DateTimes with. Does not affect existing instances.
Type: string
Set the default locale to create DateTimes with. Does not affect existing instances.
Type: string
(any)
Get the default numbering system to create DateTimes with. Does not affect existing instances.
Type: string
Set the default numbering system to create DateTimes with. Does not affect existing instances.
Type: string
(any)
Get the default output calendar to create DateTimes with. Does not affect existing instances.
Type: string
Set the default output calendar to create DateTimes with. Does not affect existing instances.
Type: string
(any)
(WeekSettings | null):
Allows overriding the default locale week settings, i.e. the start of the week, the weekend and how many days are required in the first week of a year. Does not affect existing instances.
((WeekSettings | null))
Get the cutoff year for whether a 2-digit year string is interpreted in the current or previous century. Numbers higher than the cutoff will be considered to mean 19xx and numbers lower or equal to the cutoff will be considered 20xx.
Type: number
Set the cutoff year for whether a 2-digit year string is interpreted in the current or previous century. Numbers higher than the cutoff will be considered to mean 19xx and numbers lower or equal to the cutoff will be considered 20xx.
Type: number
(any)
Settings.twoDigitCutoffYear = 0 // all 'yy' are interpreted as 20th century
Settings.twoDigitCutoffYear = 99 // all 'yy' are interpreted as 21st century
Settings.twoDigitCutoffYear = 50 // '49' -> 2049; '50' -> 1950
Settings.twoDigitCutoffYear = 1950 // interpreted as 50
Settings.twoDigitCutoffYear = 2050 // ALSO interpreted as 50
Get whether Luxon will throw when it encounters invalid DateTimes, Durations, or Intervals
Type: boolean
Set whether Luxon will throw when it encounters invalid DateTimes, Durations, or Intervals
Type: boolean
(any)
Reset Luxon's global caches. Should only be necessary in testing scenarios.
void:
Type: Object