Skip to main content

MetricUnitFormatUtils

Writes measurements for people, in the style of JavaScript's Intl.NumberFormat with style: "unit": a localized number, then the unit's symbol or name. The unit is picked to suit the value's size unless one is given, so 1,500 N is 1.5 kN. Takes a MetricUnit or its plain MetricUnitData.

Numbers go through NumberLocalizationUtils, so digit grouping and the decimal mark follow the locale. Unit names come from MetricUnitFallbackStrings, and duration words from TimeLocalizationUtils.

A duration is broken into years, months, days, hours, minutes and seconds with MetricUnit's own averaged year and month (a Julian year, and a twelfth of it), not @quenty/time's 365 and 30 days, so MetricUnit.years(1) reads 1 year and MetricUnit.months(1) reads 1 month. Only @quenty/time's words are used. For a clock-style h:mm:ss, or calendar months, hand exact seconds to TimeDurationUtils or Time yourself. 

MetricUnitFormatUtils.format(MetricUnit.meters(1500)) --> 1.5 km
MetricUnitFormatUtils.format(MetricUnit.meters(1500), { unitDisplay = "long" }) --> 1.5 kilometers
MetricUnitFormatUtils.format(MetricUnit.meters(1500):ToUSCustomary()) --> 4,921.26 ft
MetricUnitFormatUtils.format({ amount = 1234.5, dimensions = { length = 1 } }, { unit = "meter", locale = "de-de" }) --> 1 234,5 m
MetricUnitFormatUtils.format(MetricUnit.minutes(90)) --> 1 hour, 30 minutes
MetricUnitFormatUtils.formatUnit("kilowattHour", 3) --> 3 kWh

Types​

UnitDisplay​

</>
type UnitDisplay = "short" | "long"

"short" writes the unit's symbol (5 km), "long" its name (5 kilometers).

MetricUnitData​

</>
interface MetricUnitData {
amount: number
dimensions: {[string]: number}
absolute: boolean?
}

A measurement as plain data, for saves and for formatting without a [MetricUnit]: its amount in SI base units, its exponents, and whether it is absolute. MetricUnit.toData and MetricUnit.fromData convert to and from it.

DurationStyle​

</>
type DurationStyle = "words" | "clock"

How a duration is written: in words through @quenty/time's duration phrases, or as a clock.

MetricUnitTranslatorLike​

</>
interface MetricUnitTranslatorLike {
FormatByKey: (
self,
key: string,
args: {[string]: any}?
) → string
GetLocaleId: (self) → string
ObserveFormatByKey: (
self,
key: string,
args: {[string]: any}?
) → Observable<string>
}

What the formatter needs of [MetricUnitTranslator]: a JSONTranslator's FormatByKey, GetLocaleId and, for RxMetricUnitFormatUtils.observeFormat, ObserveFormatByKey.

MetricUnitFormatOptions​

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

Picks the number format and unit names, defaults to en-us

unitDisplay: UnitDisplay?--

short symbols (the default) or long names

unit: UnitLike?--

Always write this unit; for a rate, the whole rate's (kilometerPerHour, perHour) or the numerator's (kilometer)

perUnit: TimeUnit?--

Always write a rate per this time unit, such as "hour" or "h"

autoUnit: boolean?--

Pick the unit that suits the size (the default), or always write the SI base unit

minimumFractionDigits: number?--

Pad with zeros to at least this many decimals, defaults to 0

maximumFractionDigits: number?--

Round to at most this many decimals, defaults to 3

maximumSignificantDigits: number?--

Round to this many significant digits instead of fraction digits

useGrouping: boolean?--

Group thousands for the locale, defaults to true

strings: UnitStringOverrides?--

Overrides a unit's phrase, e.g. { kilometer = { short = "%s klicks" } }

perStrings: PerStringOverrides?--

Overrides a per phrase, e.g. { hour = { short = "%s an hour" } }

durationStrings: DurationStringOverrides?--

Overrides a duration word, as in TimeDurationUtils

maxParts: number?--

How many non-zero units a duration is written in, largest first, defaults to 2

separator: string?--

Between the parts of a duration, defaults to ,

durationStyle: DurationStyle?--

words (the default, 1 hour, 30 minutes) or clock (1:30:00, or 1:30 under an hour)

durationTemplate: string?--

A TimeDurationUtils.format template such as hh:mm:ss; years and months are refused

translator: MetricUnitTranslatorLike?--

MetricUnitTranslator, for long names in the player's language

}

