Engine

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.

NameRangeNotes
Year1400–9999
Month1–12
Day1–31
Hour0–23
Minute0–59
Second0–60Usually 0–59, sometimes 60 to accommodate leap seconds in certain systems.
Millisecond0–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
YY70, 71, …, 29, 30
YYYY1970, 1971, …, 2029, 2030
Month
M1, 2, …, 11, 12
MM01, 02, …, 11, 12
MMMJan, Feb, …, Nov, Dec
MMMMJanuary, February, …, November, December
Day of Month
D1, 2, …, 30, 31
DD01, 02, …, 30, 31
Day of Year
DDD1, 2, …, 364, 365
DDDD001, 002, …, 364, 365
Day of Week
d0, 1, …, 5, 6
ddSu, Mo, …, Fr, Sa
dddSun, Mon, …, Fri, Sat
ddddSunday, Monday, …, Friday, Saturday
Hour
H0, 1, …, 22, 23
HH00, 01, …, 22, 23
h1, 2, …, 11, 12
hh01, 02, …, 11, 12
Minute
m0, 1, …, 58, 59
mm00, 01, …, 58, 59
Second
s0, 1, …, 58, 59
ss00, 01, …, 58, 59
Fractional Second
S0, 1, …, 8, 9
SS00, 01, …, 98, 99
SSS000, 001, …, 998, 999
AM/PM
A
en-us : AM, PM
zh-cn : 凌晨|早上|上午|中午|下午|晚上
a
en-us : am, pm
zh-cn : 凌晨|早上|上午|中午|下午|晚上

Summary

Constructors

Properties

Methods

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

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

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

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

ToLocalTime

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

ToIsoDate

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

FormatUniversalTime

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

FormatLocalTime

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