Skip to main content

TimeDurationUtils

Durations. A duration is a length of time with no start point, kept as a number of seconds to match Roblox's os.time, task.wait and friends. A year is counted as 365 days and a month as 30 days when converting to and from seconds. 

TimeDurationUtils.format({ hours = 1, minutes = 30 }, "hh:mm") --> 01:30
TimeDurationUtils.humanize(TimeDurationUtils.toSeconds(2, "days")) --> 2 days
TimeDurationUtils.toIsoString("PT90M") --> PT1H30M

Types​

DurationTable​

</>
interface DurationTable {
years: number?
months: number?
weeks: number?
days: number?
hours: number?
minutes: number?
seconds: number?
milliseconds: number?
}

Units of a duration. Singular keys are accepted as well.

DurationLike​

</>
type DurationLike = number | DurationTable | string

A number of seconds, a DurationTable, or an ISO 8601 duration such as "P1DT12H".

DurationBreakdown​

</>
interface DurationBreakdown {
years: number
months: number
days: number
hours: number
minutes: number
seconds: number
milliseconds: number
}

A duration broken into whole units, largest first, as TimeDurationUtils.toTable returns it.

DurationStringOverrides​

</>
type DurationStringOverrides = TimeLocalizationUtils.DurationStringOverrides

DurationTrim​

</>
type DurationTrim = "large" | "small" | "both" | "mid" | "all" | false

Which zero-valued tokens TimeDurationUtils.format drops: large the leading ones, small the trailing ones, mid the interior ones, both leading and trailing, all every one and false none. The last remaining token is never dropped.

DurationFormatOptions​

</>
interface DurationFormatOptions {
locale: string?--

Picks the unit phrases through TimeLocalizationUtils, defaults to English

strings: DurationStringOverrides?--

Overrides the phrase for a unit, e.g. { hours = { one = "%d hr", other = "%d hrs" } }

trim: DurationTrim?--

Which zero tokens to drop, defaults to large

stopTrim: string?--

Tokens never dropped, as a template such as m; * before a token in the template does the same

largest: number?--

Show only this many of the largest non-zero tokens; implies trim = "all" unless trim is given

trunc: boolean?--

Truncate the smallest token instead of rounding it

precision: number?--

Decimal places on the smallest token; negative rounds to tens, hundreds and so on

forceLength: boolean?--

Pad the first shown token to its template width even when a larger one was dropped

minValue: number?--

Below this many of the smallest unit, print < and the minimum instead

maxValue: number?--

Above this many of the smallest unit, print > and the maximum instead

limits: {[string]: number}?--

How far a token may count before the next larger token is used: { minutes = 60 } prints one hour as 60:00, { hours = 47 } prints a day and a half as 36:00:00

}

Functions​

toSeconds​

</>
TimeDurationUtils.toSeconds(
duration: DurationLike,
unit: Time.TimeUnit?
) → number

Normalizes any DurationLike to seconds. A bare number is seconds unless unit says otherwise, so toSeconds(5, "minutes") is 300.

toMilliseconds​

</>
TimeDurationUtils.toMilliseconds(
duration: DurationLike,
unit: Time.TimeUnit?
) → number

Normalizes any DurationLike to milliseconds. See TimeDurationUtils.toSeconds.

as​

</>
TimeDurationUtils.as(
duration: DurationLike,
unit: Time.TimeUnit
) → number

Returns the whole duration in one unit, fractional. as(90, "minutes") is 1.5.

toTable​

</>
TimeDurationUtils.toTable(duration: DurationLike) → DurationBreakdown

Breaks the duration into whole years, months, days, hours, minutes, seconds and milliseconds, largest first.

get​

</>
TimeDurationUtils.get(
duration: DurationLike,
unit: Time.TimeUnit
) → number

Returns one whole unit of the breakdown: get({ hours = 25 }, "hours") is 1 and get({ hours = 25 }, "days") is 1. Weeks are whole weeks within the days and quarters whole quarters within the months.

add​

</>
TimeDurationUtils.add(
duration: DurationLike,
other: DurationLike,
unit: Time.TimeUnit?
) → number

Adds another duration, returning seconds. unit applies when other is a number.

subtract​

</>
TimeDurationUtils.subtract(
duration: DurationLike,
other: DurationLike,
unit: Time.TimeUnit?
) → number

