time

Adds a duration to a timestamp.

The duration string can have the following units: ns, us, ms, s, m, h, d, w, y.

mo and y are calendar months and years in local time: the wall-clock time is kept and the day is clamped to the target month (Jan 31 + 1mo is Feb 28/29). All other units are exact amounts of time.

Converts a day count relative to the Unix epoch (1970-01-01), as produced by time.daysFromCivil, back into a civil (Gregorian) calendar year, month, and day. The inverse of time.daysFromCivil.

Based on Howard Hinnant's "civil_from_days" algorithm, the counterpart to daysFromCivil's "days_from_civil".

Converts a Unix timestamp in seconds into a civil (Gregorian) date and time of day. The inverse of time.timestampFromCivil.

Like time.timestampFromCivil, this is pure arithmetic and is not affected by the host's local timezone; the result is in UTC, add time.offset( timestamp ) to get local time.

Returns the ordinal day of the year for a given civil (Gregorian) date, where January 1st is 1.

Converts a civil (Gregorian) calendar date into a day count relative to the Unix epoch (1970-01-01), i.e. the same scale as days in time.civilFromDays and time.weekdayFromDays — negative for dates before the epoch, 0 for the epoch date itself, positive after.

Based on Howard Hinnant's "days_from_civil" algorithm, which is valid for any year representable by the host's integer type, correctly accounting for the Gregorian leap year rule (including the century/400-year exceptions) without needing a lookup table.

See howardhinnant date algorithms and socantre lua port.

Returns the number of days in a given month of a given year, accounting for leap years.

The result is always in the range [28, 31].

month is wrapped into the valid [1, 12] range via modulo before use, so out-of-range values (e.g. 13 or 0) are normalized rather than erroring.

Returns the number of days in a given year, accounting for leap years.

Returns the time elapsed since lua/game was started.

Converts a timestamp to a formatted string.

Format Keys

Converts a duration string to the specified unit.

The duration string can have the following units: ns, us, ms, s, m, h, d, w, y. Numbers without a unit are seconds.

Parses a JS-like ( ISO 8601 ) date-time string, as produced by JavaScript's Date.prototype.toISOString() / JSON.stringify( new Date() ), and converts it to a unix timestamp.