Options for MetricUnitFormatUtils.format, modelled on Intl.NumberFormat.

Properties​

NO_BREAK_SPACE​

</>
MetricUnitFormatUtils.NO_BREAK_SPACE: string

The no-break space (U+00A0) that joins a number to its unit, so a line never wraps between them.

Functions​

format​

</>
MetricUnitFormatUtils.format(
) → string

Writes a measurement for the locale in a unit that suits its size, or the one options.unit names. Durations are broken into parts with localized words, temperatures keep whether they are absolute (5 °C) or a difference (5 K), and a rate is written per the shortest time unit it fills at least once (1.6 MB/s).

A value is written in the system of the unit it was made from, so MetricUnit.new(5, "mile") writes miles and MetricUnit.kilometers(8) kilometres. Convert it to write another (MetricUnit.ToMetric, MetricUnit.ToImperial), or use MetricUnitSystem.Format. The locale never chooses a measurement system. 

local length = MetricUnit.meters(2500)
MetricUnitFormatUtils.format(length) --> 2.5 km
MetricUnitFormatUtils.format(length, { unit = "meter" }) --> 2,500 m
MetricUnitFormatUtils.format(length, { unit = "stud" }) --> 8,928.571 studs
MetricUnitFormatUtils.format(length, { unitDisplay = "long", locale = "en-gb" }) --> 2.5 kilometres
MetricUnitFormatUtils.format(length, { maximumSignificantDigits = 1 }) --> 3 km

formatUnit​

</>
MetricUnitFormatUtils.formatUnit(
unit: UnitLike,
amount: number,--

in unit

) → string

Writes amount of the unit unit, as MetricUnitFormatUtils.format would, without picking another unit. A temperature is absolute on its own scale, so formatUnit("celsius", 20) is 20 °C. 

MetricUnitFormatUtils.formatUnit("kilometerPerHour", 90) --> 90 km/h
MetricUnitFormatUtils.formatUnit("liter", 1, { unitDisplay = "long" }) --> 1 liter
MetricUnitFormatUtils.formatUnit("hours", 1.5) --> 1.5 hours

formatNumber​

</>
MetricUnitFormatUtils.formatNumber(
value: number,
) → string

Writes a plain number for the locale: grouped thousands, the locale's decimal mark, and the digit options of MetricUnitFormatOptions. 

MetricUnitFormatUtils.formatNumber(1234.5678) --> 1,234.568
MetricUnitFormatUtils.formatNumber(1234.5, { locale = "de-de" }) --> 1 234,5
MetricUnitFormatUtils.formatNumber(2, { minimumFractionDigits = 2 }) --> 2.00

getDecimalSeparator​

</>
MetricUnitFormatUtils.getDecimalSeparator(locale: string) → string

The decimal mark locale writes numbers with, such as "." or ",".

