DateTime

A DateTime 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 do not store timezone values; rather, 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 functions ToUniversalTime and ToLocalTime return a table of time-related values, such as Year, Month, Day etc. 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	–

Constructors

DateTime.now ( )
Creates a new DateTime representing the current moment in time.

DateTime.fromUnixTimestamp ( Integer unixTimestamp )
Creates a new DateTime object from the given Unix timestamp, or the number of seconds since January 1st, 1970 at 00:00 (UTC).

DateTime.fromUnixTimestampMillis ( Integer unixTimestampMillis )
Create a new DateTime object from the given Unix timestamp, or the number of milliseconds since January 1st, 1970 at 00:00 (UTC).

DateTime.fromUniversalTime ( Integer year = 1970, Integer month = 1, Integer day = 1, Integer hour = 0, Integer minute = 0, Integer second = 0, Integer millisecond = 0 )
Creates a new DateTime using the given units from a UTC time. The values accepted are similar to those found in the time value table returned by `ToUniversalTime`. Date units (year, month, day) that produce an invalid date will raise an error. For example, January 32nd or February 29th on a non-leap year. Time units (hour, minute, second, millisecond) that are outside their normal range are valid. For example, 90 minutes will cause the hour to roll over by 1; -10 seconds will cause the minute value to roll back by 1. Non-integer values are rounded down. For example, providing 2.5 hours will be equivalent to providing 2 hours, not 2 hours 30 minutes. Omitted values are assumed to be their lowest value in their normal range, except for year which defaults to 1970.

DateTime.fromLocalTime ( Integer year = 1970, Integer month = 1, Integer day = 1, Integer hour = 0, Integer minute = 0, Integer second = 0, Integer millisecond = 0 )
Creates a new DateTime using the given units from a local time. The values accepted are similar to those found in the time value table returned by `ToLocalTime`. Date units (year, month, day) that produce an invalid date will raise an error. For example, January 32nd or February 29th on a non-leap year. Time units (hour, minute, second, millisecond) that are outside their normal range are valid. For example, 90 minutes will cause the hour to roll over by 1; -10 seconds will cause the minute value to roll back by 1. Non-integer values are rounded down. For example, providing 2.5 hours will be equivalent to providing 2 hours, not 2 hours 30 minutes. Omitted values are assumed to be their lowest value in their normal range, except for year which defaults to 1970.

DateTime.fromIsoDate ( string isoDate )
Creates a DateTime from an ISO 8601 date-time string in UTC time, such as those returned by `ToIsoDate`. If the string parsing fails, the function returns nil. An example ISO 8601 date-time string would be `2020-01-02T10:30:45Z`, which represents January nd 2020 at 10:30 AM, 45 seconds.

Properties

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

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

Functions

table DateTime: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 table in the DateTime description. The values within this table could be passed to `fromUniversalTime` to produce the original DateTime object.

table DateTime: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 table in the DateTime description. The values within this table could be passed to `fromLocalTime` to produce the original DateTime object.

string DateTime: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.

string DateTime:FormatUniversalTime ( string format, string locale )
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 details on all the available tokens, see `articles/DateTime Format Strings`. 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"

string DateTime:FormatLocalTime ( string format, string locale )
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 details on all the available tokens, see `articles/DateTime Format Strings`. 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"