Supported formats ( matching JavaScript's Date Time String Format ):

• 2024-01-15T10:30:00.000Z - UTC, with milliseconds
• 2024-01-15T10:30:00Z - UTC, without milliseconds
• 2024-01-15T10:30:00.000+02:00 / 2024-01-15T10:30:00+0200 - explicit offset
• 2024-01-15T10:30Z - without seconds
• 2024-01-15T10:30:00 - no timezone info, interpreted as local time ( DST-aware )
• 2024-01-15 - date only, interpreted as UTC midnight, matching JavaScript's behaviour

A space can be used instead of T. Fractions of any length are supported, digits beyond the precision of unit are truncated.

Parses an RFC 2822 date-time string ( as used in email Date: headers, for example Mon, 15 Jan 2024 10:30:00 +0000 ) and converts it to a unix timestamp.

The weekday name, the seconds and the timezone are all optional. The timezone can be a numeric offset ( +0200, -0500 ), or one of the named zones UT, GMT, UTC, EST, EDT, CST, CDT, MST, MDT, PST, PDT. A missing or unrecognised timezone is treated as UTC, per RFC 2822's handling of the obsolete military zones.

Checks if a year is a leap year, following the Gregorian rule: divisible by 4, except century years (divisible by 100), unless also divisible by 400.

Returns the ISO 8601 week-numbering year and week number for a given civil (Gregorian) date.

ISO weeks start on Monday, and week 1 is the week containing the year's first Thursday (equivalently, the week containing January 4th). Because of that, the first few days of January may belong to the last week of the previous ISO year, and the last few days of December may belong to week 1 of the next one — which is why the ISO year is returned alongside the week.

See ISO week date.

Returns the number of ISO 8601 weeks in a given ISO week-numbering year.

A year has 53 ISO weeks if it starts on a Thursday, or if it is a leap year that starts on a Wednesday; otherwise it has 52.

Returns the last occurrence of a given weekday in a given month of a given year, e.g. "the last Sunday of March 2026".

Based on Howard Hinnant's year_month_weekday_last: takes the last day of the month, then steps back by the forward distance from weekday to that day's weekday.

month is wrapped into the valid [1, 12] range via modulo before use, the same way time.daysInMonth does.

See howardhinnant date.

Returns the index-th occurrence of a given weekday in a given month of a given year, e.g. "the second Sunday of March 2026".

Based on Howard Hinnant's year_month_weekday: takes the first day of the month, steps forward by the distance from that day's weekday to weekday, then adds whole weeks.

month is wrapped into the valid [1, 12] range via modulo before use, the same way time.daysInMonth does.

Negative index values count from the end of the month instead: -1 is the last occurrence (same as time.lastMonthWeekday), -2 the second-to-last, and so on.

If the month has no such occurrence (e.g. a 5th Monday in a month that only has four), or index is 0, nil is returned.

See howardhinnant date.

Returns the next weekday after the given one, wrapping from 6 (Saturday) back to 0 (Sunday).

Returns the current Unix timestamp (UTC) in the specified unit.

Returns the UTC offset of the local timezone at the given moment, in seconds.

Follows the host's timezone including its DST rules, or time.zone as a fixed offset if it was changed.

Returns a table with the date and time components.

Returns the weekday before the given one, wrapping from 0 (Sunday) back to 6 (Saturday).

Subtracts a duration from a timestamp.

The duration string can have the following units: ns, us, ms, s, m, h, d, w, y.

mo and y are calendar months and years in local time: the wall-clock time is kept and the day is clamped to the target month (Mar 31 - 1mo is Feb 28/29). All other units are exact amounts of time.

Returns the time elapsed since the last call to this function (or since the library was loaded).

Converts a civil (Gregorian) date and time of day into a Unix timestamp in seconds.

Unlike os.time, this is pure arithmetic: the result is not affected by the host's local timezone or DST settings, and works for any year, including those before 1970. The date and time are treated as UTC; subtract time.offset() to convert from local time.

Converts a number of seconds to a duration string.

The duration string can have the following units: ns, us, ms, s, m, h, d, w, y. Negative durations have every segment negated (-1m -30s), so they parse back with time.fromDuration.

Converts a timestamp to a JS-like ( ISO 8601 ) date-time string, for example 2024-01-15T10:30:00.000Z or 2024-01-15T10:30:00.000-05:00 with timezone offset.

Milliseconds are included if unit is ms, us or ns, or if timestamp has a fraction.

The output is compatible with JavaScript's Date.prototype.toISOString() / JSON.stringify( new Date() ), and can be parsed back with time.fromISOString.

Converts a timestamp to an RFC 2822 date-time string, for example Mon, 15 Jan 2024 10:30:00 +0000.

This is the format used by email headers ( Date: ) and HTTP's obsolete rfc1123-date, and is also what JavaScript's Date.prototype.toString() timezone-less variants are based on.

Transforms a timestamp to a different unit.

A double holds ~16 significant digits, so a Unix timestamp in ns (~1.7e18) is only precise to ~256ns, and the same moment in float seconds to ~240ns.

Returns the number of days to add to weekday y to reach weekday x, both given as 0-based weekday indices in [0, 6] (the same convention as time.weekdayFromDays).

The result is always in [0, 6]: 0 if x and y are the same weekday, otherwise the forward (wrapping) distance from y to x.

Returns the day of the week for a given civil (Gregorian) date.

Shortcut for time.weekdayFromDays( time.daysFromCivil( year, month, day ) ).

Returns the day of the week for a given day count relative to the Unix epoch, as produced by time.daysFromCivil.

The result is a 0-based weekday index in [0, 6], matching the convention used by time.nextWeekday/time.prevWeekday/time.weekdayDifference; 1970-01-01 (days == 0) was a Thursday, which is why the calculation offsets by 4 before taking the modulo.