PcoWSkbVqDnWTu_dm2ix
Collapse Sidebar

DateTime

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:

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

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

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"