DateTime

Show Deprecated

The DateTime data type represents a moment in time using a Unix timestamp. It can be used to easily format dates and times in specific locales. When converted to a string, a string conversion of the stored timestamp integer is returned. They don't store timezone values. Instead, timezones are considered when constructing and using DateTime objects.

DateTime objects are equal if and only if their UnixTimestampMillis properties are equal.

Time Value Table

The ToUniversalTime() and ToLocalTime() methods return a table of time-related values, such as Year, Month, and Day. The format of the table returned by these functions is described below, with each integer element in descending size order.

Name	Range	Notes
Year	1400–9999	—
Month	1–12	—
Day	1–31	—
Hour	0–23	—
Minute	0–59	—
Second	0–60	Usually 0–59, sometimes 60 to accommodate leap seconds in certain systems.
Millisecond	0–999	—

String Format

The DateTime object supports date/time conversion into a string through the FormatUniversalTime() and FormatLocalTime() methods. They both work the same except for which timezone the DateTime should be interpreted in.

The first argument passed to these methods must be a string representing one of the tokens shown below. The tokens are then replaced with a specific value depending on the provided locale.


local dt = DateTime.now()

-- The "dddd" token is replaced with the full day of the week
print("Today is " .. dt:FormatLocalTime("dddd", "en-us"))

-- For the "en-us" locale, the "LL" token equals "MMMM D, YYYY"
print("The date is " .. dt:FormatLocalTime("LL", "en-us"))

Composite Tokens

Depending on locale, these tokens replace to specific combinations of the elemental tokens described in the next section. This produces a correct date/time string depending on the locale. For example, in English, the date has the "[month] [day]" as in "June 11". In French, the date is in a "[day] [month]" format as in "11 juin". These special rules are handled for you automatically through the following composite tokens, so use these if you're displaying simple time and/or date information.

Token(s)	Locale Examples (Format)
Time
LT	en-us : 8:30 PM (h:mm A) zh-cn : 20:30 (HH:mm)
Time with Seconds
LTS	en-us : 8:30:25 PM (h:mm:ss A) zh-cn : 20:30:25 (HH:mm:ss)
Month (Number), Day, Year
L	en-us : 09/04/1986 (MM/DD/YYYY) zh-cn : 1986/09/04 (YYYY/MM/DD)
l	en-us : 9/4/1986 (M/D/YYYY) zh-cn : 1986/9/4 (YYYY/M/D)
Month (Name), Day, Year
LL	en-us : September 4, 1986 (MMMM D, YYYY) zh-cn : 1986年9月4日 (YYYY年M月D日)
ll	en-us : Sep 4, 1986 (MMM D, YYYY) zh-cn : 1986年9月4日 (YYYY年M月D日)
Month (Name), Day, Year, Time
LLL	en-us : September 4, 1986 8:30 PM (MMMM D, YYYY h:mm A) zh-cn : 1986年9月4日晚上8点30分 (YYYY年M月D日Ah点mm分)
lll	en-us : Sep 4, 1986 8:30 PM (MMM D, YYYY h:mm A) zh-cn : 1986年9月4日 20:30 (YYYY年M月D日 HH:mm)
Day of Week, Month (Name), Day, Year, Time
LLLL	en-us : Thursday, September 4, 1986 8:30 PM (dddd, MMMM D, YYYY h:mm A) zh-cn : 1986年9月4日星期四晚上8点30分 (YYYY年M月D日ddddAh点mm分)
llll	en-us : Thu, Sep 4, 1986 8:30 PM (ddd, MMM D, YYYY h:mm A) zh-cn : 1986年9月4日星期四 20:30 (YYYY年M月D日dddd HH:mm)

Elemental Tokens

Each of these tokens replace to a single value and can be used as elements of a larger time string. Avoid using these if you only need simple date and time information, as the composite tokens are more appropriate for those purposes.

Token(s)	Examples
Year
YY	70, 71, …, 29, 30
YYYY	1970, 1971, …, 2029, 2030
Month
M	1, 2, …, 11, 12
MM	01, 02, …, 11, 12
MMM	Jan, Feb, …, Nov, Dec
MMMM	January, February, …, November, December
Day of Month
D	1, 2, …, 30, 31
DD	01, 02, …, 30, 31
Day of Year
DDD	1, 2, …, 364, 365
DDDD	001, 002, …, 364, 365
Day of Week
d	0, 1, …, 5, 6
dd	Su, Mo, …, Fr, Sa
ddd	Sun, Mon, …, Fri, Sat
dddd	Sunday, Monday, …, Friday, Saturday
Hour
H	0, 1, …, 22, 23
HH	00, 01, …, 22, 23
h	1, 2, …, 11, 12
hh	01, 02, …, 11, 12
Minute
m	0, 1, …, 58, 59
mm	00, 01, …, 58, 59
Second
s	0, 1, …, 58, 59
ss	00, 01, …, 58, 59
Fractional Second
S	0, 1, …, 8, 9
SS	00, 01, …, 98, 99
SSS	000, 001, …, 998, 999
AM/PM
A	en-us : AM, PM zh-cn : 凌晨\|早上\|上午\|中午\|下午\|晚上
a	en-us : am, pm zh-cn : 凌晨\|早上\|上午\|中午\|下午\|晚上

