Skip to main content

TimeCalendarUtils

Calendar time: describes a time relative to a reference day with phrases like Today at 2:30 PM, Tomorrow at 9:00 AM, Last Friday at 5:00 PM, and falls back to a plain date outside of a week either way. 

TimeCalendarUtils.calendar("2025-09-23T18:30:00Z", "2025-09-22T13:00:00Z") --> Tomorrow at 6:30 PM
TimeCalendarUtils.calendar(os.time() - 3 * 86400) --> Last Friday at 1:00 PM (for example)

Types​

CalendarFormat​

</>
type CalendarFormat = TimeLocalizationUtils.CalendarFormat

CalendarFormats​

</>
type CalendarFormats = TimeLocalizationUtils.CalendarFormatOverrides

Which phrase to use for each distance from the reference day. Missing keys fall back to the locale's defaults from TimeLocalizationUtils.getCalendarFormatsForLocale.

Functions​

calendar​

</>
TimeCalendarUtils.calendar(
currentTime: Time.DateTimeLike,
referenceTime: Time.DateTimeLike,
formats: CalendarFormats?,
locale: string?
) → string

Describes currentTime relative to the day of referenceTime (now when nil). Times within the same day, the next day, the previous day, the next six days and the previous six days each get their own phrase; anything further is a plain date.

formats overrides any of the phrases, see CalendarFormats. The locale picks the default phrases through TimeLocalizationUtils and applies to every template.

Show raw api
{
    "functions": [
        {
            "name": "calendar",
            "desc": "Describes `currentTime` relative to the day of `referenceTime` (now when nil). Times within the same day, the next day, the previous day, the next six days and\nthe previous six days each get their own phrase; anything further is a plain date.\n\n`formats` overrides any of the phrases, see [CalendarFormats]. The `locale` picks the\ndefault phrases through [TimeLocalizationUtils] and applies to every template.",
            "params": [
                {
                    "name": "currentTime",
                    "desc": "",
                    "lua_type": "Time.DateTimeLike"
                },
                {
                    "name": "referenceTime",
                    "desc": "",
                    "lua_type": "Time.DateTimeLike"
                },
                {
                    "name": "formats",
                    "desc": "",
                    "lua_type": "CalendarFormats?"
                },
                {
                    "name": "locale",
                    "desc": "",
                    "lua_type": "string?\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 69,
                "path": "src/time/src/Shared/TimeCalendarUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "CalendarFormat",
            "desc": "See [TimeLocalizationUtils.CalendarFormat].",
            "lua_type": "TimeLocalizationUtils.CalendarFormat",
            "source": {
                "line": 28,
                "path": "src/time/src/Shared/TimeCalendarUtils.lua"
            }
        },
        {
            "name": "CalendarFormats",
            "desc": "Which phrase to use for each distance from the reference day. Missing keys fall back to the\nlocale's defaults from [TimeLocalizationUtils.getCalendarFormatsForLocale].",
            "lua_type": "TimeLocalizationUtils.CalendarFormatOverrides",
            "source": {
                "line": 37,
                "path": "src/time/src/Shared/TimeCalendarUtils.lua"
            }
        }
    ],
    "name": "TimeCalendarUtils",
    "desc": "Calendar time: describes a time relative to a\nreference day with phrases like `Today at 2:30 PM`, `Tomorrow at 9:00 AM`, `Last Friday at\n5:00 PM`, and falls back to a plain date outside of a week either way.\n\n```lua\nTimeCalendarUtils.calendar(\"2025-09-23T18:30:00Z\", \"2025-09-22T13:00:00Z\") --> Tomorrow at 6:30 PM\nTimeCalendarUtils.calendar(os.time() - 3 * 86400) --> Last Friday at 1:00 PM (for example)\n```",
    "source": {
        "line": 14,
        "path": "src/time/src/Shared/TimeCalendarUtils.lua"
    }
}