DateTime

Mostrar obsoleto

*Este conteúdo estará disponível no idioma selecionado em breve.

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 : 凌晨\|早上\|上午\|中午\|下午\|晚上

Resumo

Construtores

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)

Propriedades

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

Métodos

ToUniversalTime():Dictionary
Returns the components of the DateTime in UTC.
ToLocalTime():Dictionary
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.

Construtores

now

fromUnixTimestamp

Parâmetros

unixTimestamp: number

fromUnixTimestampMillis

Parâmetros

unixTimestampMillis: number

fromUniversalTime

Parâmetros

year: number

Valor Padrão: 1970

month: number

Valor Padrão: 1

day: number

Valor Padrão: 1

hour: number

Valor Padrão: 0

minute: number

Valor Padrão: 0

second: number

Valor Padrão: 0

millisecond: number

Valor Padrão: 0

fromLocalTime

Parâmetros

year: number

Valor Padrão: 1970

month: number

Valor Padrão: 1

day: number

Valor Padrão: 1

hour: number

Valor Padrão: 0

minute: number

Valor Padrão: 0

second: number

Valor Padrão: 0

millisecond: number

Valor Padrão: 0

fromIsoDate

Parâmetros

isoDate: string

Propriedades

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.

Métodos

ToUniversalTime

Dictionary

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.

Devolução

Dictionary

ToLocalTime

Dictionary

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.

Devolução

Dictionary

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.

Devolução

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"

Parâmetros

format: string

locale: string

Devolução

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"

Parâmetros

format: string

locale: string

Devolução

string