Summary

Constructors

now()

fromUnixTimestamp(unixTimestamp: number)

fromUnixTimestampMillis(unixTimestampMillis: number)

fromUniversalTime(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number)

fromLocalTime(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number)

fromIsoDate(isoDate: string)

Properties

UnixTimestamp: number

The number of seconds between January 1st, 1970 at 00:00 UTC (the Unix epoch).

UnixTimestampMillis: number

The number of milliseconds between January 1st, 1970 at 00:00 UTC (the Unix epoch).

Methods

ToUniversalTime(): table

Returns the components of the DateTime in UTC.

ToLocalTime(): table

Returns the components of the DateTime in local time.

ToIsoDate(): string

Returns the DateTime as an ISO 8601 date-time string.

FormatUniversalTime(format: string, locale: string): string

Returns the DateTime's value in UTC formatted into a string.

FormatLocalTime(format: string, locale: string): string

Returns the DateTime object's value in local time formatted into a string.

Constructors

now

fromUnixTimestamp

Parameters

unixTimestamp: number

fromUnixTimestampMillis

Parameters

unixTimestampMillis: number

fromUniversalTime

Parameters

year: number

Default Value: 1970

month: number

Default Value: 1

day: number

Default Value: 1

hour: number

Default Value: 0

minute: number

Default Value: 0

second: number

Default Value: 0

millisecond: number

Default Value: 0

fromLocalTime

Parameters

year: number

Default Value: 1970

month: number

Default Value: 1

day: number

Default Value: 1

hour: number

Default Value: 0

minute: number

Default Value: 0

second: number

Default Value: 0

millisecond: number

Default Value: 0

fromIsoDate

Parameters

isoDate: string

Properties

UnixTimestamp

number

The number of seconds since January 1st, 1970 at 00:00 UTC (the Unix epoch). Range is -17,987,443,200 to 253,402,300,799, approximately years 1400–9999.

UnixTimestampMillis

number

The number of milliseconds since January 1st, 1970 at 00:00 UTC (the Unix epoch). Range is -17,987,443,200,000 to 253,402,300,799,999, approximately years 1400–9999.

Methods

ToUniversalTime

table

Converts the value of this DateTime object to Universal Coordinated Time (UTC). The returned table contains the following keys: Year, Month, Day, Hour, Minute, Second, Millisecond. For more details, see the time value table in this data type's description. The values within this table could be passed to fromUniversalTime() to produce the original DateTime object.

Returns

table

ToLocalTime

table

Converts the value of this DateTime object to local time. The returned table contains the following keys: Year, Month, Day, Hour, Minute, Second, Millisecond. For more details, see the time value table in this data type's description. The values within this table could be passed to fromLocalTime() to produce the original DateTime object.

Returns

table

ToIsoDate

string

Formats a date as a ISO 8601 date-time string. The value returned by this function could be passed to fromIsoDate() to produce the original DateTime object.

An example ISO 8601 date-time string would be 2020-01-02T10:30:45Z, which represents January 2nd 2020 at 10:30 AM, 45 seconds.

Returns

string

FormatUniversalTime

string

Generates a string from the DateTime value interpreted as Universal Coordinated Time (UTC) and a format string. The format string should contain tokens, which will replace to certain date/time values described by the DateTime object. For more details, see the String Format section in this data type's description.


local dt = DateTime.now()
-- For en-us, the "LL" token equals "MMM D, YYYY", which gives "June 11, 2020"
print("The date is " .. dt:FormatUniversalTime("LL", "en-us"))
--> "The date is June 11, 2020"

Parameters

format: string

locale: string

Returns

string

FormatLocalTime

string

Generates a string from the DateTime value interpreted as local time and a format string. The format string should contain tokens, which will replace to certain date/time values described by the DateTime object. For more details, see the String Format section in this data type's description.


local dt = DateTime.now()
-- For en-us, the "LL" token equals "MMM D, YYYY", which gives "June 11, 2020"
print("The date is " .. dt:FormatLocalTime("LL", "en-us"))
--> "The date is June 11, 2020"

Parameters

format: string

locale: string

Returns

string