Subtracts another duration, returning seconds. unit applies when other is a number.

formatUnit​

</>
TimeDurationUtils.formatUnit(
unit: Time.TimeUnit,
amount: number,
) → string

Prints an amount with its unit, pluralized for the locale: formatUnit("days", 1) is 1 day and formatUnit("days", 45) is 45 days. The amount is printed as given, so formatUnit("hours", 1.5) is 1.5 hours. Quarters have no phrase. 

TimeDurationUtils.formatUnit("hours", 2, { locale = "es-es" }) --> 2 horas

format​

</>
TimeDurationUtils.format(
duration: DurationLike,
template: string?,
) → string

Formats the duration with a template in the style of moment-duration-format. Tokens are y years, M months, w weeks, d days, h hours, m minutes, s seconds, C centiseconds and S milliseconds; repeating a letter zero pads it to that width. The largest token in the template absorbs everything above it, so h:mm on 47 hours is 47:00, and the smallest token is rounded unless trunc is set. __ after a token prints it as a localized phrase such as 2 days, and text in square brackets is literal.

Tokens whose value is zero are dropped from the front by default, so h:mm:ss on 45 seconds is 45; see DurationTrim. Dropping a token also drops the text between it and its neighbour, so put unit words in __ labels rather than brackets when trimming matters. Without a template, one is chosen from the duration's size: 250 milliseconds, 2:03:00, 3 days, 1 week, 3 days, 2 hours or 1 year, 2 months, 3 days. 

TimeDurationUtils.format(47 * 3600, "h:mm:ss") --> 47:00:00
TimeDurationUtils.format(65.432, "mm:ss:CC", { trunc = true }) --> 01:05:43
TimeDurationUtils.format({ days = 45 }, "d __") --> 45 days
TimeDurationUtils.format(123 * 60, "d __ h:mm:ss") --> 2:03:00
TimeDurationUtils.format({ days = 1, minutes = 5 }, "d __, h __, m __", { largest = 2 }) --> 1 day, 5 minutes
TimeDurationUtils.format({ hours = 2 }, "h __", { locale = "es-es" }) --> 2 horas

humanize​

</>
TimeDurationUtils.humanize(
duration: DurationLike,
withSuffix: boolean?,
options: RelativeTimeUtils.RelativeTimeOptions?
) → string

Describes the duration in words through [RelativeTimeUtils]: an hour, 2 days. With withSuffix, a positive duration reads in an hour and a negative one an hour ago. options can set the locale, thresholds or strings; its withoutSuffix is ignored in favour of withSuffix.

toIsoString​

</>
TimeDurationUtils.toIsoString(duration: DurationLike) → string

Formats the duration as an ISO 8601 string such as P1DT12H or PT1.5S. A zero duration is P0D and a negative one is prefixed with -.

