Skip to main content

MetricUnitParseUtils

Reads measurements from text, for chat commands, admin tools, configs and text boxes. Returns plain MetricUnitData; MetricUnit.parse wraps it in a MetricUnit.

Accepts:

  • A number and a unit, with or without a space: "5 km", "5km", "2.5 kilometers", "45%", "20 °C", "20C", "-3 °F", "60 mph", "1.5 MiB". A unit is any unit id, constructor name, symbol, English name (American or Commonwealth spelling), a common alias such as "kph" or "Mbps", or one of @quenty/time's names for a time unit.
  • Several of one dimension, added up: "1h30m", "1 hour, 30 minutes", "5 ft 3 in".
  • A composed unit: "5 m/s", "1.6 MB/s", "6 m·kg/s", "9.81 m/s^2", "5/d".
  • Clock text: "1:30" is one minute thirty (m:ss) and "1:30:00" one hour thirty (h:mm:ss), as MetricUnitFormatUtils writes them with durationStyle = "clock".
  • An ISO 8601 duration without years or months, such as "PT1H30M".

Text such as "m" can name more than one unit: the metre, and @quenty/time's minute. The rule is:

  1. With an expected kind, the unit of that kind wins: parse("5 m", "time") is five minutes.
  2. Otherwise, in text with several parts, the dimension every part can share wins: "1m30s" is minutes.
  3. Otherwise the SI symbol wins over @quenty/time's alias: "5 m" is five metres.

Symbols match case exactly ("MB" is a megabyte, "Mb" is not); names match without case ("Kilometers"). Numbers use the locale's decimal mark when options.locale is given ("1,5 km" in de-de), else .. No-break spaces read as spaces, so formatted text reads back.

Types​

ParseOptions​

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

Reads numbers with this locale's decimal mark and grouping, defaults to . and ,

defaultUnit: UnitLike?--

The unit of a bare number, such as "meter" for a field of metres

}

Functions​

parse​

</>
MetricUnitParseUtils.parse(
text: string,
kind: (KindName | Dimensions)?,
options: ParseOptions?
) → (
string?
)

Reads text as a measurement. Returns the measurement as plain data, or nil and a message suitable to show a player. kind is what the caller expects, such as "length"; it settles ambiguous units and turns a mismatch or a bare number into a helpful message. 

MetricUnitParseUtils.parse("5 km") -- { amount = 5000, dimensions = { length = 1 } }
MetricUnitParseUtils.parse("5", "length") -- nil, 'Add a unit, such as "5 m"'
MetricUnitParseUtils.parse("5", "length", { defaultUnit = "meter" }) -- { amount = 5, dimensions = { length = 1 } }
MetricUnitParseUtils.parse("20 C") -- an absolute temperature
MetricUnitParseUtils.parse("20 C", "temperatureDifference") -- a difference of 20 K
Show raw api
{
    "functions": [
        {
            "name": "parse",
            "desc": "Reads `text` as a measurement. Returns the measurement as plain data, or nil and a message suitable to show a\nplayer. `kind` is what the caller expects, such as `\"length\"`; it settles ambiguous units and turns a mismatch or\na bare number into a helpful message.\n\n```lua\nMetricUnitParseUtils.parse(\"5 km\") -- { amount = 5000, dimensions = { length = 1 } }\nMetricUnitParseUtils.parse(\"5\", \"length\") -- nil, 'Add a unit, such as \"5 m\"'\nMetricUnitParseUtils.parse(\"5\", \"length\", { defaultUnit = \"meter\" }) -- { amount = 5, dimensions = { length = 1 } }\nMetricUnitParseUtils.parse(\"20 C\") -- an absolute temperature\nMetricUnitParseUtils.parse(\"20 C\", \"temperatureDifference\") -- a difference of 20 K\n```",
            "params": [
                {
                    "name": "text",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "kind",
                    "desc": "",
                    "lua_type": "(KindName | Dimensions)?"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "ParseOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "MetricUnitData?"
                },
                {
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 180,
                "path": "src/metricutils/src/Shared/Parsing/MetricUnitParseUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "ParseOptions",
            "desc": "Options for [MetricUnitParseUtils.parse].",
            "fields": [
                {
                    "name": "locale",
                    "lua_type": "string?",
                    "desc": "Reads numbers with this locale's decimal mark and grouping, defaults to `.` and `,`"
                },
                {
                    "name": "defaultUnit",
                    "lua_type": "UnitLike?",
                    "desc": "The unit of a bare number, such as `\"meter\"` for a field of metres"
                }
            ],
            "source": {
                "line": 52,
                "path": "src/metricutils/src/Shared/Parsing/MetricUnitParseUtils.lua"
            }
        }
    ],
    "name": "MetricUnitParseUtils",
    "desc": "Reads measurements from text, for chat commands, admin tools, configs and text boxes. Returns plain\n[MetricUnitData]; [MetricUnit.parse] wraps it in a [MetricUnit].\n\nAccepts:\n\n- A number and a unit, with or without a space: `\"5 km\"`, `\"5km\"`, `\"2.5 kilometers\"`, `\"45%\"`, `\"20 °C\"`,\n  `\"20C\"`, `\"-3 °F\"`, `\"60 mph\"`, `\"1.5 MiB\"`. A unit is any unit id, constructor name, symbol, English name\n  (American or Commonwealth spelling), a common alias such as `\"kph\"` or `\"Mbps\"`, or one of `@quenty/time`'s\n  names for a time unit.\n- Several of one dimension, added up: `\"1h30m\"`, `\"1 hour, 30 minutes\"`, `\"5 ft 3 in\"`.\n- A composed unit: `\"5 m/s\"`, `\"1.6 MB/s\"`, `\"6 m·kg/s\"`, `\"9.81 m/s^2\"`, `\"5/d\"`.\n- Clock text: `\"1:30\"` is one minute thirty (`m:ss`) and `\"1:30:00\"` one hour thirty (`h:mm:ss`), as\n  [MetricUnitFormatUtils] writes them with `durationStyle = \"clock\"`.\n- An ISO 8601 duration without years or months, such as `\"PT1H30M\"`.\n\nText such as `\"m\"` can name more than one unit: the metre, and `@quenty/time`'s minute. The rule is:\n\n1. With an expected `kind`, the unit of that kind wins: `parse(\"5 m\", \"time\")` is five minutes.\n2. Otherwise, in text with several parts, the dimension every part can share wins: `\"1m30s\"` is minutes.\n3. Otherwise the SI symbol wins over `@quenty/time`'s alias: `\"5 m\"` is five metres.\n\nSymbols match case exactly (`\"MB\"` is a megabyte, `\"Mb\"` is not); names match without case (`\"Kilometers\"`).\nNumbers use the locale's decimal mark when `options.locale` is given (`\"1,5 km\"` in `de-de`), else `.`.\nNo-break spaces read as spaces, so formatted text reads back.",
    "source": {
        "line": 30,
        "path": "src/metricutils/src/Shared/Parsing/MetricUnitParseUtils.lua"
    }
}