DateTime
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:
- A timestamp. Each DateTime instance refers to a specific millisecond of the Unix epoch.
- A time zone. Each instance is considered in the context of a specific zone (by default the local system's zone).
- Configuration properties that effect how output strings are formatted, such as
locale
,numberingSystem
, andoutputCalendar
.
Here is a brief overview of the most commonly used functionality it provides:
- Creation: To create a DateTime from its components, use one of its factory class methods: local, utc, and (most flexibly) fromObject. To create one from a standard string format, use fromISO, fromHTTP, and fromRFC2822. To create one from a custom string format, use fromString. To create one from a native JS date, use fromJSDate.
- Gregorian calendar and time: To examine the Gregorian properties of a DateTime individually (i.e as opposed to collectively through toObject), use the year, month, day, hour, minute, second, millisecond accessors.
- Week calendar: For ISO week calendar attributes, see the weekYear, weekNumber, and weekday accessors.
- Configuration See the locale and numberingSystem accessors.
- Transformation: To transform the DateTime into other DateTimes, use set, reconfigure, setZone, setLocale, plus, minus, endOf, startOf, toUTC, and toLocal.
- Output: To convert the DateTime to other representations, use the toJSON, toISO, toHTTP, toObject, toRFC2822, toString, toLocaleString, toFormat, and valueOf.
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.
Static Member Summary
Static Public Members | ||
public static get |
DATETIME_FULL: {"year": string, "month": string, "day": string, "hour": string, "minute": string, "timeZoneName": string} toLocaleString format like 'October 14, 1983, 9:30 AM EDT'. |
|
public static get |
DATETIME_FULL_WITH_SECONDS: {"year": string, "month": string, "day": string, "hour": string, "minute": string, "second": string, "timeZoneName": string} toLocaleString format like 'October 14, 1983, 9:303 AM EDT'. |
|
public static get |
DATETIME_HUGE: {"year": string, "month": string, "day": string, "weekday": string, "hour": string, "minute": string, "timeZoneName": string} toLocaleString format like 'Friday, October 14, 1983, 9:30 AM Eastern Daylight Time'. |
|
public static get |
DATETIME_HUGE_WITH_SECONDS: {"year": string, "month": string, "day": string, "weekday": string, "hour": string, "minute": string, "second": string, "timeZoneName": string} toLocaleString format like 'Friday, October 14, 1983, 9:30:33 AM Eastern Daylight Time'. |
|
public static get |
toLocaleString format like 'Oct 14, 1983, 9:30 AM'. |
|
public static get |
DATETIME_MED_WITH_SECONDS: {"year": string, "month": string, "day": string, "hour": string, "minute": string, "second": string} toLocaleString format like 'Oct 14, 1983, 9:30:33 AM'. |
|
public static get |
toLocaleString format like '10/14/1983, 9:30 AM'. |
|
public static get |
DATETIME_SHORT_WITH_SECONDS: {"year": string, "month": string, "day": string, "hour": string, "minute": string, "second": string} toLocaleString format like '10/14/1983, 9:30:33 AM'. |
|
public static get |
toLocaleString format like 'October 14, 1983' |
|
public static get |
toLocaleString format like 'Tuesday, October 14, 1983' |
|
public static get |
toLocaleString format like 'Oct 14, 1983' |
|
public static get |
DATE_SHORT: {"year": string, "month": string, "day": string} toLocaleString format like 10/14/1983 |
|
public static get |
TIME_24_SIMPLE: {"hour": string, "minute": string, "hour12": *} toLocaleString format like '09:30', always 24-hour. |
|
public static get |
TIME_24_WITH_LONG_OFFSET: {"hour": string, "minute": string, "second": string, "hour12": *, "timeZoneName": string} toLocaleString format like '09:30:23 Eastern Daylight Time', always 24-hour. |
|
public static get |
TIME_24_WITH_SECONDS: {"hour": string, "minute": string, "second": string, "hour12": *} toLocaleString format like '09:30:23', always 24-hour. |
|
public static get |
TIME_24_WITH_SHORT_OFFSET: {"hour": string, "minute": string, "second": string, "hour12": *, "timeZoneName": string} toLocaleString format like '09:30:23 EDT', always 24-hour. |
|
public static get |
TIME_SIMPLE: {"hour": string, "minute": string} toLocaleString format like '09:30 AM'. |
|
public static get |
TIME_WITH_LONG_OFFSET: {"hour": string, "minute": string, "second": string, "timeZoneName": string} toLocaleString format like '09:30:23 AM Eastern Daylight Time'. |
|
public static get |
TIME_WITH_SECONDS: {"hour": string, "minute": string, "second": string} toLocaleString format like '09:30:23 AM'. |
|
public static get |
TIME_WITH_SHORT_OFFSET: {"hour": string, "minute": string, "second": string, "timeZoneName": string} toLocaleString format like '09:30:23 AM EDT'. |
Static Method Summary
Static Public Methods | ||
public static |
Create a DateTime from an HTTP header date |
|
public static |
Create a DateTime from an ISO 8601 string |
|
public static |
fromJSDate(date: Date, options: Object): DateTime Create an DateTime from a Javascript Date object. |
|
public static |
fromMillis(milliseconds: number, options: Object): DateTime Create an DateTime from a count of epoch milliseconds. |
|
public static |
fromObject(obj: Object): DateTime Create an DateTime from a Javascript object with keys like 'year' and 'hour' with reasonable defaults. |
|
public static |
fromRFC2822(text: string, opts: Object): DateTime Create a DateTime from an RFC 2822 string |
|
public static |
fromString(text: string, fmt: string, options: Object): DateTime Create a DateTime from an input string and format string |
|
public static |
fromStringExplain(text: string, fmt: string, options: object): object Explain how a string would be parsed by fromString() |
|
public static |
Create an invalid DateTime. |
|
public static |
local(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime Create a local DateTime |
|
public static |
Return the max of several date times |
|
public static |
Return the min of several date times |
|
public static |
utc(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime Create a DateTime in UTC |
Member Summary
Public Members | ||
public get |
Get the day of the month (1-30ish). |
|
public get |
daysInMonth: number: * Returns the number of days in this DateTime's month |
|
public get |
daysInYear: number: * Returns the number of days in this DateTime's year |
|
public get |
Get the hour of the day (0-23). |
|
public get |
invalidReason: string: * Returns an explanation of why this DateTime became invalid, or null if the DateTime is valid |
|
public get |
Get whether the DateTime is in a DST. |
|
public get |
isInLeapYear: boolean: * Returns true if this DateTime is in a leap year, false otherwise |
|
public get |
isOffsetFixed: boolean: * Get whether this zone's offset ever changes, as in a DST. |
|
public get |
Returns whether the DateTime is valid. |
|
public get |
Get the locale of a DateTime, such 'en-GB'. |
|
public get |
millisecond: number: * Get the millisecond of the second (0-999). |
|
public get |
Get the minute of the hour (0-59). |
|
public get |
Get the month (1-12). |
|
public get |
Get the numbering system of a DateTime, such 'beng'. |
|
public get |
Get the UTC offset of this DateTime in minutes |
|
public get |
offsetNameLong: String: * Get the long human name for the zone's current offset, for example "Eastern Standard Time" or "Eastern Daylight Time". Is locale-aware. |
|
public get |
Get the short human name for the zone's current offset, for example "EST" or "EDT". |
|
public get |
Get the ordinal (i.e. |
|
public get |
outputCalendar: string: * Get the output calendar of a DateTime, such 'islamic'. |
|
public get |
Get the second of the minute (0-59). |
|
public get |
weekNumber: number: * Get the week number of the week year (1-52ish). |
|
public get |
Get the week year |
|
public get |
Get the day of the week. |
|
public get |
Get the year |
|
public get |
Get the name of the time zone. |
Method Summary
Public Methods | ||
public |
Return the difference between two DateTimes as a Duration. |
|
public |
Return the difference between this DateTime and right now. |
|
public |
"Set" this DateTime to the end (i.e. |
|
public |
Equality check Two DateTimes are equal iff they represent the same millisecond |
|
public |
Get the value of unit. |
|
public |
Return whether this DateTime is in the same unit of time as another DateTime |
|
public |
Subtract a period of time to this DateTime and return the resulting DateTime See plus |
|
public |
Add a period of time to this DateTime and return the resulting DateTime |
|
public |
reconfigure(properties: object): DateTime "Set" the locale, numberingSystem, or outputCalendar. |
|
public |
resolvedLocaleOpts(opts: object): object Returns the resolved Intl options for this DateTime. |
|
public |
"Set" the values of specified units. |
|
public |
"Set" the locale. |
|
public |
"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 UTC timestamp), but the new instance will report different local times and consider DSTs when making computations, as with plus. You may wish to use toLocal and toUTC which provide simple convenience wrappers for commonly used zones. |
|
public |
"Set" this DateTime to the beginning of a unit of time. |
|
public |
Returns a string representation of this DateTime formatted according to the specified format string. |
|
public |
Returns a string representation of this DateTime appropriate for use in HTTP headers. |
|
public |
Returns an ISO 8601-compliant string representation of this DateTime |
|
public |
Returns an ISO 8601-compliant string representation of this DateTime's date component |
|
public |
Returns an ISO 8601-compliant string representation of this DateTime's time component |
|
public |
Returns an ISO 8601-compliant string representation of this DateTime's week date |
|
public |
Returns a Javascript Date equivalent to this DateTime. |
|
public |
Returns an ISO 8601 representation of this DateTime appropriate for use in JSON. |
|
public |
"Set" the DateTime's zone to the host's local zone. |
|
public |
toLocaleParts(opts: *): * Returns an array of format "parts", i.e. |
|
public |
toLocaleString(opts: *): string Returns a localized string representing this date. |
|
public |
Returns a Javascript object with this DateTime's year, month, day, and so on. |
|
public |
Returns an RFC 2822-compatible string representation of this DateTime, always in UTC |
|
public |
Returns a string representation of this DateTime appropriate for debugging |
|
public |
"Set" the DateTime's zone to UTC. Returns a newly-constructed DateTime. Equivalent to setZone('utc') |
|
public |
Return an Interval spanning between this DateTime and another DateTime |
|
public |
Returns the epoch milliseconds of this DateTime |
Static Public Members
public static get DATETIME_FULL: {"year": string, "month": string, "day": string, "hour": string, "minute": string, "timeZoneName": string} source
toLocaleString format like 'October 14, 1983, 9:30 AM EDT'. Only 12-hour if the locale is.
public static get DATETIME_FULL_WITH_SECONDS: {"year": string, "month": string, "day": string, "hour": string, "minute": string, "second": string, "timeZoneName": string} source
toLocaleString format like 'October 14, 1983, 9:303 AM EDT'. Only 12-hour if the locale is.
public static get DATETIME_HUGE: {"year": string, "month": string, "day": string, "weekday": string, "hour": string, "minute": string, "timeZoneName": string} source
toLocaleString format like 'Friday, October 14, 1983, 9:30 AM Eastern Daylight Time'. Only 12-hour if the locale is.
public static get DATETIME_HUGE_WITH_SECONDS: {"year": string, "month": string, "day": string, "weekday": string, "hour": string, "minute": string, "second": string, "timeZoneName": string} source
toLocaleString format like 'Friday, October 14, 1983, 9:30:33 AM Eastern Daylight Time'. Only 12-hour if the locale is.
public static get DATETIME_MED: {"year": string, "month": string, "day": string, "hour": string, "minute": string} source
toLocaleString format like 'Oct 14, 1983, 9:30 AM'. Only 12-hour if the locale is.
public static get DATETIME_MED_WITH_SECONDS: {"year": string, "month": string, "day": string, "hour": string, "minute": string, "second": string} source
toLocaleString format like 'Oct 14, 1983, 9:30:33 AM'. Only 12-hour if the locale is.
public static get DATETIME_SHORT: {"year": string, "month": string, "day": string, "hour": string, "minute": string} source
toLocaleString format like '10/14/1983, 9:30 AM'. Only 12-hour if the locale is.
public static get DATETIME_SHORT_WITH_SECONDS: {"year": string, "month": string, "day": string, "hour": string, "minute": string, "second": string} source
toLocaleString format like '10/14/1983, 9:30:33 AM'. Only 12-hour if the locale is.
public static get DATE_FULL: {"year": string, "month": string, "day": string} source
toLocaleString format like 'October 14, 1983'
public static get DATE_HUGE: {"year": string, "month": string, "day": string, "weekday": string} source
toLocaleString format like 'Tuesday, October 14, 1983'
public static get DATE_MED: {"year": string, "month": string, "day": string} source
toLocaleString format like 'Oct 14, 1983'
public static get DATE_SHORT: {"year": string, "month": string, "day": string} source
toLocaleString format like 10/14/1983
public static get TIME_24_SIMPLE: {"hour": string, "minute": string, "hour12": *} source
toLocaleString format like '09:30', always 24-hour.
public static get TIME_24_WITH_LONG_OFFSET: {"hour": string, "minute": string, "second": string, "hour12": *, "timeZoneName": string} source
toLocaleString format like '09:30:23 Eastern Daylight Time', always 24-hour.
public static get TIME_24_WITH_SECONDS: {"hour": string, "minute": string, "second": string, "hour12": *} source
toLocaleString format like '09:30:23', always 24-hour.
public static get TIME_24_WITH_SHORT_OFFSET: {"hour": string, "minute": string, "second": string, "hour12": *, "timeZoneName": string} source
toLocaleString format like '09:30:23 EDT', always 24-hour.
public static get TIME_SIMPLE: {"hour": string, "minute": string} source
toLocaleString format like '09:30 AM'. Only 12-hour if the locale is.
public static get TIME_WITH_LONG_OFFSET: {"hour": string, "minute": string, "second": string, "timeZoneName": string} source
toLocaleString format like '09:30:23 AM Eastern Daylight Time'. Only 12-hour if the locale is.
public static get TIME_WITH_SECONDS: {"hour": string, "minute": string, "second": string} source
toLocaleString format like '09:30:23 AM'. Only 12-hour if the locale is.
Static Public Methods
public static fromHTTP(text: string, options: object): DateTime source
Create a DateTime from an HTTP header date
Params:
Name | Type | Attribute | Description |
text | string | the HTTP header date |
|
options | object | options to affect the creation |
|
options.zone | boolean |
|
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. |
options.setZone | boolean |
|
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 |
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 |
Example:
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')
public static fromISO(text: string, opts: Object): DateTime source
Create a DateTime from an ISO 8601 string
Params:
Name | Type | Attribute | Description |
text | string | the ISO string |
|
opts | Object | options to affect the creation |
|
opts.zone | boolean |
|
use this zone if no offset is specified in the input string itself. Will also convert the time to this zone |
opts.setZone | boolean |
|
override the zone with a fixed-offset zone specified in the string itself, if it specifies one |
opts.locale | string |
|
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 |
Example:
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')
public static fromJSDate(date: Date, options: Object): DateTime source
Create an DateTime from a Javascript Date object. Uses the default zone.
public static fromMillis(milliseconds: number, options: Object): DateTime source
Create an DateTime from a count of epoch milliseconds. Uses the default zone.
Params:
Name | Type | Attribute | Description |
milliseconds | number | a number of milliseconds since 1970 UTC |
|
options | Object | configuration options for the DateTime |
|
options.zone | string | Zone |
|
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 |
public static fromObject(obj: Object): DateTime source
Create an DateTime from a Javascript object with keys like 'year' and 'hour' with reasonable defaults.
Params:
Name | Type | Attribute | Description |
obj | Object | the object to create the DateTime from |
|
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.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 |
|
obj.zone | string | Zone |
|
interpret the numbers in the context of a particular zone. Can take any value taken as the first argument to setZone() |
obj.locale | string |
|
a locale to set on the resulting DateTime instance |
obj.outputCalendar | string | the output calendar to set on the resulting DateTime instance |
|
obj.numberingSystem | string | the numbering system to set on the resulting DateTime instance |
Example:
DateTime.fromObject({ year: 1982, month: 5, day: 25}).toISODate() //=> '1982-05-25'
DateTime.fromObject({ year: 1982 }).toISODate() //=> '1982-01-01T00'
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'
public static fromRFC2822(text: string, opts: Object): DateTime source
Create a DateTime from an RFC 2822 string
Params:
Name | Type | Attribute | Description |
text | string | the RFC 2822 string |
|
opts | Object | options to affect the creation |
|
opts.zone | boolean |
|
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 |
|
override the zone with a fixed-offset zone specified in the string itself, if it specifies one |
opts.locale | string |
|
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 |
Example:
DateTime.fromRFC2822('25 Nov 2016 13:23:12 GMT')
DateTime.fromRFC2822('Tue, 25 Nov 2016 13:23:12 +0600')
DateTime.fromRFC2822('25 Nov 2016 13:23 Z')
public static fromString(text: string, fmt: string, options: Object): DateTime source
Create a DateTime from an input string and format string
Params:
Name | Type | Attribute | Description |
text | string | the string to parse |
|
fmt | string | the format the string is expected to be in (see description) |
|
options | Object | options to affect the creation |
|
options.zone | boolean |
|
use this zone if no offset is specified in the input string itself. Will also convert the DateTime to this zone |
options.setZone | boolean |
|
override the zone with a zone specified in the string itself, if it specifies one |
options.locale | string |
|
a locale string to use when parsing. Will also set the DateTime to this locale |
options.numberingSystem | string | the numbering system to use when parsing. Will also set the resulting DateTime to this numbering system |
|
options.outputCalendar | string | the output calendar to set on the resulting DateTime instance |
public static fromStringExplain(text: string, fmt: string, options: object): object source
Explain how a string would be parsed by fromString()
public static invalid(reason: *): DateTime source
Create an invalid DateTime.
Params:
Name | Type | Attribute | Description |
reason | * |
public static local(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime source
Create a local DateTime
Params:
Name | Type | Attribute | Description |
year | number | The calendar year. If omitted (as in, call |
|
month | number |
|
The month, 1-indexed |
day | number |
|
The day of the month |
hour | number |
|
The hour of the day, in 24-hour time |
minute | number |
|
The minute of the hour, i.e. a number between 0 and 59 |
second | number |
|
The second of the minute, i.e. a number between 0 and 59 |
millisecond | number |
|
The millisecond of the second, i.e. a number between 0 and 999 |
Example:
DateTime.local() //~> now
DateTime.local(2017) //~> 2017-01-01T00:00:00
DateTime.local(2017, 3) //~> 2017-03-01T00:00:00
DateTime.local(2017, 3, 12) //~> 2017-03-12T00:00:00
DateTime.local(2017, 3, 12, 5) //~> 2017-03-12T05:00:00
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.675
public static max(dateTimes: ...DateTime): DateTime source
Return the max of several date times
Params:
Name | Type | Attribute | Description |
dateTimes | ...DateTime | the DateTimes from which to choose the maximum |
public static min(dateTimes: ...DateTime): DateTime source
Return the min of several date times
Params:
Name | Type | Attribute | Description |
dateTimes | ...DateTime | the DateTimes from which to choose the minimum |
public static utc(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime source
Create a DateTime in UTC
Params:
Name | Type | Attribute | Description |
year | number | The calendar year. If omitted (as in, call |
|
month | number |
|
The month, 1-indexed |
day | number |
|
The day of the month |
hour | number |
|
The hour of the day, in 24-hour time |
minute | number |
|
The minute of the hour, i.e. a number between 0 and 59 |
second | number |
|
The second of the minute, i.e. a number between 0 and 59 |
millisecond | number |
|
The millisecond of the second, i.e. a number between 0 and 999 |
Example:
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, 10) //~> 2017-03-12T05:45:10Z
DateTime.utc(2017, 3, 12, 5, 45, 10, 765) //~> 2017-03-12T05:45:10.675Z
Public Members
public get day: number: * source
Get the day of the month (1-30ish).
Example:
DateTime.local(2017, 5, 25).day //=> 25
public get daysInMonth: number: * source
Returns the number of days in this DateTime's month
Example:
DateTime.local(2016, 2).daysInMonth //=> 29
DateTime.local(2016, 3).days //=> 31
public get daysInYear: number: * source
Returns the number of days in this DateTime's year
Example:
DateTime.local(2016).daysInYear //=> 366
DateTime.local(2013).daysInYear //=> 365
public get hour: number: * source
Get the hour of the day (0-23).
Example:
DateTime.local(2017, 5, 25, 9).hour //=> 9
public get invalidReason: string: * source
Returns an explanation of why this DateTime became invalid, or null if the DateTime is valid
public get isInLeapYear: boolean: * source
Returns true if this DateTime is in a leap year, false otherwise
Example:
DateTime.local(2016).isInLeapYear //=> true
DateTime.local(2013).isInLeapYear //=> false
public get isOffsetFixed: boolean: * source
Get whether this zone's offset ever changes, as in a DST.
public get isValid: boolean: * source
Returns whether the DateTime is valid. Invalid DateTimes occur when:
- The DateTime was created from invalid calendar information, such as the 13th month or February 30
- The DateTime was created by an operation on another invalid date
public get locale: string: * source
Get the locale of a DateTime, such 'en-GB'. The locale is used when formatting the DateTime
public get millisecond: number: * source
Get the millisecond of the second (0-999).
Example:
DateTime.local(2017, 5, 25, 9, 30, 52, 654).millisecond //=> 654
public get minute: number: * source
Get the minute of the hour (0-59).
Example:
DateTime.local(2017, 5, 25, 9, 30).minute //=> 30
public get month: number: * source
Get the month (1-12).
Example:
DateTime.local(2017, 5, 25).month //=> 5
public get numberingSystem: string: * source
Get the numbering system of a DateTime, such 'beng'. The numbering system is used when formatting the DateTime
public get offset: number: * source
Get the UTC offset of this DateTime in minutes
Example:
DateTime.local().offset //=> -240
DateTime.utc().offset //=> 0
public get offsetNameLong: String: * source
Get the long human name for the zone's current offset, for example "Eastern Standard Time" or "Eastern Daylight Time". Is locale-aware.
public get offsetNameShort: String: * source
Get the short human name for the zone's current offset, for example "EST" or "EDT".
public get ordinal: number | DateTime: * source
Get the ordinal (i.e. the day of the year)
Example:
DateTime.local(2017, 5, 25).ordinal //=> 145
public get outputCalendar: string: * source
Get the output calendar of a DateTime, such 'islamic'. The output calendar is used when formatting the DateTime
public get second: number: * source
Get the second of the minute (0-59).
Example:
DateTime.local(2017, 5, 25, 9, 30, 52).second //=> 52
public get weekNumber: number: * source
Get the week number of the week year (1-52ish).
Example:
DateTime.local(2017, 5, 25).weekNumber //=> 21
public get weekYear: number: * source
Get the week year
Example:
DateTime.local(2014, 11, 31).weekYear //=> 2015
public get weekday: number: * source
Get the day of the week. 1 is Monday and 7 is Sunday
Example:
DateTime.local(2014, 11, 31).weekday //=> 4
Public Methods
public diff(otherDateTime: DateTime, unit: string | string[], opts: Object): Duration source
Return the difference between two DateTimes as a Duration.
Params:
Name | Type | Attribute | Description |
otherDateTime | DateTime | the DateTime to compare this one to |
|
unit | string | string[] |
|
the unit or array of units (such as 'hours' or 'days') to include in the duration. |
opts | Object | options that affect the creation of the Duration |
|
opts.conversionAccuracy | string |
|
the conversion system to use |
Example:
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 }
public diffNow(unit: string | string[], opts: Object): Duration source
Return the difference between this DateTime and right now. See diff
Params:
Name | Type | Attribute | Description |
unit | string | string[] |
|
the unit or units units (such as 'hours' or 'days') to include in the duration |
opts | Object | options that affect the creation of the Duration |
|
opts.conversionAccuracy | string |
|
the conversion system to use |
public endOf(unit: string): DateTime source
"Set" this DateTime to the end (i.e. the last millisecond) of a unit of time
Params:
Name | Type | Attribute | Description |
unit | string | The unit to go to the end of. Can be 'year', 'month', 'day', 'hour', 'minute', 'second', or 'millisecond'. |
Example:
DateTime.local(2014, 3, 3).endOf('month').toISO(); //=> '2014-03-03T00:00:00.000-05:00'
DateTime.local(2014, 3, 3).endOf('year').toISO(); //=> '2014-12-31T23:59:59.999-05:00'
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'
public equals(other: DateTime): boolean source
Equality check Two DateTimes are equal iff they represent the same millisecond
Params:
Name | Type | Attribute | Description |
other | DateTime | the other DateTime |
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:
DateTime.local(2017, 7, 4).get('month'); //=> 7
DateTime.local(2017, 7, 4).get('day'); //=> 4
public hasSame(otherDateTime: DateTime, unit: string): boolean source
Return whether this DateTime is in the same unit of time as another DateTime
Example:
DateTime.local().hasSame(otherDT, 'day'); //~> true if both the same calendar day
public minus(duration: Duration | number | object): DateTime source
Subtract a period of time to this DateTime and return the resulting DateTime See plus
public plus(duration: Duration | number | object): DateTime source
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.
Example:
DateTime.local().plus(123) //~> in 123 milliseconds
DateTime.local().plus({ minutes: 15 }) //~> in 15 minutes
DateTime.local().plus({ days: 1 }) //~> this time tomorrow
DateTime.local().plus({ hours: 3, minutes: 13 }) //~> in 1 hr, 13 min
DateTime.local().plus(Duration.fromObject({ hours: 3, minutes: 13 })) //~> in 1 hr, 13 min
public reconfigure(properties: object): DateTime source
"Set" the locale, numberingSystem, or outputCalendar. Returns a newly-constructed DateTime.
Params:
Name | Type | Attribute | Description |
properties | object | the properties to set |
Example:
DateTime.local(2017, 5, 25).reconfigure({ locale: 'en-GB' })
public resolvedLocaleOpts(opts: object): object source
Returns the resolved Intl options for this DateTime. This is useful in understanding the behavior of parsing and formatting methods
Params:
Name | Type | Attribute | Description |
opts | object | the same options as toLocaleString |
public set(values: object): DateTime source
"Set" the values of specified units. Returns a newly-constructed DateTime.
Params:
Name | Type | Attribute | Description |
values | object | a mapping of units to numbers |
Example:
dt.set({ year: 2017 })
dt.set({ hour: 8, minute: 30 })
dt.set({ weekday: 5 })
dt.set({ year: 2005, ordinal: 234 })
dt.set({ outputCalendar: 'beng', zone: 'utc' })
public setLocale(locale: *): DateTime source
"Set" the locale. Returns a newly-constructed DateTime. Just a convenient alias for reconfigure({ locale })
Params:
Name | Type | Attribute | Description |
locale | * |
Example:
DateTime.local(2017, 5, 25).setLocale('en-GB')
public setZone(zone: string | Zone, opts: object): DateTime source
"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 UTC timestamp), but the new instance will report different local times and consider DSTs when making computations, as with plus. You may wish to use toLocal and toUTC which provide simple convenience wrappers for commonly used zones.
Params:
Name | Type | Attribute | Description |
zone | string | Zone |
|
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 Zone class. |
opts | object | options |
|
opts.keepCalendarTime | boolean |
|
If true, adjust the underlying time so that the local time stays the same, but in the target zone. You should rarely need this. |
public startOf(unit: string): DateTime source
"Set" this DateTime to the beginning of a unit of time.
Params:
Name | Type | Attribute | Description |
unit | string | The unit to go to the beginning of. Can be 'year', 'month', 'day', 'hour', 'minute', 'second', or 'millisecond'. |
Example:
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, 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'
public toFormat(fmt: string, opts: object): string source
Returns a string representation of this DateTime formatted according to the specified format string. You may not want this. See toLocaleString for a more flexible formatting tool. See the documentation for the specific format tokens supported.
Example:
DateTime.local().toFormat('yyyy LLL dd') //=> '2017 avr. 22'
DateTime.local().setLocale('fr').toFormat('yyyy LLL dd') //=> '2017 Apr 22'
DateTime.local().toFormat("HH 'hours and' mm 'minutes'") //=> '20 hours and 55 minutes'
public toHTTP(): string source
Returns a string representation of this DateTime appropriate for use in HTTP headers. Specifically, the string conforms to RFC 1123.
Example:
DateTime.utc(2014, 7, 13).toHTTP() //=> 'Sun, 13 Jul 2014 00:00:00 GMT'
public toISO(opts: object): string source
Returns an ISO 8601-compliant string representation of this DateTime
Example:
DateTime.utc(1982, 5, 25).toISO() //=> '1982-05-25T00:00:00.000Z'
DateTime.local().toISO() //=> '2017-04-22T20:47:05.335-04:00'
public toISODate(): string source
Returns an ISO 8601-compliant string representation of this DateTime's date component
Example:
DateTime.utc(1982, 5, 25).toISODate() //=> '07:34:19.361Z'
public toISOTime(opts: object): string source
Returns an ISO 8601-compliant string representation of this DateTime's time component
Example:
DateTime.utc().hour(7).minute(34).toISOTime() //=> '07:34:19.361Z'
DateTime.utc().hour(7).minute(34).toISOTime({ suppressSeconds: true }) //=> '07:34Z'
public toISOWeekDate(): string source
Returns an ISO 8601-compliant string representation of this DateTime's week date
Example:
DateTime.utc(1982, 5, 25).toISOWeekDate() //=> '1982-W21-2'
public toJSON(): string source
Returns an ISO 8601 representation of this DateTime appropriate for use in JSON.
public toLocal(): DateTime source
"Set" the DateTime's zone to the host's local zone. Returns a newly-constructed DateTime.
Equivalent to setZone('local')
public toLocaleParts(opts: *): * source
Returns an array of format "parts", i.e. individual tokens along with metadata. This is allows callers to post-process individual sections of the formatted output.
Params:
Name | Type | Attribute | Description |
opts | * | {object} - Intl.DateTimeFormat constructor options, same as |
Return:
* |
Example:
DateTime.local().toLocaleString(); //=> [
//=> { type: 'day', value: '25' },
//=> { type: 'literal', value: '/' },
//=> { type: 'month', value: '05' },
//=> { type: 'literal', value: '/' },
//=> { type: 'year', value: '1982' }
//=> ]
public toLocaleString(opts: *): string source
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.
Params:
Name | Type | Attribute | Description |
opts | * | {object} - Intl.DateTimeFormat constructor options |
Example:
DateTime.local().toLocaleString(); //=> 4/20/2017
DateTime.local().setLocale('en-gb').toLocaleString(); //=> '20/04/2017'
DateTime.local().toLocaleString(DateTime.DATE_FULL); //=> 'April 20, 2017'
DateTime.local().toLocaleString(DateTime.TIME_SIMPLE); //=> '11:32 AM'
DateTime.local().toLocaleString(DateTime.DATETIME_SHORT); //=> '4/20/2017, 11:32 AM'
DateTime.local().toLocaleString({weekday: 'long', month: 'long', day: '2-digit'}); //=> 'Thu, Apr 20'
DateTime.local().toLocaleString({weekday: 'long', month: 'long', day: '2-digit', hour: '2-digit', minute: '2-digit'}); //=> 'Thu, Apr 20, 11:27'
DateTime.local().toLocaleString({hour: '2-digit', minute: '2-digit'}); //=> '11:32'
public toObject(opts: *): object source
Returns a Javascript object with this DateTime's year, month, day, and so on.
Params:
Name | Type | Attribute | Description |
opts | * | options for generating the object |
|
opts.includeConfig | boolean |
|
include configuration attributes in the output |
Example:
DateTime.local().toObject() //=> { year: 2017, month: 4, day: 22, hour: 20, minute: 49, second: 42, millisecond: 268 }
public toRFC2822(): string source
Returns an RFC 2822-compatible string representation of this DateTime, always in UTC
Example:
DateTime.utc(2014, 7, 13).toRFC2822() //=> 'Sun, 13 Jul 2014 00:00:00 +0000'
DateTime.local(2014, 7, 13).toRFC2822() //=> 'Sun, 13 Jul 2014 00:00:00 -0400'
public toString(): string source
Returns a string representation of this DateTime appropriate for debugging
public toUTC(offset: number, opts: object): DateTime source
"Set" the DateTime's zone to UTC. Returns a newly-constructed DateTime.
Equivalent to setZone('utc')