Show raw api
{
    "functions": [
        {
            "name": "toSeconds",
            "desc": "Normalizes any [DurationLike] to seconds. A bare number is seconds unless `unit` says\notherwise, so `toSeconds(5, \"minutes\")` is `300`.",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "DurationLike"
                },
                {
                    "name": "unit",
                    "desc": "",
                    "lua_type": "Time.TimeUnit?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 259,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "toMilliseconds",
            "desc": "Normalizes any [DurationLike] to milliseconds. See [TimeDurationUtils.toSeconds].",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "DurationLike"
                },
                {
                    "name": "unit",
                    "desc": "",
                    "lua_type": "Time.TimeUnit?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 283,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "as",
            "desc": "Returns the whole duration in one unit, fractional. `as(90, \"minutes\")`\nis `1.5`.",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "DurationLike"
                },
                {
                    "name": "unit",
                    "desc": "",
                    "lua_type": "Time.TimeUnit"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 291,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "toTable",
            "desc": "Breaks the duration into whole years, months, days, hours, minutes, seconds and milliseconds,\nlargest first.",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "DurationLike"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DurationBreakdown\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 299,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "get",
            "desc": "Returns one whole unit of the breakdown: `get({ hours = 25 }, \"hours\")` is\n`1` and `get({ hours = 25 }, \"days\")` is `1`. Weeks are whole weeks within the days and\nquarters whole quarters within the months.",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "DurationLike"
                },
                {
                    "name": "unit",
                    "desc": "",
                    "lua_type": "Time.TimeUnit"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 333,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "add",
            "desc": "Adds another duration, returning seconds. `unit` applies when `other` is a number.",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "DurationLike"
                },
                {
                    "name": "other",
                    "desc": "",
                    "lua_type": "DurationLike"
                },
                {
                    "name": "unit",
                    "desc": "",
                    "lua_type": "Time.TimeUnit?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 349,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "subtract",
            "desc": "Subtracts another duration, returning seconds. `unit` applies when `other` is a number.",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "DurationLike"
                },
                {
                    "name": "other",
                    "desc": "",
                    "lua_type": "DurationLike"
                },
                {
                    "name": "unit",
                    "desc": "",
                    "lua_type": "Time.TimeUnit?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 356,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "formatUnit",
            "desc": "Prints an amount with its unit, pluralized for the locale: `formatUnit(\"days\", 1)` is\n`1 day` and `formatUnit(\"days\", 45)` is `45 days`. The amount is printed as given, so\n`formatUnit(\"hours\", 1.5)` is `1.5 hours`. Quarters have no phrase.\n\n```lua\nTimeDurationUtils.formatUnit(\"hours\", 2, { locale = \"es-es\" }) --> 2 horas\n```",
            "params": [
                {
                    "name": "unit",
                    "desc": "",
                    "lua_type": "Time.TimeUnit"
                },
                {
                    "name": "amount",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "DurationFormatOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 369,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "format",
            "desc": "Formats the duration with a template in the style of moment-duration-format. Tokens are `y`\nyears, `M` months, `w` weeks, `d` days, `h` hours, `m` minutes, `s` seconds, `C`\ncentiseconds and `S` milliseconds; repeating a letter zero pads it to that width. The largest token in the\ntemplate absorbs everything above it, so `h:mm` on 47 hours is `47:00`, and the smallest\ntoken is rounded unless `trunc` is set. `__` after a token prints it as a localized phrase\nsuch as `2 days`, and text in square brackets is literal.\n\nTokens whose value is zero are dropped from the front by default, so `h:mm:ss` on 45 seconds\nis `45`; see [DurationTrim]. Dropping a token also drops the text between it and its\nneighbour, so put unit words in `__` labels rather than brackets when trimming matters.\nWithout a template, one is chosen from the duration's size: `250 milliseconds`, `2:03:00`,\n`3 days`, `1 week, 3 days, 2 hours` or `1 year, 2 months, 3 days`.\n\n```lua\nTimeDurationUtils.format(47 * 3600, \"h:mm:ss\") --> 47:00:00\nTimeDurationUtils.format(65.432, \"mm:ss:CC\", { trunc = true }) --> 01:05:43\nTimeDurationUtils.format({ days = 45 }, \"d __\") --> 45 days\nTimeDurationUtils.format(123 * 60, \"d __ h:mm:ss\") --> 2:03:00\nTimeDurationUtils.format({ days = 1, minutes = 5 }, \"d __, h __, m __\", { largest = 2 }) --> 1 day, 5 minutes\nTimeDurationUtils.format({ hours = 2 }, \"h __\", { locale = \"es-es\" }) --> 2 horas\n```",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "DurationLike"
                },
                {
                    "name": "template",
                    "desc": "",
                    "lua_type": "string?"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "DurationFormatOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 799,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "humanize",
            "desc": "Describes the duration in words through [RelativeTimeUtils]:\n`an hour`, `2 days`. With `withSuffix`, a positive duration reads `in an hour` and a negative\none `an hour ago`. `options` can set the locale, thresholds or strings; its `withoutSuffix`\nis ignored in favour of `withSuffix`.",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "DurationLike"
                },
                {
                    "name": "withSuffix",
                    "desc": "",
                    "lua_type": "boolean?"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "RelativeTimeUtils.RelativeTimeOptions?\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 847,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "toIsoString",
            "desc": "Formats the duration as an ISO 8601 string such as `P1DT12H` or `PT1.5S`. A zero duration is `P0D` and a negative one is prefixed with `-`.",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "DurationLike"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 864,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "DurationTable",
            "desc": "Units of a duration. Singular keys are accepted as well.",
            "fields": [
                {
                    "name": "years",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "months",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "weeks",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "days",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "hours",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "minutes",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "seconds",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "milliseconds",
                    "lua_type": "number?",
                    "desc": ""
                }
            ],
            "source": {
                "line": 39,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "DurationLike",
            "desc": "A number of seconds, a [DurationTable], or an ISO 8601 duration such as `\"P1DT12H\"`.",
            "lua_type": "number | DurationTable | string",
            "source": {
                "line": 56,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "DurationBreakdown",
            "desc": "A duration broken into whole units, largest first, as [TimeDurationUtils.toTable] returns it.",
            "fields": [
                {
                    "name": "years",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "months",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "days",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "hours",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "minutes",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "seconds",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "milliseconds",
                    "lua_type": "number",
                    "desc": ""
                }
            ],
            "source": {
                "line": 71,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "DurationStringOverrides",
            "desc": "See [TimeLocalizationUtils.DurationStringOverrides].",
            "lua_type": "TimeLocalizationUtils.DurationStringOverrides",
            "source": {
                "line": 87,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "DurationTrim",
            "desc": "Which zero-valued tokens [TimeDurationUtils.format] drops: `large` the leading ones, `small`\nthe trailing ones, `mid` the interior ones, `both` leading and trailing, `all` every one and\n`false` none. The last remaining token is never dropped.",
            "lua_type": "\"large\" | \"small\" | \"both\" | \"mid\" | \"all\" | false",
            "source": {
                "line": 97,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        },
        {
            "name": "DurationFormatOptions",
            "desc": "Options for [TimeDurationUtils.format].",
            "fields": [
                {
                    "name": "locale",
                    "lua_type": "string?",
                    "desc": "Picks the unit phrases through [TimeLocalizationUtils], defaults to English"
                },
                {
                    "name": "strings",
                    "lua_type": "DurationStringOverrides?",
                    "desc": "Overrides the phrase for a unit, e.g. `{ hours = { one = \"%d hr\", other = \"%d hrs\" } }`"
                },
                {
                    "name": "trim",
                    "lua_type": "DurationTrim?",
                    "desc": "Which zero tokens to drop, defaults to `large`"
                },
                {
                    "name": "stopTrim",
                    "lua_type": "string?",
                    "desc": "Tokens never dropped, as a template such as `m`; `*` before a token in the template does the same"
                },
                {
                    "name": "largest",
                    "lua_type": "number?",
                    "desc": "Show only this many of the largest non-zero tokens; implies `trim = \"all\"` unless `trim` is given"
                },
                {
                    "name": "trunc",
                    "lua_type": "boolean?",
                    "desc": "Truncate the smallest token instead of rounding it"
                },
                {
                    "name": "precision",
                    "lua_type": "number?",
                    "desc": "Decimal places on the smallest token; negative rounds to tens, hundreds and so on"
                },
                {
                    "name": "forceLength",
                    "lua_type": "boolean?",
                    "desc": "Pad the first shown token to its template width even when a larger one was dropped"
                },
                {
                    "name": "minValue",
                    "lua_type": "number?",
                    "desc": "Below this many of the smallest unit, print `< ` and the minimum instead"
                },
                {
                    "name": "maxValue",
                    "lua_type": "number?",
                    "desc": "Above this many of the smallest unit, print `> ` and the maximum instead"
                },
                {
                    "name": "limits",
                    "lua_type": "{ [string]: number }?",
                    "desc": "How far a token may count before the next larger token is used: `{ minutes = 60 }` prints one hour as `60:00`, `{ hours = 47 }` prints a day and a half as `36:00:00`"
                }
            ],
            "source": {
                "line": 116,
                "path": "src/time/src/Shared/TimeDurationUtils.lua"
            }
        }
    ],
    "name": "TimeDurationUtils",
    "desc": "Durations. A duration is a length of time with no\nstart point, kept as a number of seconds to match Roblox's `os.time`, `task.wait` and friends.\nA year is counted as 365 days and a month as 30 days when converting to and from\nseconds.\n\n```lua\nTimeDurationUtils.format({ hours = 1, minutes = 30 }, \"hh:mm\") --> 01:30\nTimeDurationUtils.humanize(TimeDurationUtils.toSeconds(2, \"days\")) --> 2 days\nTimeDurationUtils.toIsoString(\"PT90M\") --> PT1H30M\n```",
    "source": {
        "line": 16,
        "path": "src/time/src/Shared/TimeDurationUtils.lua"
    }
}