Show raw api
{
    "functions": [
        {
            "name": "format",
            "desc": "Writes a measurement for the locale in a unit that suits its size, or the one `options.unit` names. Durations are\nbroken into parts with localized words, temperatures keep whether they are absolute (`5 °C`) or a difference\n(`5 K`), and a rate is written per the shortest time unit it fills at least once (`1.6 MB/s`).\n\nA value is written in the system of the unit it was made from, so `MetricUnit.new(5, \"mile\")` writes miles and\n`MetricUnit.kilometers(8)` kilometres. Convert it to write another ([MetricUnit.ToMetric],\n[MetricUnit.ToImperial]), or use [MetricUnitSystem.Format]. The locale never chooses a measurement system.\n\n```lua\nlocal length = MetricUnit.meters(2500)\nMetricUnitFormatUtils.format(length) --> 2.5 km\nMetricUnitFormatUtils.format(length, { unit = \"meter\" }) --> 2,500 m\nMetricUnitFormatUtils.format(length, { unit = \"stud\" }) --> 8,928.571 studs\nMetricUnitFormatUtils.format(length, { unitDisplay = \"long\", locale = \"en-gb\" }) --> 2.5 kilometres\nMetricUnitFormatUtils.format(length, { maximumSignificantDigits = 1 }) --> 3 km\n```",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "MetricUnit | MetricUnitData"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "MetricUnitFormatOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 206,
                "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
            }
        },
        {
            "name": "formatUnit",
            "desc": "Writes `amount` of the unit `unit`, as [MetricUnitFormatUtils.format] would, without picking another unit. A\ntemperature is absolute on its own scale, so `formatUnit(\"celsius\", 20)` is `20 °C`.\n\n```lua\nMetricUnitFormatUtils.formatUnit(\"kilometerPerHour\", 90) --> 90 km/h\nMetricUnitFormatUtils.formatUnit(\"liter\", 1, { unitDisplay = \"long\" }) --> 1 liter\nMetricUnitFormatUtils.formatUnit(\"hours\", 1.5) --> 1.5 hours\n```",
            "params": [
                {
                    "name": "unit",
                    "desc": "",
                    "lua_type": "UnitLike"
                },
                {
                    "name": "amount",
                    "desc": "in `unit`",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "MetricUnitFormatOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 245,
                "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
            }
        },
        {
            "name": "formatNumber",
            "desc": "Writes a plain number for the locale: grouped thousands, the locale's decimal mark, and the digit options of\n[MetricUnitFormatOptions].\n\n```lua\nMetricUnitFormatUtils.formatNumber(1234.5678) --> 1,234.568\nMetricUnitFormatUtils.formatNumber(1234.5, { locale = \"de-de\" }) --> 1 234,5\nMetricUnitFormatUtils.formatNumber(2, { minimumFractionDigits = 2 }) --> 2.00\n```",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "MetricUnitFormatOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 278,
                "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
            }
        },
        {
            "name": "getDecimalSeparator",
            "desc": "The decimal mark `locale` writes numbers with, such as `\".\"` or `\",\"`.",
            "params": [
                {
                    "name": "locale",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 404,
                "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
            }
        }
    ],
    "properties": [
        {
            "name": "NO_BREAK_SPACE",
            "desc": "The no-break space (U+00A0) that joins a number to its unit, so a line never wraps between them.",
            "lua_type": "string",
            "source": {
                "line": 49,
                "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
            }
        }
    ],
    "types": [
        {
            "name": "UnitDisplay",
            "desc": "`\"short\"` writes the unit's symbol (`5 km`), `\"long\"` its name (`5 kilometers`).",
            "lua_type": "\"short\" | \"long\"",
            "source": {
                "line": 69,
                "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
            }
        },
        {
            "name": "MetricUnitData",
            "desc": "A measurement as plain data, for saves and for formatting without a [MetricUnit]: its amount in SI base units,\nits exponents, and whether it is absolute. [MetricUnit.toData] and [MetricUnit.fromData] convert to and from it.",
            "fields": [
                {
                    "name": "amount",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "dimensions",
                    "lua_type": "{ [string]: number }",
                    "desc": ""
                },
                {
                    "name": "absolute",
                    "lua_type": "boolean?",
                    "desc": ""
                }
            ],
            "source": {
                "line": 81,
                "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
            }
        },
        {
            "name": "DurationStyle",
            "desc": "How a duration is written: in words through `@quenty/time`'s duration phrases, or as a clock.",
            "lua_type": "\"words\" | \"clock\"",
            "source": {
                "line": 93,
                "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
            }
        },
        {
            "name": "MetricUnitTranslatorLike",
            "desc": "What the formatter needs of [MetricUnitTranslator]: a `JSONTranslator`'s `FormatByKey`, `GetLocaleId` and,\nfor [RxMetricUnitFormatUtils.observeFormat], `ObserveFormatByKey`.",
            "fields": [
                {
                    "name": "FormatByKey",
                    "lua_type": "(self, key: string, args: { [string]: any }?) -> string",
                    "desc": ""
                },
                {
                    "name": "GetLocaleId",
                    "lua_type": "(self) -> string",
                    "desc": ""
                },
                {
                    "name": "ObserveFormatByKey",
                    "lua_type": "(self, key: string, args: { [string]: any }?) -> Observable<string>",
                    "desc": ""
                }
            ],
            "source": {
                "line": 105,
                "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
            }
        },
        {
            "name": "MetricUnitFormatOptions",
            "desc": "Options for [MetricUnitFormatUtils.format], modelled on `Intl.NumberFormat`.",
            "fields": [
                {
                    "name": "locale",
                    "lua_type": "string?",
                    "desc": "Picks the number format and unit names, defaults to `en-us`"
                },
                {
                    "name": "unitDisplay",
                    "lua_type": "UnitDisplay?",
                    "desc": "`short` symbols (the default) or `long` names"
                },
                {
                    "name": "unit",
                    "lua_type": "UnitLike?",
                    "desc": "Always write this unit; for a rate, the whole rate's (`kilometerPerHour`, `perHour`) or the numerator's (`kilometer`)"
                },
                {
                    "name": "perUnit",
                    "lua_type": "TimeUnit?",
                    "desc": "Always write a rate per this time unit, such as `\"hour\"` or `\"h\"`"
                },
                {
                    "name": "autoUnit",
                    "lua_type": "boolean?",
                    "desc": "Pick the unit that suits the size (the default), or always write the SI base unit"
                },
                {
                    "name": "minimumFractionDigits",
                    "lua_type": "number?",
                    "desc": "Pad with zeros to at least this many decimals, defaults to 0"
                },
                {
                    "name": "maximumFractionDigits",
                    "lua_type": "number?",
                    "desc": "Round to at most this many decimals, defaults to 3"
                },
                {
                    "name": "maximumSignificantDigits",
                    "lua_type": "number?",
                    "desc": "Round to this many significant digits instead of fraction digits"
                },
                {
                    "name": "useGrouping",
                    "lua_type": "boolean?",
                    "desc": "Group thousands for the locale, defaults to true"
                },
                {
                    "name": "strings",
                    "lua_type": "UnitStringOverrides?",
                    "desc": "Overrides a unit's phrase, e.g. `{ kilometer = { short = \"%s klicks\" } }`"
                },
                {
                    "name": "perStrings",
                    "lua_type": "PerStringOverrides?",
                    "desc": "Overrides a per phrase, e.g. `{ hour = { short = \"%s an hour\" } }`"
                },
                {
                    "name": "durationStrings",
                    "lua_type": "DurationStringOverrides?",
                    "desc": "Overrides a duration word, as in `TimeDurationUtils`"
                },
                {
                    "name": "maxParts",
                    "lua_type": "number?",
                    "desc": "How many non-zero units a duration is written in, largest first, defaults to 2"
                },
                {
                    "name": "separator",
                    "lua_type": "string?",
                    "desc": "Between the parts of a duration, defaults to `, `"
                },
                {
                    "name": "durationStyle",
                    "lua_type": "DurationStyle?",
                    "desc": "`words` (the default, `1 hour, 30 minutes`) or `clock` (`1:30:00`, or `1:30` under an hour)"
                },
                {
                    "name": "durationTemplate",
                    "lua_type": "string?",
                    "desc": "A `TimeDurationUtils.format` template such as `hh:mm:ss`; years and months are refused"
                },
                {
                    "name": "translator",
                    "lua_type": "MetricUnitTranslatorLike?",
                    "desc": "[MetricUnitTranslator], for long names in the player's language"
                }
            ],
            "source": {
                "line": 134,
                "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
            }
        }
    ],
    "name": "MetricUnitFormatUtils",
    "desc": "Writes measurements for people, in the style of JavaScript's `Intl.NumberFormat` with `style: \"unit\"`: a\nlocalized number, then the unit's symbol or name. The unit is picked to suit the value's size unless one is\ngiven, so 1,500 N is `1.5 kN`. Takes a [MetricUnit] or its plain [MetricUnitData].\n\nNumbers go through [NumberLocalizationUtils], so digit grouping and the decimal mark follow the locale. Unit\nnames come from [MetricUnitFallbackStrings], and duration words from [TimeLocalizationUtils].\n\nA duration is broken into years, months, days, hours, minutes and seconds with [MetricUnit]'s own averaged year\nand month (a Julian year, and a twelfth of it), not `@quenty/time`'s 365 and 30 days, so `MetricUnit.years(1)`\nreads `1 year` and `MetricUnit.months(1)` reads `1 month`. Only `@quenty/time`'s words are used. For a clock-style\n`h:mm:ss`, or calendar months, hand exact seconds to `TimeDurationUtils` or `Time` yourself.\n\n```lua\nMetricUnitFormatUtils.format(MetricUnit.meters(1500)) --> 1.5 km\nMetricUnitFormatUtils.format(MetricUnit.meters(1500), { unitDisplay = \"long\" }) --> 1.5 kilometers\nMetricUnitFormatUtils.format(MetricUnit.meters(1500):ToUSCustomary()) --> 4,921.26 ft\nMetricUnitFormatUtils.format({ amount = 1234.5, dimensions = { length = 1 } }, { unit = \"meter\", locale = \"de-de\" }) --> 1 234,5 m\nMetricUnitFormatUtils.format(MetricUnit.minutes(90)) --> 1 hour, 30 minutes\nMetricUnitFormatUtils.formatUnit(\"kilowattHour\", 3) --> 3 kWh\n```",
    "source": {
        "line": 26,
        "path": "src/metricutils/src/Shared/Formatting/MetricUnitFormatUtils.lua"
    }
}