@quenty/metricutils 2.4.4 → 2.5.0

package/src/Shared/Parsing/MetricUnitParseUtils.spec.lua

@@ -0,0 +1,189 @@
+--!strict
+--[[
+	@class MetricUnitParseUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+type MetricUnit = MetricUnit.MetricUnit
+
+local function parse(text: string, kind: any?, options: any?): MetricUnit
+	local value, err = MetricUnit.parse(text, kind, options)
+	if not value then
+		error(string.format("could not parse %q: %s", text, tostring(err)))
+	end
+	return value
+end
+
+local function parseError(text: string, kind: any?, options: any?): string?
+	local value, err = MetricUnit.parse(text, kind, options)
+	expect(value).toBeNil()
+	return err
+end
+
+describe("MetricUnit.parse", function()
+	it("reads a number and a unit, with or without a space", function()
+		expect(parse("5 km"):In("meter")).toBe(5000)
+		expect(parse("5km"):In("meter")).toBe(5000)
+		expect(parse("2.5 kilometers"):In("meter")).toBe(2500)
+		expect(parse("2.5 Kilometres"):In("meter")).toBe(2500)
+		expect(parse("1.5 MiB"):In("byte")).toBe(1572864)
+		expect(parse("1 KB"):In("byte")).toBe(1000)
+		expect(parse("60 mph"):In("milePerHour")).toBeCloseTo(60, 9)
+		expect(parse("100 kbps"):In("kilobitPerSecond")).toBeCloseTo(100, 9)
+		expect(parse("45%"):In("percent")).toBeCloseTo(45, 9)
+		expect(parse("45°"):In("degree")).toBeCloseTo(45, 9)
+		expect(parse("100 studs"):In("meter")).toBeCloseTo(28, 9)
+	end)
+
+	it("reads composed units", function()
+		expect(parse("5 m/s"):In("meterPerSecond")).toBe(5)
+		expect(parse("9.81 m/s²"):In("meterPerSecondSquared")).toBeCloseTo(9.81, 9)
+		expect(parse("9.81 m/s^2"):In("meterPerSecondSquared")).toBeCloseTo(9.81, 9)
+		expect(parse("1.6 MB/s"):In("kilobytePerSecond")).toBeCloseTo(1600, 6)
+		expect(parse("5/d"):In("perDay")).toBeCloseTo(5, 9)
+		local momentum = parse("6 m·kg/s")
+		expect(momentum:GetDimensions()).toEqual({ length = 1, mass = 1, time = -1 })
+		expect(momentum:GetBaseAmount()).toBe(6)
+		expect(parse("2 m^4"):GetDimensions()).toEqual({ length = 4 })
+		expect(parse("5 ft/s²"):In("meterPerSecondSquared")).toBeCloseTo(5 * 0.3048, 9)
+		expect(parse("3 ft·lb"):GetDimensions()).toEqual({ length = 1, mass = 1 })
+		expect(parse("2 kg*m/s"):GetDimensions()).toEqual({ length = 1, mass = 1, time = -1 })
+	end)
+
+	it("reads a temperature scale as absolute unless a difference is expected", function()
+		local warm = parse("20 °C")
+		expect(warm:IsAbsolute()).toBe(true)
+		expect(warm:In("celsius")).toBeCloseTo(20, 9)
+		expect(parse("20C"):In("celsius")).toBeCloseTo(20, 9)
+		expect(parse("-3 °F"):In("fahrenheit")).toBeCloseTo(-3, 9)
+		local rise = parse("20 C", "temperatureDifference")
+		expect(rise:IsAbsolute()).toBe(false)
+		expect(rise:In("kelvin")).toBeCloseTo(20, 9)
+	end)
+
+	it("adds up several parts of one dimension", function()
+		expect(parse("1h30m"):In("minute")).toBe(90)
+		expect(parse("1 hour, 30 minutes"):In("minute")).toBe(90)
+		expect(parse("1 hour and 30 minutes"):In("minute")).toBe(90)
+		expect(parse("5 ft 3 in"):In("inch")).toBeCloseTo(63, 9)
+		expect(function()
+			parse("20 C 5 F")
+		end).toThrow("Write a temperature as one number and unit")
+	end)
+
+	it("reads clock text and ISO durations", function()
+		expect(parse("1:30"):InSeconds()).toBe(90)
+		expect(parse("1:30:00"):InSeconds()).toBe(5400)
+		expect(parse("-0:45"):InSeconds()).toBe(-45)
+		expect(parse("PT1H30M"):InSeconds()).toBe(5400)
+		expect(string.find(parseError("P1Y") or "", "calendar spans", 1, true) ~= nil).toBe(true)
+	end)
+
+	it("resolves ambiguous units by kind, then by the other parts, then by SI symbol", function()
+		expect(parse("5 m"):In("meter")).toBe(5)
+		expect(parse("5 m", "time"):In("minute")).toBe(5)
+		expect(parse("1m30s"):In("second")).toBe(90)
+		expect(parse("2 M"):In("month")).toBe(2)
+		expect(parseError("5 Mb")).toBe('Unknown unit "Mb"')
+		expect(parse("5 MB"):In("megabyte")).toBe(5)
+	end)
+
+	it("reads bare numbers by kind and default unit", function()
+		expect(parse("5"):GetKind()).toBe("none")
+		expect(parse("5", "none"):GetBaseAmount()).toBe(5)
+		expect(parseError("5", "length")).toBe('Add a unit, such as "5 m"')
+		expect(parseError("45", "angle")).toBe('Add a unit, such as "45°"')
+		expect(parse("5", "length", { defaultUnit = "meter" }):In("meter")).toBe(5)
+		expect(parse("5", "instant", { defaultUnit = "second" }):IsAbsolute()).toBe(true)
+	end)
+
+	it("returns a message to show instead of erroring", function()
+		expect(parseError("")).toBe("Enter a value")
+		expect(parseError("abc")).toBe('Could not read "abc"')
+		expect(parseError("5 klicks")).toBe('Unknown unit "klicks"')
+		expect(parseError("5 kg", "length")).toBe('Expected length, but "5 kg" is mass')
+		expect(parseError("5 m", "temperature")).toBe('Expected temperature, but "5 m" is length')
+	end)
+
+	it("reads numbers with the locale's decimal mark", function()
+		expect(parse("1,5 km", nil, { locale = "de-de" }):In("meter")).toBe(1500)
+		expect(parse("1 234,5 m", nil, { locale = "de-de" }):In("meter")).toBeCloseTo(1234.5, 9)
+		expect(parse("1,234.5 m"):In("meter")).toBeCloseTo(1234.5, 9)
+	end)
+
+	it("reads back what short formatting writes", function()
+		local values: { MetricUnit } = {
+			MetricUnit.meters(2500),
+			MetricUnit.kilometers(0.75),
+			MetricUnit.millimeters(3),
+			MetricUnit.meters(1234.5),
+			MetricUnit.new(50, "squareMeter"),
+			MetricUnit.new(0.25, "liter"),
+			MetricUnit.new(3, "cubicMeter"),
+			MetricUnit.bytes(512),
+			MetricUnit.megabytes(1.6),
+			MetricUnit.new(8, "bit"),
+			MetricUnit.kilograms(80),
+			MetricUnit.tonnes(2),
+			MetricUnit.grams(20),
+			MetricUnit.new(1500, "newton"),
+			MetricUnit.new(4184, "joule"),
+			MetricUnit.new(2500, "watt"),
+			MetricUnit.new(101325, "pascal"),
+			MetricUnit.new(997, "kilogramPerCubicMeter"),
+			MetricUnit.new(5, "meterPerSecond"),
+			MetricUnit.new(36, "kilometerPerHour"),
+			MetricUnit.new(1600, "kilobytePerSecond"),
+			MetricUnit.perDay(5),
+			MetricUnit.perSecond(2),
+			MetricUnit.new(60, "hertz"),
+			MetricUnit.new(9.81, "meterPerSecondSquared"),
+			MetricUnit.celsius(21.5),
+			MetricUnit.celsius(-3),
+			MetricUnit.degrees(45),
+			MetricUnit.new(90, "degreePerSecond"),
+			MetricUnit.new(2, "radianPerSecondSquared"),
+			MetricUnit.none(0.45),
+			MetricUnit.minutes(90),
+			MetricUnit.years(1),
+			MetricUnit.days(1.5),
+			MetricUnit.milliseconds(250),
+			MetricUnit.new(40, "microsecond"),
+			MetricUnit.seconds(0),
+			MetricUnit.kilograms(2) * MetricUnit.new(3, "meterPerSecond"),
+			MetricUnit.pow(MetricUnit.meters(2), 4),
+		}
+		for _, value in values do
+			local text = MetricUnit.format(value)
+			local parsed = parse(text)
+			expect(MetricUnit.format(parsed)).toBe(text)
+			expect(parsed:GetKind()).toBe(value:GetKind())
+		end
+
+		-- A temperature difference reads back with its kind, since "5 K" alone is an absolute temperature
+		local rise = MetricUnit.difference(5, "celsius")
+		expect(MetricUnit.format(parse(MetricUnit.format(rise), "temperatureDifference"))).toBe("5\u{00A0}K")
+	end)
+end)
+
+describe("MetricUnit.parse negative text in several parts", function()
+	it("applies the leading minus sign to every part", function()
+		expect(parse("-1 hour, 30 minutes"):In("minute")).toBeCloseTo(-90, 9)
+		expect(parse("-5 ft 3 in"):In("inch")).toBeCloseTo(-63, 9)
+		expect(parse("-1h30m"):In("second")).toBeCloseTo(-5400, 9)
+		expect(parse("1 hour, 30 minutes"):In("minute")).toBeCloseTo(90, 9)
+	end)
+
+	it("reads back what the formatter writes for a negative duration", function()
+		local written = MetricUnit.format(-MetricUnit.minutes(90))
+		expect(parse(written):In("minute")).toBeCloseTo(-90, 9)
+	end)
+end)

package/src/Shared/Systems/MetricUnitSystem.lua

@@ -0,0 +1,322 @@
+--!strict
+--[=[
+	A system of units: the units it declares, the units a value is shown in when it prefers this system, and the
+	system it falls back to for everything else. Metric is the base: every unit is sized in SI units, and a value
+	made from a metric unit prefers nothing. US customary, British imperial and Roblox studs are systems
+	([MetricUnitSystems]), and a game can declare its own, such as studs at another scale.
+
+	A value made from a system's unit shows itself in that system, so studs read back as studs. To show any value
+	in a system, convert it with [MetricUnit.ToSystem] or ask the system to [MetricUnitSystem.Format] it.
+
+	```lua
+	local MINI = MetricUnitSystems.roblox({ name = "robloxMini", metersPerStud = 0.028 })
+
+	local height = MINI:New(5, "stud") -- 14 cm
+	MetricUnit.format(height) -- "5 studs"
+	MINI:In(height, "stud") -- 5
+	height:In("meter") -- 0.14
+
+	MetricUnitSystems.IMPERIAL:Format(MetricUnit.new(2, "liter")) -- "3.52 imp pt"
+	```
+
+	Every amount is held in SI units, so values made through different systems add, compare and convert freely.
+
+	@class MetricUnitSystem
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local MetricUnitDefinitions = require("MetricUnitDefinitions")
+local MetricUnitDimensionUtils = require("MetricUnitDimensionUtils")
+
+type UnitDefinition = MetricUnitDefinitions.UnitDefinition
+
+local MetricUnitSystem = {}
+MetricUnitSystem.ClassName = "MetricUnitSystem"
+MetricUnitSystem.__index = MetricUnitSystem
+
+-- MetricUnit and its formatter require the well-known systems, so this requires them back only when called
+local function requireWhenCalled(moduleName: string): any
+	return (require :: any)(moduleName)
+end
+
+local SYSTEM_BY_OWN_UNIT: { [UnitDefinition]: MetricUnitSystem } = setmetatable({} :: any, { __mode = "kv" })
+
+--[=[
+	What a system is made from.
+
+	- `units` are the units it declares, from [MetricUnitDefinitions.createUnits]. They take the place of a
+	  well-known unit of the same id, so a system can rescale `stud` and keep its names and translations.
+	- `displayUnits` lists, for each dimension, the unit ids to choose from by size, largest first.
+	- `pointDisplayUnits` does the same for absolute values, such as `{ "celsius" }` for temperatures.
+	- `fallback` is the system asked for any dimension this one does not list.
+
+	@interface MetricUnitSystemConfig
+	.name string
+	.units { UnitDefinition }?
+	.displayUnits { { string } }?
+	.pointDisplayUnits { { string } }?
+	.fallback MetricUnitSystem?
+	@within MetricUnitSystem
+]=]
+export type MetricUnitSystemConfig = {
+	name: string,
+	units: { UnitDefinition }?,
+	displayUnits: { { string } }?,
+	pointDisplayUnits: { { string } }?,
+	fallback: MetricUnitSystem?,
+}
+
+export type MetricUnitSystem = typeof(setmetatable(
+	{} :: {
+		_name: string,
+		_units: { UnitDefinition },
+		_unitsById: { [string]: UnitDefinition },
+		_displayUnitIds: { { string } },
+		_pointDisplayUnitIds: { { string } },
+		_resolved: { displayUnits: { { UnitDefinition } }?, pointDisplayUnits: { { UnitDefinition } }? },
+		_fallback: MetricUnitSystem?,
+	},
+	{} :: typeof({ __index = MetricUnitSystem })
+))
+
+--[=[
+	A system from `config`. See [MetricUnitSystemConfig].
+
+	@param config MetricUnitSystemConfig
+	@return MetricUnitSystem
+]=]
+function MetricUnitSystem.new(config: MetricUnitSystemConfig): MetricUnitSystem
+	assert(type(config) == "table", "Bad config")
+	assert(type(config.name) == "string", "Bad config.name")
+	assert(config.fallback == nil or MetricUnitSystem.isSystem(config.fallback), "Bad config.fallback")
+
+	local units: { UnitDefinition } = config.units or {}
+	local unitsById: { [string]: UnitDefinition } = {}
+	for _, unit in units do
+		unitsById[unit.id] = unit
+	end
+
+	local self: MetricUnitSystem = setmetatable({} :: any, MetricUnitSystem)
+	for _, unit in units do
+		SYSTEM_BY_OWN_UNIT[unit] = self
+	end
+	self._name = config.name
+	self._units = table.freeze(table.clone(units))
+	self._unitsById = table.freeze(unitsById)
+	self._fallback = config.fallback
+	self._displayUnitIds = table.freeze(table.clone(config.displayUnits or {}))
+	self._pointDisplayUnitIds = table.freeze(table.clone(config.pointDisplayUnits or {}))
+	self._resolved = {}
+	return table.freeze(self :: any)
+end
+
+--[=[
+	The system that declared `unit` in its config, or nil for a well-known unit.
+
+	@param unit UnitDefinition
+	@return MetricUnitSystem?
+]=]
+function MetricUnitSystem.getSystemDeclaring(unit: UnitDefinition): MetricUnitSystem?
+	return SYSTEM_BY_OWN_UNIT[unit]
+end
+
+--[=[
+	Whether `value` is a [MetricUnitSystem].
+
+	@param value any
+	@return boolean
+]=]
+function MetricUnitSystem.isSystem(value: any): boolean
+	return type(value) == "table" and getmetatable(value) == MetricUnitSystem
+end
+
+--[=[
+	The system's name, such as `"imperial"`.
+
+	@return string
+]=]
+function MetricUnitSystem.GetName(self: MetricUnitSystem): string
+	return self._name
+end
+
+--[=[
+	The system asked for the dimensions this one does not list, or nil.
+
+	@return MetricUnitSystem?
+]=]
+function MetricUnitSystem.GetFallback(self: MetricUnitSystem): MetricUnitSystem?
+	return self._fallback
+end
+
+--[=[
+	The units this system declares itself, not counting its fallbacks.
+
+	@return { UnitDefinition }
+]=]
+function MetricUnitSystem.GetUnits(self: MetricUnitSystem): { UnitDefinition }
+	return self._units
+end
+
+--[=[
+	The unit `unit` names in this system: its own, then its fallbacks', then the well-known one. A unit given
+	itself is returned as it is. The result can be passed anywhere a unit is named, and keeps this system's scale.
+
+	```lua
+	height:As(MINI:GetUnit("stud"))
+	```
+
+	@param unit UnitLike
+	@return UnitDefinition?
+]=]
+function MetricUnitSystem.GetUnit(self: MetricUnitSystem, unit: string | UnitDefinition): UnitDefinition?
+	if type(unit) ~= "string" then
+		return MetricUnitDefinitions.getUnit(unit)
+	end
+	local system: MetricUnitSystem? = self
+	while system do
+		local own = system._unitsById[unit]
+		if own then
+			return own
+		end
+		system = system._fallback
+	end
+	return MetricUnitDefinitions.getUnit(unit)
+end
+
+--[=[
+	The units a value of `dimensions` is shown in when it prefers this system, largest first: this system's, then
+	its fallbacks', or nil when none lists the dimension. An absolute value takes the point display units first.
+
+	@param dimensions Dimensions
+	@param absolute boolean?
+	@return { UnitDefinition }?
+]=]
+function MetricUnitSystem.GetDisplayUnits(
+	self: MetricUnitSystem,
+	dimensions: MetricUnitDimensionUtils.Dimensions,
+	absolute: boolean?
+): { UnitDefinition }?
+	local system: MetricUnitSystem? = self
+	while system do
+		local displayUnits, pointDisplayUnits = system:_getDisplayUnitLists()
+		local found = (absolute and MetricUnitSystem._findByDimensions(pointDisplayUnits, dimensions))
+			or MetricUnitSystem._findByDimensions(displayUnits, dimensions)
+		if found then
+			return found
+		end
+		system = system._fallback
+	end
+	return nil
+end
+
+--[=[
+	`amount` of this system's `unit`, such as `MINI:New(5, "stud")`.
+
+	@param amount number
+	@param unit UnitLike
+	@return MetricUnit
+]=]
+function MetricUnitSystem.New(self: MetricUnitSystem, amount: number, unit: string | UnitDefinition): any
+	local MetricUnit = requireWhenCalled("MetricUnit")
+	return MetricUnit.new(amount, self:_requireUnit(unit, "New"))
+end
+
+--[=[
+	How many of this system's `unit` `value` is, such as `MINI:In(height, "stud")`.
+
+	@param value MetricUnit
+	@param unit UnitLike
+	@return number
+]=]
+function MetricUnitSystem.In(self: MetricUnitSystem, value: any, unit: string | UnitDefinition): number
+	return value:In(self:_requireUnit(unit, "In"))
+end
+
+--[=[
+	Text for players with `value` in this system's units where it has them, as [MetricUnit.format] writes it.
+
+	```lua
+	MetricUnitSystems.IMPERIAL:Format(MetricUnit.kilograms(80)) -- "12.598 st"
+	```
+
+	@param value MetricUnit | MetricUnitData
+	@param options MetricUnitFormatOptions?
+	@return string
+]=]
+function MetricUnitSystem.Format(self: MetricUnitSystem, value: any, options: any?): string
+	local MetricUnitFormatUtils = requireWhenCalled("MetricUnitFormatUtils")
+	return MetricUnitFormatUtils._formatInSystem(value, self, options)
+end
+
+--[=[
+	Reads `text` as [MetricUnit.parse] does, with this system's units: `MINI:Parse("5 studs")` is five of its
+	studs.
+
+	@param text string
+	@param kind (KindName | Dimensions)?
+	@param options ParseOptions?
+	@return MetricUnit?
+	@return string? -- why it could not be read
+]=]
+function MetricUnitSystem.Parse(self: MetricUnitSystem, text: string, kind: any?, options: any?): (any?, string?)
+	local MetricUnit = requireWhenCalled("MetricUnit")
+	return MetricUnit._parseInSystem(text, kind, options, self)
+end
+
+function MetricUnitSystem._requireUnit(
+	self: MetricUnitSystem,
+	unit: string | UnitDefinition,
+	verb: string
+): UnitDefinition
+	local definition = self:GetUnit(unit)
+	if not definition then
+		error(string.format("MetricUnitSystem:%s: %q knows no unit %q", verb, self._name, tostring(unit)), 3)
+	end
+	return definition
+end
+
+function MetricUnitSystem._findByDimensions(
+	lists: { { UnitDefinition } },
+	dimensions: MetricUnitDimensionUtils.Dimensions
+): { UnitDefinition }?
+	for _, units in lists do
+		if MetricUnitDimensionUtils.equal(units[1].dimensions, dimensions) then
+			return units
+		end
+	end
+	return nil
+end
+
+function MetricUnitSystem._getDisplayUnitLists(self: MetricUnitSystem): ({ { UnitDefinition } }, { { UnitDefinition } })
+	local resolved = self._resolved
+	local displayUnits = resolved.displayUnits
+	local pointDisplayUnits = resolved.pointDisplayUnits
+	if displayUnits and pointDisplayUnits then
+		return displayUnits, pointDisplayUnits
+	end
+	local newDisplayUnits = self:_resolveDisplayUnits(self._displayUnitIds)
+	local newPointDisplayUnits = self:_resolveDisplayUnits(self._pointDisplayUnitIds)
+	resolved.displayUnits = newDisplayUnits
+	resolved.pointDisplayUnits = newPointDisplayUnits
+	return newDisplayUnits, newPointDisplayUnits
+end
+
+function MetricUnitSystem._resolveDisplayUnits(self: MetricUnitSystem, lists: { { string } }): { { UnitDefinition } }
+	local resolved: { { UnitDefinition } } = {}
+	for _, ids in lists do
+		local units: { UnitDefinition } = {}
+		for _, id in ids do
+			local unit = self:GetUnit(id)
+			if not unit then
+				error(string.format("MetricUnitSystem %q knows no unit %q", self._name, id), 4)
+			end
+			table.insert(units, unit)
+		end
+		assert(#units > 0, "Empty display unit list")
+		table.insert(resolved, table.freeze(units))
+	end
+	return table.freeze(resolved)
+end
+
+return MetricUnitSystem

package/src/Shared/Systems/MetricUnitSystem.spec.lua

@@ -0,0 +1,181 @@
+--!strict
+--[[
+	@class MetricUnitSystem.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+local MetricUnitDefinitions = require("MetricUnitDefinitions")
+local MetricUnitSystem = require("MetricUnitSystem")
+local MetricUnitSystems = require("MetricUnitSystems")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local MINI = MetricUnitSystems.roblox({ name = "robloxMini", metersPerStud = 0.028 })
+
+local function plain(text: string): string
+	return (string.gsub(text, "\u{00A0}", " "))
+end
+
+local function format(value: any, options: any?): string
+	return plain(MetricUnit.format(value, options))
+end
+
+describe("MetricUnitSystems", function()
+	it("names the well-known systems and chains their fallbacks", function()
+		expect(MetricUnitSystems.METRIC:GetName()).toBe("metric")
+		expect(MetricUnitSystems.US_CUSTOMARY:GetFallback()).toBe(MetricUnitSystems.US_CUSTOMARY_AND_IMPERIAL)
+		expect(MetricUnitSystems.IMPERIAL:GetFallback()).toBe(MetricUnitSystems.US_CUSTOMARY_AND_IMPERIAL)
+		expect(MetricUnitSystems.US_CUSTOMARY_AND_IMPERIAL:GetFallback()).toBe(MetricUnitSystems.METRIC)
+		expect(MetricUnitSystems.ROBLOX:GetFallback()).toBe(MetricUnitSystems.METRIC)
+		expect(MetricUnitSystem.isSystem(MetricUnitSystems.ROBLOX)).toBe(true)
+		expect(MetricUnitSystem.isSystem({})).toBe(false)
+	end)
+
+	it("finds the system that declares a unit", function()
+		expect(MetricUnitSystems.getSystemOfUnit(assert(MetricUnitDefinitions.getUnit("imperialPint")))).toBe(
+			MetricUnitSystems.IMPERIAL
+		)
+		expect(MetricUnitSystems.getSystemOfUnit(assert(MINI:GetUnit("stud")))).toBe(MINI)
+		expect(MetricUnitSystems.getSystemOfUnit(assert(MetricUnitDefinitions.getUnit("second")))).toBeNil()
+	end)
+end)
+
+describe("a value shows itself in the system of the unit it was made from", function()
+	it("prefers nothing when made from a metric unit", function()
+		expect(MetricUnit.kilometers(8):GetDisplaySystem()).toBeNil()
+		expect(format(MetricUnit.kilometers(8))).toBe("8 km")
+	end)
+
+	it("prefers the unit's system otherwise", function()
+		expect(format(MetricUnit.new(5, "mile"))).toBe("5 mi")
+		expect(format(MetricUnit.new(30, "milePerUsGallon"))).toBe("30 mpg (US)")
+		expect(format(MetricUnit.new(2, "imperialPint"))).toBe("2 imp pt")
+		expect(format(MetricUnit.studs(10))).toBe("10 studs")
+	end)
+
+	it("converts to another system for display", function()
+		local distance = MetricUnit.new(5, "mile")
+		expect(format(distance:ToMetric())).toBe("8.047 km")
+		expect(format(MetricUnit.kilometers(8):ToImperial())).toBe("4.971 mi")
+	end)
+end)
+
+describe("MetricUnitSystem:Format", function()
+	it("shows any value in the system", function()
+		expect(plain(MetricUnitSystems.IMPERIAL:Format(MetricUnit.new(2, "liter")))).toBe("3.52 imp pt")
+		expect(plain(MetricUnitSystems.US_CUSTOMARY:Format(MetricUnit.new(2, "liter")))).toBe("2.113 US qt")
+		expect(plain(MetricUnitSystems.METRIC:Format(MetricUnit.new(5, "mile")))).toBe("8.047 km")
+		expect(plain(MINI:Format(MetricUnit.meters(0.14)))).toBe("5 studs")
+	end)
+
+	it("falls back for dimensions the system does not list", function()
+		expect(plain(MINI:Format(MetricUnit.seconds(90)))).toBe("1 minute, 30 seconds")
+		expect(plain(MetricUnitSystems.IMPERIAL:Format(MetricUnit.new(5, "volt")))).toBe("5 V")
+	end)
+end)
+
+describe("MetricUnitSystems.roblox", function()
+	it("reads stud amounts in and out at a game's own scale", function()
+		local height = MINI:New(5, "stud")
+		expect(height:In("meter")).toBeCloseTo(0.14, 9)
+		expect(MINI:In(height, "stud")).toBeCloseTo(5, 9)
+		expect(format(height)).toBe("5 studs")
+		expect(format(height:ToMetric())).toBe("14 cm")
+	end)
+
+	it("scales speeds, accelerations and the mass unit with the stud", function()
+		expect(MINI:New(10, "studPerSecond"):In("meterPerSecond")).toBeCloseTo(0.28, 9)
+		expect(MINI:New(1, "studPerSecondSquared"):In("meterPerSecondSquared")).toBeCloseTo(0.028, 9)
+		expect(MINI:New(1, "robloxMassUnit"):In("gram")).toBeCloseTo(21.952, 9)
+		if typeof(Vector3) == "userdata" or typeof(Vector3) == "table" then
+			local speed = MINI:New(Vector3.new(30, 40, 0).Magnitude, "studPerSecond")
+			expect(speed:In("meterPerSecond")).toBeCloseTo(1.4, 9)
+		end
+	end)
+
+	it("keeps Roblox's own studs apart from the game's", function()
+		local height = MINI:New(5, "stud")
+		expect(height:In("stud")).toBeCloseTo(0.5, 9)
+		expect((MetricUnit.studs(10) + MINI:New(100, "stud")):In("meter")).toBeCloseTo(5.6, 9)
+	end)
+
+	it("keeps its studs through arithmetic", function()
+		local height = MINI:New(5, "stud")
+		expect(format(height * 2)).toBe("10 studs")
+		expect(format(height / MetricUnit.seconds(1))).toBe("5 studs/s")
+		expect(format(MetricUnit.round(MINI:New(5.4, "stud"), "stud"))).toBe("5 studs")
+	end)
+
+	it("pins a value to one of its units", function()
+		local stud = assert(MINI:GetUnit("stud"))
+		expect(format(MetricUnit.meters(0.14):As(stud))).toBe("5 studs")
+		expect(MetricUnit.meters(0.14):As(stud):GetDisplayUnit()).toBe(stud)
+		expect(MetricUnit.meters(0.14):In(stud)).toBeCloseTo(5, 9)
+	end)
+
+	it("parses studs at its scale", function()
+		local value = assert(MINI:Parse("5 studs", "length"))
+		expect(value:In("meter")).toBeCloseTo(0.14, 9)
+		expect(format(value)).toBe("5 studs")
+		local plainStuds = assert(MetricUnit.parse("5 studs", "length"))
+		expect(plainStuds:In("meter")).toBeCloseTo(1.4, 9)
+		local bare = assert(MINI:Parse("5", "length", { defaultUnit = "stud" }))
+		expect(bare:In("meter")).toBeCloseTo(0.14, 9)
+	end)
+
+	it("shows the game's stud amounts in a player's chosen system", function()
+		local distance = MINI:New(10000, "stud")
+		expect(plain(MetricUnitSystems.METRIC:Format(distance))).toBe("280 m")
+		expect(plain(MetricUnitSystems.US_CUSTOMARY:Format(distance))).toBe("918.635 ft")
+		expect(format(distance)).toBe("10,000 studs")
+	end)
+end)
+
+describe("MetricUnitSystem.new", function()
+	local SPACE = MetricUnitSystem.new({
+		name = "space",
+		units = MetricUnitDefinitions.createUnits("length", "space", {
+			{ id = "lightYear" :: any, factor = 9.4607e15, symbol = "ly", name = "light-year" },
+			{ id = "parsec" :: any, factor = 3.0857e16, symbol = "pc", name = "parsec", prefixes = "si" },
+		}),
+		displayUnits = { { "parsec", "lightYear", "kilometer" } },
+		fallback = MetricUnitSystems.METRIC,
+	})
+
+	it("declares units only it knows", function()
+		expect(MetricUnitDefinitions.getUnit("lightYear" :: any)).toBeNil()
+		expect(SPACE:New(2, "lightYear"):In("kilometer")).toBeCloseTo(1.89214e13, -8)
+		expect(SPACE:In(SPACE:New(1, "kiloparsec"), "parsec")).toBeCloseTo(1000, 9)
+		expect(SPACE:New(3, "meter"):In("meter")).toBe(3)
+		expect(function()
+			MetricUnit.new(1, "lightYear" :: any)
+		end).toThrow('MetricUnit.new knows no unit "lightYear"')
+		expect(function()
+			SPACE:New(1, "furlong")
+		end).toThrow('"space" knows no unit "furlong"')
+	end)
+
+	it("shows and writes its own units in English", function()
+		local distance = SPACE:New(4.2, "lightYear")
+		expect(format(distance)).toBe("1.288 pc")
+		expect(format(distance, { unit = "lightYear", unitDisplay = "long" })).toBe("4.2 light-years")
+		expect(plain(SPACE:Format(MetricUnit.kilograms(3)))).toBe("3 kg")
+	end)
+
+	it("parses its own units", function()
+		local value = assert(SPACE:Parse("4.2 ly", "length"))
+		expect(SPACE:In(value, "lightYear")).toBeCloseTo(4.2, 9)
+	end)
+
+	it("errors on a display unit it cannot find, when it first shows a value", function()
+		local broken = MetricUnitSystem.new({ name = "broken", displayUnits = { { "furlong" } } })
+		expect(function()
+			broken:Format(MetricUnit.meters(1))
+		end).toThrow('MetricUnitSystem "broken" knows no unit "furlong"')
+	end)
+end)