Skip to main content

RelativeTimeUtils

Describes the distance between two times in words: in 3 hours, a day ago, 2 months.

Types​

RelativeTimeThreshold​

</>
interface RelativeTimeThreshold {
key: string
limit: number?
unit: TimeUnit?
}

One step of the relative time scale. key picks the string, limit is the largest rounded amount this step accepts (omit for the last step), and unit is one of Time.TimeUnit other than milliseconds or quarters. A step without a unit reuses the previous step's diff, which is how 45..89 seconds becomes a minute.

RelativeTimeStringOverrides​

</>
type RelativeTimeStringOverrides = TimeLocalizationUtils.RelativeTimeStringOverrides

RelativeTimeOptions​

</>
interface RelativeTimeOptions {
withoutSuffix: boolean?--

Drop the in / ago wrapper

thresholds: {RelativeTimeThreshold}?--

Replaces the default scale

rounding: ((number) → number)?--

Applied to the absolute amount, defaults to round half up

locale: string?--

Picks the strings through TimeLocalizationUtils, defaults to English

strings: RelativeTimeStringOverrides?--

Overrides or extends the locale's strings keyed by threshold key, plus future and past

}

Functions​

from​

</>
RelativeTimeUtils.from(
currentTime: Time.DateTimeLike,
compareTo: Time.DateTimeLike,
) → string

Describes how far currentTime is from compareTo: a later time reads in a day, an earlier one a day ago. See RelativeTimeOptions to drop the suffix or change the scale. 

print(RelativeTimeUtils.from("2025-09-23T00:00:00Z", "2025-09-22T00:00:00Z")) --> in a day
print(RelativeTimeUtils.from("2025-09-22T00:00:00Z", "2025-09-23T00:00:00Z", { withoutSuffix = true })) --> a day

to​

</>
RelativeTimeUtils.to(
currentTime: Time.DateTimeLike,
compareTo: Time.DateTimeLike,
) → string

Describes how far compareTo is from currentTime. The mirror of [RelativeTimeUtils.from]: RelativeTimeUtils.to(a, b) equals RelativeTimeUtils.from(b, a).

fromNow​

</>
RelativeTimeUtils.fromNow(
currentTime: Time.DateTimeLike,
) → string

Describes how far currentTime is from now: 3 hours ago.

toNow​

</>
RelativeTimeUtils.toNow(
currentTime: Time.DateTimeLike,
) → string

Describes how far now is from currentTime: in 3 hours for a time three hours in the past.

Show raw api
{
    "functions": [
        {
            "name": "from",
            "desc": "Describes how far `currentTime` is from `compareTo`: a later time reads\n`in a day`, an earlier one `a day ago`. See [RelativeTimeOptions] to drop the suffix or\nchange the scale.\n\n```lua\nprint(RelativeTimeUtils.from(\"2025-09-23T00:00:00Z\", \"2025-09-22T00:00:00Z\")) --> in a day\nprint(RelativeTimeUtils.from(\"2025-09-22T00:00:00Z\", \"2025-09-23T00:00:00Z\", { withoutSuffix = true })) --> a day\n```",
            "params": [
                {
                    "name": "currentTime",
                    "desc": "",
                    "lua_type": "Time.DateTimeLike"
                },
                {
                    "name": "compareTo",
                    "desc": "",
                    "lua_type": "Time.DateTimeLike"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "RelativeTimeOptions?\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 185,
                "path": "src/time/src/Shared/RelativeTimeUtils.lua"
            }
        },
        {
            "name": "to",
            "desc": "Describes how far `compareTo` is from `currentTime`. The mirror of\n[RelativeTimeUtils.from]: `RelativeTimeUtils.to(a, b)` equals `RelativeTimeUtils.from(b, a)`.",
            "params": [
                {
                    "name": "currentTime",
                    "desc": "",
                    "lua_type": "Time.DateTimeLike"
                },
                {
                    "name": "compareTo",
                    "desc": "",
                    "lua_type": "Time.DateTimeLike"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "RelativeTimeOptions?\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 197,
                "path": "src/time/src/Shared/RelativeTimeUtils.lua"
            }
        },
        {
            "name": "fromNow",
            "desc": "Describes how far `currentTime` is from now: `3 hours ago`.",
            "params": [
                {
                    "name": "currentTime",
                    "desc": "",
                    "lua_type": "Time.DateTimeLike"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "RelativeTimeOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 208,
                "path": "src/time/src/Shared/RelativeTimeUtils.lua"
            }
        },
        {
            "name": "toNow",
            "desc": "Describes how far now is from `currentTime`: `in 3 hours` for a time\nthree hours in the past.",
            "params": [
                {
                    "name": "currentTime",
                    "desc": "",
                    "lua_type": "Time.DateTimeLike"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "RelativeTimeOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 216,
                "path": "src/time/src/Shared/RelativeTimeUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "RelativeTimeThreshold",
            "desc": "One step of the relative time scale. `key` picks the string, `limit` is the\nlargest rounded amount this step accepts (omit for the last step), and `unit` is one of\n[Time.TimeUnit] other than milliseconds or quarters. A step without a unit reuses the\nprevious step's diff, which is how `45..89 seconds` becomes `a minute`.",
            "fields": [
                {
                    "name": "key",
                    "lua_type": "string",
                    "desc": ""
                },
                {
                    "name": "limit",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "unit",
                    "lua_type": "TimeUnit?",
                    "desc": ""
                }
            ],
            "source": {
                "line": 70,
                "path": "src/time/src/Shared/RelativeTimeUtils.lua"
            }
        },
        {
            "name": "RelativeTimeStringOverrides",
            "desc": "See [TimeLocalizationUtils.RelativeTimeStringOverrides].",
            "lua_type": "TimeLocalizationUtils.RelativeTimeStringOverrides",
            "source": {
                "line": 78,
                "path": "src/time/src/Shared/RelativeTimeUtils.lua"
            }
        },
        {
            "name": "RelativeTimeOptions",
            "desc": "Options for [RelativeTimeUtils.from], [RelativeTimeUtils.to], [RelativeTimeUtils.fromNow] and [RelativeTimeUtils.toNow].",
            "fields": [
                {
                    "name": "withoutSuffix",
                    "lua_type": "boolean?",
                    "desc": "Drop the `in` / `ago` wrapper"
                },
                {
                    "name": "thresholds",
                    "lua_type": "{ RelativeTimeThreshold }?",
                    "desc": "Replaces the default scale"
                },
                {
                    "name": "rounding",
                    "lua_type": "((number) -> number)?",
                    "desc": "Applied to the absolute amount, defaults to round half up"
                },
                {
                    "name": "locale",
                    "lua_type": "string?",
                    "desc": "Picks the strings through [TimeLocalizationUtils], defaults to English"
                },
                {
                    "name": "strings",
                    "lua_type": "RelativeTimeStringOverrides?",
                    "desc": "Overrides or extends the locale's strings keyed by threshold key, plus `future` and `past`"
                }
            ],
            "source": {
                "line": 91,
                "path": "src/time/src/Shared/RelativeTimeUtils.lua"
            }
        }
    ],
    "name": "RelativeTimeUtils",
    "desc": "Describes the distance between two times in words: `in 3 hours`, `a day ago`, `2 months`.",
    "source": {
        "line": 7,
        "path": "src/time/src/Shared/RelativeTimeUtils.lua"
    }
}