@quenty/metricutils 2.4.3 → 2.5.0

package/src/Shared/Localization/PluralCategoryUtils.lua

@@ -0,0 +1,103 @@
+--!strict
+--[=[
+	CLDR cardinal plural rules: which form of a word (`one`, `few`, `many`, `other`, …) a number takes in a language.
+	Nothing here is specific to units; [MetricUnitFormatUtils] uses it to pick a translated unit name's form.
+
+	@class PluralCategoryUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local ResolveLocaleUtils = require("ResolveLocaleUtils")
+
+local PluralCategoryUtils = {}
+
+local DEFAULT_LOCALE = "en-us"
+
+--[=[
+	A CLDR plural category. A translated name has a key for each category its language uses.
+
+	@type PluralCategory "zero" | "one" | "two" | "few" | "many" | "other"
+	@within PluralCategoryUtils
+]=]
+export type PluralCategory = "zero" | "one" | "two" | "few" | "many" | "other"
+
+--[=[
+	The CLDR plural category of a number as written in `locale`, from CLDR's cardinal plural rules for every language
+	[MetricUnitTranslator] ships. `amount` is the rounded value shown and `fraction` the decimals written after the
+	decimal mark (`"50"` for "1.50"), since English writes "1 meter" but "1.0 meters".
+
+	- `one` only: English, German (`i = 1 and v = 0`); Spanish and Turkish (`n = 1`); Vietnamese (`i = 0 or n = 1`).
+	- `one` and `many`: French and Portuguese (`one` for `i = 0..1`), Italian (`one` for `i = 1 and v = 0`); `many`
+	  is a whole multiple of a million, as Spanish also has.
+	- `one`, `few`, `many`: Russian and Polish, for whole numbers; their fractions are `other`.
+	- `zero`, `one`, `two`, `few`, `many`: Arabic.
+	- `other` only: Chinese, Japanese, Korean, Thai and Indonesian.
+
+	```lua
+	PluralCategoryUtils.getPluralCategory("en-us", 1) -- "one"
+	PluralCategoryUtils.getPluralCategory("en-us", 1, "0") -- "other", as in "1.0 meters"
+	PluralCategoryUtils.getPluralCategory("fr-fr", 1.5, "5") -- "one"
+	PluralCategoryUtils.getPluralCategory("ru-ru", 3) -- "few"
+	PluralCategoryUtils.getPluralCategory("ar", 11) -- "many"
+	```
+
+	@param locale string?
+	@param amount number
+	@param fraction string? -- the decimals written, if any
+	@return PluralCategory
+]=]
+function PluralCategoryUtils.getPluralCategory(locale: string?, amount: number, fraction: string?): PluralCategory
+	local language = ResolveLocaleUtils.getLanguageSubtag(locale or DEFAULT_LOCALE) or "en"
+
+	local absoluteValue = math.abs(amount)
+	local integerPart = math.floor(absoluteValue)
+	local decimalsWritten = if fraction then #fraction elseif absoluteValue ~= integerPart then 1 else 0
+	local isWholeMillion = decimalsWritten == 0 and integerPart ~= 0 and integerPart % 1_000_000 == 0
+
+	if language == "en" or language == "de" then
+		return if integerPart == 1 and decimalsWritten == 0 then "one" else "other"
+	elseif language == "es" then
+		return if absoluteValue == 1 then "one" elseif isWholeMillion then "many" else "other"
+	elseif language == "fr" or language == "pt" then
+		return if integerPart == 0 or integerPart == 1 then "one" elseif isWholeMillion then "many" else "other"
+	elseif language == "it" then
+		return if integerPart == 1 and decimalsWritten == 0 then "one" elseif isWholeMillion then "many" else "other"
+	elseif language == "tr" then
+		return if absoluteValue == 1 then "one" else "other"
+	elseif language == "vi" then
+		return if integerPart == 0 or absoluteValue == 1 then "one" else "other"
+	elseif language == "ru" or language == "pl" then
+		if decimalsWritten ~= 0 then
+			return "other"
+		end
+		local ones, tens = integerPart % 10, integerPart % 100
+		if language == "pl" and integerPart == 1 then
+			return "one"
+		elseif language == "ru" and ones == 1 and tens ~= 11 then
+			return "one"
+		elseif ones >= 2 and ones <= 4 and (tens < 12 or tens > 14) then
+			return "few"
+		end
+		return "many"
+	elseif language == "ar" then
+		if absoluteValue == 0 then
+			return "zero"
+		elseif absoluteValue == 1 then
+			return "one"
+		elseif absoluteValue == 2 then
+			return "two"
+		elseif absoluteValue == integerPart then
+			local lastTwoDigits = integerPart % 100
+			if lastTwoDigits >= 3 and lastTwoDigits <= 10 then
+				return "few"
+			elseif lastTwoDigits >= 11 then
+				return "many"
+			end
+		end
+		return "other"
+	end
+	return "other"
+end
+
+return table.freeze(PluralCategoryUtils)

package/src/Shared/Localization/PluralCategoryUtils.spec.lua

@@ -0,0 +1,77 @@
+--!strict
+--[[
+	@class PluralCategoryUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local PluralCategoryUtils = require("PluralCategoryUtils")
+
+local describe = Jest.Globals.describe
+local it = Jest.Globals.it
+
+describe("PluralCategoryUtils.getPluralCategory", function()
+	-- CLDR's samples for each category, as fraction digits written ("" for a whole number)
+	local SAMPLES: { [string]: { { any } } } = {
+		en = { { 1, "", "one" }, { 0, "", "other" }, { 2, "", "other" }, { 1, "0", "other" }, { 1.5, "5", "other" } },
+		de = { { 1, "", "one" }, { 2, "", "other" }, { 1, "0", "other" } },
+		es = { { 1, "", "one" }, { 1, "0", "one" }, { 2, "", "other" }, { 1000000, "", "many" }, { 0.5, "5", "other" } },
+		fr = { { 0, "", "one" }, { 1, "", "one" }, { 1.5, "5", "one" }, { 2, "", "other" }, { 1000000, "", "many" } },
+		pt = { { 0, "", "one" }, { 1.5, "5", "one" }, { 2, "", "other" }, { 2000000, "", "many" } },
+		it = { { 1, "", "one" }, { 1, "0", "other" }, { 2, "", "other" }, { 1000000, "", "many" } },
+		ru = {
+			{ 1, "", "one" },
+			{ 21, "", "one" },
+			{ 2, "", "few" },
+			{ 24, "", "few" },
+			{ 0, "", "many" },
+			{ 5, "", "many" },
+			{ 11, "", "many" },
+			{ 12, "", "many" },
+			{ 1.5, "5", "other" },
+		},
+		pl = {
+			{ 1, "", "one" },
+			{ 2, "", "few" },
+			{ 22, "", "few" },
+			{ 0, "", "many" },
+			{ 5, "", "many" },
+			{ 21, "", "many" },
+			{ 12, "", "many" },
+			{ 1.5, "5", "other" },
+		},
+		tr = { { 1, "", "one" }, { 2, "", "other" }, { 1, "0", "one" } },
+		vi = { { 0, "", "one" }, { 1, "", "one" }, { 0.5, "5", "one" }, { 2, "", "other" } },
+		ar = {
+			{ 0, "", "zero" },
+			{ 1, "", "one" },
+			{ 2, "", "two" },
+			{ 3, "", "few" },
+			{ 103, "", "few" },
+			{ 11, "", "many" },
+			{ 99, "", "many" },
+			{ 100, "", "other" },
+			{ 102, "", "other" },
+			{ 1.5, "5", "other" },
+		},
+		id = { { 1, "", "other" } },
+		th = { { 1, "", "other" } },
+		ja = { { 1, "", "other" } },
+		ko = { { 1, "", "other" } },
+		["zh-cn"] = { { 1, "", "other" } },
+		["zh-tw"] = { { 1, "", "other" } },
+	}
+
+	it("follows CLDR's rule for every shipped language", function()
+		for locale, samples in SAMPLES do
+			for _, sample in samples do
+				local fraction = if sample[2] == "" then nil else sample[2]
+				local category = PluralCategoryUtils.getPluralCategory(locale, sample[1], fraction)
+				if category ~= sample[3] then
+					error(string.format("%s %s: expected %s, got %s", locale, tostring(sample[1]), sample[3], category))
+				end
+			end
+		end
+	end)
+end)

package/src/Shared/Logarithmic/DecibelUtils.lua

@@ -0,0 +1,72 @@
+--!strict
+--[=[
+	Converts between linear ratios and decibels. A decibel value is a logarithm, so it is a plain number here rather
+	than a [MetricUnit]: decibel gains add where linear ratios multiply, which does not fit MetricUnit's arithmetic.
+
+	Amplitude ratios (a signal's level, such as a voltage or a sample value) use 20 × log10; power ratios use
+	10 × log10. Halving the amplitude is about -6 dB; halving the power is about -3 dB.
+
+	```lua
+	DecibelUtils.amplitudeToDecibels(0.5) -- -6.0206
+	DecibelUtils.decibelsToAmplitude(-6) -- 0.5012
+	DecibelUtils.powerToDecibels(2) -- 3.0103
+	```
+
+	Check which kind a property is before converting: a volume that scales a signal is an amplitude ratio.
+
+	@class DecibelUtils
+]=]
+
+local DecibelUtils = {}
+
+--[=[
+	The decibels of an amplitude ratio: `20 × log10(ratio)`. A ratio of 0 is negative infinity (silence).
+
+	@param ratio number -- 1 is unchanged
+	@return number
+]=]
+function DecibelUtils.amplitudeToDecibels(ratio: number): number
+	assert(type(ratio) == "number" and ratio >= 0, "Bad ratio")
+	if ratio == 0 then
+		return -math.huge
+	end
+	return 20 * math.log10(ratio)
+end
+
+--[=[
+	The amplitude ratio of a decibel gain: `10 ^ (decibels / 20)`.
+
+	@param decibels number -- 0 is unchanged
+	@return number
+]=]
+function DecibelUtils.decibelsToAmplitude(decibels: number): number
+	assert(type(decibels) == "number", "Bad decibels")
+	return 10 ^ (decibels / 20)
+end
+
+--[=[
+	The decibels of a power ratio: `10 × log10(ratio)`. A ratio of 0 is negative infinity.
+
+	@param ratio number -- 1 is unchanged
+	@return number
+]=]
+function DecibelUtils.powerToDecibels(ratio: number): number
+	assert(type(ratio) == "number" and ratio >= 0, "Bad ratio")
+	if ratio == 0 then
+		return -math.huge
+	end
+	return 10 * math.log10(ratio)
+end
+
+--[=[
+	The power ratio of a decibel gain: `10 ^ (decibels / 10)`.
+
+	@param decibels number -- 0 is unchanged
+	@return number
+]=]
+function DecibelUtils.decibelsToPower(decibels: number): number
+	assert(type(decibels) == "number", "Bad decibels")
+	return 10 ^ (decibels / 10)
+end
+
+return table.freeze(DecibelUtils)

package/src/Shared/Logarithmic/DecibelUtils.spec.lua

@@ -0,0 +1,35 @@
+--!strict
+--[[
+	@class DecibelUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local DecibelUtils = require("DecibelUtils")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("DecibelUtils", function()
+	it("uses 20 log10 for amplitude ratios", function()
+		expect(DecibelUtils.amplitudeToDecibels(1)).toBe(0)
+		expect(DecibelUtils.amplitudeToDecibels(10)).toBeCloseTo(20, 9)
+		expect(DecibelUtils.amplitudeToDecibels(0.5)).toBeCloseTo(-6.0206, 4)
+		expect(DecibelUtils.decibelsToAmplitude(-20)).toBeCloseTo(0.1, 12)
+		expect(DecibelUtils.amplitudeToDecibels(0)).toBe(-math.huge)
+	end)
+
+	it("uses 10 log10 for power ratios", function()
+		expect(DecibelUtils.powerToDecibels(10)).toBeCloseTo(10, 9)
+		expect(DecibelUtils.powerToDecibels(2)).toBeCloseTo(3.0103, 4)
+		expect(DecibelUtils.decibelsToPower(-10)).toBeCloseTo(0.1, 12)
+	end)
+
+	it("round trips, and adds gains where ratios multiply", function()
+		expect(DecibelUtils.decibelsToAmplitude(DecibelUtils.amplitudeToDecibels(0.37))).toBeCloseTo(0.37, 12)
+		local gain = DecibelUtils.amplitudeToDecibels(0.5) + DecibelUtils.amplitudeToDecibels(0.5)
+		expect(DecibelUtils.decibelsToAmplitude(gain)).toBeCloseTo(0.25, 12)
+	end)
+end)

package/src/Shared/MetricUnit.Angles.spec.lua

@@ -0,0 +1,80 @@
+--!strict
+--[[
+	@class MetricUnit.Angles.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
+
+-- Formatting puts a no-break space between a number and its unit; these compare it as a plain space
+local function plain(text: string): string
+	return (string.gsub(text, "\u{00A0}", " "))
+end
+
+local function format(value: any, options: MetricUnit.FormatOptions?): string
+	return plain(MetricUnit.format(value, options))
+end
+
+describe("MetricUnit angles", function()
+	it("converts between radians, degrees and revolutions", function()
+		expect(MetricUnit.degrees(180):In("radian")).toBeCloseTo(math.pi, 12)
+		expect(MetricUnit.new(1, "revolution"):In("degree")).toBeCloseTo(360, 9)
+		expect(MetricUnit.fuzzyEq(MetricUnit.radians(math.pi), MetricUnit.degrees(180))).toBe(true)
+		-- The bridge to CFrame.Angles and math.sin is reading radians
+		expect(MetricUnit.degrees(90):In("radian")).toBeCloseTo(math.rad(90), 12)
+		expect(MetricUnit.radians(math.rad(30)):In("degree")).toBeCloseTo(30, 9)
+		expect(MetricUnit.degrees(1):GetKind()).toBe("angle")
+	end)
+
+	it("keeps angles apart from lengths", function()
+		expect(function()
+			local _ = MetricUnit.degrees(1) + MetricUnit.meters(1)
+		end).toThrow("cannot add angle and length")
+		expect(MetricUnit.sameDimension(MetricUnit.radians(1), MetricUnit.none(1))).toBe(false)
+	end)
+
+	it("reads angular velocity and acceleration", function()
+		expect(MetricUnit.new(60, "revolutionPerMinute"):In("radianPerSecond")).toBeCloseTo(2 * math.pi, 9)
+		expect(MetricUnit.new(360, "degreePerSecond"):In("revolutionPerMinute")).toBeCloseTo(60, 9)
+		expect((MetricUnit.degrees(90) / MetricUnit.seconds(1)):GetKind()).toBe("angularVelocity")
+		local spinUp = MetricUnit.new(4, "radianPerSecond") / MetricUnit.seconds(2)
+		expect(spinUp:GetKind()).toBe("angularAcceleration")
+		expect(spinUp:In("radianPerSecondSquared")).toBe(2)
+	end)
+
+	it("turns an angle into an arc length, and an angular speed into a speed", function()
+		expect(MetricUnit.arcLength(MetricUnit.degrees(180), MetricUnit.meters(2)):In("meter")).toBeCloseTo(
+			2 * math.pi,
+			9
+		)
+		local rim = MetricUnit.arcLength(MetricUnit.new(60, "revolutionPerMinute"), MetricUnit.meters(1))
+		expect(rim:GetKind()).toBe("speed")
+		expect(rim:In("meterPerSecond")).toBeCloseTo(2 * math.pi, 9)
+		expect(function()
+			MetricUnit.arcLength(MetricUnit.meters(1), MetricUnit.meters(1))
+		end).toThrow("takes an angle or an angle per time, not length")
+	end)
+
+	it("formats angles in degrees by default", function()
+		expect(format(MetricUnit.degrees(45))).toBe("45°")
+		expect(format(MetricUnit.radians(1))).toBe("57.296°")
+		expect(format(MetricUnit.radians(1), { unit = "radian" })).toBe("1 rad")
+		expect(format(MetricUnit.degrees(2), { unitDisplay = "long" })).toBe("2 degrees")
+		expect(format(MetricUnit.degrees(1), { unitDisplay = "long" })).toBe("1 degree")
+		expect(format(MetricUnit.new(60, "revolutionPerMinute"))).toBe("360 °/s")
+		expect(format(MetricUnit.new(60, "revolutionPerMinute"), { unit = "revolutionPerMinute" })).toBe("60 rpm")
+		expect(tostring(MetricUnit.degrees(45))).toBe("45°")
+	end)
+end)
+
+describe("MetricUnit.arcLength with a plain zero radius", function()
+	it("is zero", function()
+		expect(MetricUnit.arcLength(MetricUnit.degrees(90), 0 :: any):In("meter")).toBe(0)
+	end)
+end)

package/src/Shared/MetricUnit.Customary.spec.lua

@@ -0,0 +1,104 @@
+--!strict
+--[[
+	@class MetricUnit.Customary.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+local MetricUnitSystems = require("MetricUnitSystems")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function format(value: any, options: any?): string
+	return (string.gsub(MetricUnit.format(value, options), "\u{00A0}", " "))
+end
+
+describe("MetricUnit US customary and British imperial", function()
+	it("keeps US and imperial volumes apart", function()
+		expect(MetricUnit.new(1, "usGallon"):In("liter")).toBeCloseTo(3.785411784, 9)
+		expect(MetricUnit.new(1, "imperialGallon"):In("liter")).toBeCloseTo(4.54609, 9)
+		expect(MetricUnit.new(1, "imperialPint"):In("usPint")).toBeCloseTo(1.20095, 5)
+		expect(MetricUnit.new(1, "usCup"):In("usTablespoon")).toBeCloseTo(16, 9)
+		expect(MetricUnit.new(1, "usTablespoon"):In("usTeaspoon")).toBeCloseTo(3, 9)
+		expect(MetricUnit.new(1, "imperialPint"):In("imperialFluidOunce")).toBeCloseTo(20, 9)
+	end)
+
+	it("shows each system's units for a value that asks for it", function()
+		local volume = MetricUnit.new(2, "liter")
+		expect(format(volume:ToUSCustomary())).toBe("2.113 US qt")
+		expect(format(volume:ToImperial())).toBe("3.52 imp pt")
+		expect(format(MetricUnit.new(250, "milliliter"):ToUSCustomary())).toBe("1.057 cups")
+		expect(format(MetricUnit.new(5, "milliliter"):ToUSCustomary())).toBe("1.014 tsp")
+
+		local body = MetricUnit.kilograms(80)
+		expect(format(body:ToUSCustomary())).toBe("176.37 lb")
+		expect(format(body:ToImperial())).toBe("12.598 st")
+		expect(format(MetricUnit.new(2, "tonne"):ToUSCustomary())).toBe("2.205 tn")
+
+		local distance = MetricUnit.kilometers(5)
+		expect(format(distance:ToUSCustomary())).toBe("3.107 mi")
+		expect(format(distance:ToImperial())).toBe("3.107 mi")
+		expect(distance:ToImperial():GetDisplaySystem()).toBe(MetricUnitSystems.IMPERIAL)
+	end)
+
+	it("covers areas, volumes and densities in feet and inches", function()
+		expect(MetricUnit.new(1, "squareMile"):In("acre")).toBeCloseTo(640, 9)
+		expect(MetricUnit.new(1, "cubicFoot"):In("cubicInch")).toBeCloseTo(1728, 9)
+		expect(MetricUnit.new(1, "cubicYard"):In("cubicFoot")).toBeCloseTo(27, 9)
+		expect(MetricUnit.new(1, "usGallon"):In("cubicInch")).toBeCloseTo(231, 9)
+		expect(MetricUnit.new(62.428, "poundPerCubicFoot"):In("kilogramPerCubicMeter")).toBeCloseTo(1000, 2)
+		expect(MetricUnit.new(1, "nauticalMile"):In("meter")).toBe(1852)
+	end)
+end)
+
+describe("MetricUnit for cars", function()
+	it("converts horsepower, torque and fuel economy", function()
+		expect(MetricUnit.new(1, "horsepower"):In("watt")).toBeCloseTo(745.6999, 4)
+		expect(MetricUnit.new(1, "metricHorsepower"):In("watt")).toBeCloseTo(735.49875, 9)
+		expect(format(MetricUnit.new(100, "kilowatt"):ToUSCustomary())).toBe("134.102 hp")
+
+		local torque = MetricUnit.new(300, "poundFoot")
+		expect(torque:In("newtonMeter")).toBeCloseTo(406.7454, 4)
+		expect(format(torque:As("newtonMeter"))).toBe("406.745 N·m")
+
+		local economy = MetricUnit.new(30, "milePerUsGallon")
+		expect(economy:GetKind()).toBe("fuelEconomy")
+		expect(economy:In("kilometerPerLiter")).toBeCloseTo(12.7543, 4)
+		expect(economy:In("milePerImperialGallon")).toBeCloseTo(36.0285, 4)
+		expect((1 / economy):In("literPer100Kilometers")).toBeCloseTo(7.8405, 4)
+		expect(format(economy:ToImperial())).toBe("36.028 mpg (UK)")
+		expect(format(economy)).toBe("30 mpg (US)")
+		expect(format(economy:ToMetric())).toBe("12.754 km/L")
+	end)
+
+	it("derives fuel economy from a distance and the fuel it used", function()
+		local economy = MetricUnit.new(300, "mile") / MetricUnit.new(10, "usGallon")
+		expect(economy:In("milePerUsGallon")).toBeCloseTo(30, 9)
+		expect(format(economy:ToUSCustomary())).toBe("30 mpg (US)")
+	end)
+
+	it("converts BTU, psi, inches of mercury and Rankine", function()
+		expect(MetricUnit.new(1, "britishThermalUnit"):In("joule")).toBeCloseTo(1055.05585262, 9)
+		expect(MetricUnit.new(29.92, "inchOfMercury"):In("kilopascal")).toBeCloseTo(101.32, 2)
+		expect(MetricUnit.new(32, "poundForcePerSquareInch"):In("kilopascal")).toBeCloseTo(220.632, 3)
+		expect(MetricUnit.point(491.67, "rankine"):In("celsius")).toBeCloseTo(0, 9)
+		expect(MetricUnit.new(10, "footPerSecondSquared"):In("meterPerSecondSquared")).toBeCloseTo(3.048, 9)
+	end)
+
+	it("parses car units as they are written", function()
+		local function parse(text: string): MetricUnit.MetricUnit
+			return assert(MetricUnit.parse(text)) :: any
+		end
+		expect(parse("300 hp"):In("horsepower")).toBe(300)
+		expect(parse("400 Nm"):In("newtonMeter")).toBe(400)
+		expect(parse("300 lb-ft"):In("poundFoot")).toBe(300)
+		expect(parse("30 mpg"):In("milePerUsGallon")).toBe(30)
+		expect(parse("12000 BTU"):In("britishThermalUnit")).toBe(12000)
+		expect(parse("2 cups"):In("usCup")).toBe(2)
+		expect(parse("150 PS"):In("metricHorsepower")).toBe(150)
+	end)
+end)

package/src/Shared/MetricUnit.Derived.spec.lua

@@ -0,0 +1,173 @@
+--!strict
+--[[
+	@class MetricUnit.Derived.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
+
+describe("MetricUnit prefixed base units", function()
+	it("reads milliseconds and microseconds back", function()
+		expect(MetricUnit.milliseconds(250):In("millisecond")).toBeCloseTo(250, 9)
+		expect(MetricUnit.new(40, "microsecond"):In("microsecond")).toBeCloseTo(40, 9)
+		expect(MetricUnit.milliseconds(1_500):InSeconds()).toBeCloseTo(1.5, 9)
+		expect(MetricUnit.new(1_000, "microsecond"):In("millisecond")).toBeCloseTo(1, 9)
+	end)
+
+	it("keeps decimal and binary memory apart", function()
+		expect(MetricUnit.new(1, "gigabyte"):In("megabyte")).toBe(1_000)
+		expect(MetricUnit.new(1, "kibibyte"):In("byte")).toBe(1_024)
+		expect(MetricUnit.new(4, "mebibyte"):In("byte")).toBe(4_194_304)
+		expect(MetricUnit.new(1, "gibibyte"):In("mebibyte")).toBe(1_024)
+		expect(MetricUnit.new(1, "mebibyte"):In("kibibyte")).toBe(1_024)
+		expect(MetricUnit.new(1, "gigabyte"):In("gibibyte")).toBeCloseTo(0.9313, 4)
+		expect(MetricUnit.new(1, "kibibyte"):In("kilobyte")).toBeCloseTo(1.024, 9)
+	end)
+
+	it("reads milligrams back", function()
+		expect(MetricUnit.new(500, "milligram"):In("gram")).toBeCloseTo(0.5, 9)
+		expect(MetricUnit.grams(2):In("milligram")).toBeCloseTo(2_000, 9)
+	end)
+
+	it("reads a rate per minute and a frequency in hertz", function()
+		expect(MetricUnit.new(120, "perMinute"):In("perSecond")).toBeCloseTo(2, 9)
+		expect(MetricUnit.perSecond(1):In("perMinute")).toBeCloseTo(60, 9)
+		expect(MetricUnit.new(60, "hertz"):In("hertz")).toBe(60)
+		expect(MetricUnit.new(1, "hertz") == MetricUnit.perSecond(1)).toBe(true)
+		expect((1 / MetricUnit.milliseconds(20)):In("hertz")).toBeCloseTo(50, 9)
+	end)
+end)
+
+describe("MetricUnit area and volume", function()
+	it("reads areas back, from lengths multiplied", function()
+		expect(MetricUnit.new(50, "squareMeter"):In("squareMeter")).toBe(50)
+		expect(MetricUnit.new(1, "hectare"):In("squareMeter")).toBe(10_000)
+		expect(MetricUnit.squareKilometers(1):In("hectare")).toBe(100)
+		expect((MetricUnit.meters(100) * MetricUnit.meters(100)):In("hectare")).toBeCloseTo(1, 9)
+		expect(MetricUnit.isKind(MetricUnit.kilometers(2) * MetricUnit.kilometers(3), "area")).toBe(true)
+		expect((MetricUnit.kilometers(2) * MetricUnit.kilometers(3)):In("squareKilometer")).toBeCloseTo(6, 9)
+	end)
+
+	it("reads volumes back, from areas and lengths multiplied", function()
+		expect(MetricUnit.new(1, "liter"):In("milliliter")).toBeCloseTo(1_000, 9)
+		expect(MetricUnit.new(1, "cubicMeter"):In("liter")).toBeCloseTo(1_000, 9)
+		expect(MetricUnit.new(250, "milliliter"):In("liter")).toBeCloseTo(0.25, 9)
+		expect(MetricUnit.isKind(MetricUnit.pow(MetricUnit.new(10, "centimeter"), 3), "volume")).toBe(true)
+		expect(MetricUnit.pow(MetricUnit.new(10, "centimeter"), 3):In("liter")).toBeCloseTo(1, 9)
+		expect(MetricUnit.isKind(MetricUnit.new(2, "squareMeter") * MetricUnit.meters(3), "volume")).toBe(true)
+	end)
+end)
+
+describe("MetricUnit mechanics", function()
+	it("reads speeds in m/s and km/h", function()
+		expect(MetricUnit.new(10, "meterPerSecond"):In("kilometerPerHour")).toBeCloseTo(36, 9)
+		expect(MetricUnit.new(36, "kilometerPerHour"):In("meterPerSecond")).toBeCloseTo(10, 9)
+		expect((MetricUnit.kilometers(36) / MetricUnit.hours(1)):In("meterPerSecond")).toBeCloseTo(10, 9)
+		expect(MetricUnit.isKind(MetricUnit.new(1, "kilometerPerHour"), "speed")).toBe(true)
+	end)
+
+	it("makes an acceleration from a speed over a time", function()
+		local acceleration = MetricUnit.new(20, "meterPerSecond") / MetricUnit.seconds(2)
+		expect(MetricUnit.isKind(acceleration, "acceleration")).toBe(true)
+		expect(acceleration:In("meterPerSecondSquared")).toBeCloseTo(10, 9)
+		expect(MetricUnit.new(9.81, "meterPerSecondSquared"):In("meterPerSecondSquared")).toBe(9.81)
+	end)
+
+	it("makes a newton from a mass times an acceleration", function()
+		local force = MetricUnit.kilograms(2) * MetricUnit.new(3, "meterPerSecondSquared")
+		expect(MetricUnit.isKind(force, "force")).toBe(true)
+		expect(force:In("newton")).toBeCloseTo(6, 9)
+		expect(force == MetricUnit.new(6, "newton")).toBe(true)
+	end)
+
+	it("makes energy from a force over a length, and power from energy over time", function()
+		local work = MetricUnit.new(10, "newton") * MetricUnit.meters(5)
+		expect(MetricUnit.isKind(work, "energy")).toBe(true)
+		expect(work:In("joule")).toBeCloseTo(50, 9)
+
+		local power = work / MetricUnit.seconds(2)
+		expect(MetricUnit.isKind(power, "power")).toBe(true)
+		expect(power:In("watt")).toBeCloseTo(25, 9)
+
+		expect((MetricUnit.new(2, "kilowatt") * MetricUnit.hours(3)):In("kilowattHour")).toBeCloseTo(6, 9)
+		expect((MetricUnit.new(3, "kilowattHour") / MetricUnit.hours(1)):In("kilowatt")).toBeCloseTo(3, 9)
+	end)
+
+	it("converts between energy units", function()
+		expect(MetricUnit.new(1, "kilojoule"):In("joule")).toBe(1_000)
+		expect(MetricUnit.new(1, "kilowattHour"):In("kilojoule")).toBe(3_600)
+		expect(MetricUnit.new(1, "kilocalorie"):In("joule")).toBe(4_184)
+		expect(MetricUnit.new(4_184, "joule"):In("kilocalorie")).toBe(1)
+	end)
+
+	it("makes pressure from a force over an area", function()
+		local pressure = MetricUnit.new(1_000, "newton") / MetricUnit.new(2, "squareMeter")
+		expect(MetricUnit.isKind(pressure, "pressure")).toBe(true)
+		expect(pressure:In("pascal")).toBeCloseTo(500, 9)
+		expect(MetricUnit.new(1, "bar"):In("kilopascal")).toBe(100)
+		expect(MetricUnit.new(250, "kilopascal"):In("bar")).toBeCloseTo(2.5, 9)
+	end)
+
+	it("makes density from a mass over a volume", function()
+		local density = MetricUnit.kilograms(1) / MetricUnit.new(1, "liter")
+		expect(MetricUnit.isKind(density, "density")).toBe(true)
+		expect(density:In("kilogramPerCubicMeter")).toBeCloseTo(1_000, 9)
+		expect(density:In("gramPerCubicCentimeter")).toBeCloseTo(1, 9)
+		expect(MetricUnit.new(7.8, "gramPerCubicCentimeter"):In("kilogramPerCubicMeter")).toBeCloseTo(7_800, 9)
+		expect((MetricUnit.new(1_000, "kilogramPerCubicMeter") * MetricUnit.new(2, "liter")):In("kilogram")).toBeCloseTo(
+			2,
+			9
+		)
+	end)
+end)
+
+describe("MetricUnit data rates", function()
+	it("makes a data rate from memory over time", function()
+		local rate = MetricUnit.kilobytes(50) / MetricUnit.seconds(1)
+		expect(MetricUnit.isKind(rate, "dataRate")).toBe(true)
+		expect(rate:In("kilobytePerSecond")).toBeCloseTo(50, 9)
+		expect(MetricUnit.new(2_000, "bytePerSecond"):In("kilobytePerSecond")).toBe(2)
+		expect((MetricUnit.new(8, "kilobytePerSecond") * MetricUnit.minutes(1)):In("kilobyte")).toBeCloseTo(480, 9)
+	end)
+end)
+
+describe("MetricUnit derived boundaries", function()
+	it("tells derived dimensions apart", function()
+		expect(MetricUnit.isKind(MetricUnit.new(1, "newton"), "energy")).toBe(false)
+		expect(MetricUnit.isKind(MetricUnit.new(1, "joule"), "force")).toBe(false)
+		expect(MetricUnit.isKind(MetricUnit.new(1, "joule"), "power")).toBe(false)
+		expect(MetricUnit.isKind(MetricUnit.new(1, "liter"), "area")).toBe(false)
+		expect(MetricUnit.isKind(MetricUnit.perSecond(1), "dataRate")).toBe(false)
+		expect(MetricUnit.isKind(MetricUnit.new(1, "meterPerSecondSquared"), "speed")).toBe(false)
+	end)
+
+	it("errors when a derived reader meets another dimension, naming both", function()
+		expect(function()
+			MetricUnit.new(1, "joule"):In("watt")
+		end).toThrow('In("watt") reads length^2·mass/time^3, not length^2·mass/time^2')
+		expect(function()
+			MetricUnit.new(1, "newton"):In("pascal")
+		end).toThrow('In("pascal") reads mass/length/time^2, not length·mass/time^2')
+	end)
+
+	it("expects each derived dimension by name", function()
+		expect(MetricUnit.expect(MetricUnit.new(1, "hectare"), "area", "plot")).toBe(10_000)
+		expect(MetricUnit.expect(MetricUnit.new(1, "liter"), "volume", "tank")).toBeCloseTo(1e-3, 12)
+		expect(MetricUnit.expect(MetricUnit.new(9.81, "meterPerSecondSquared"), "acceleration", "gravity")).toBe(9.81)
+		expect(MetricUnit.expect(MetricUnit.new(5, "newton"), "force", "thrust")).toBe(5)
+		expect(MetricUnit.expect(MetricUnit.new(2, "kilojoule"), "energy", "charge")).toBe(2_000)
+		expect(MetricUnit.expect(MetricUnit.new(1, "kilowatt"), "power", "output")).toBe(1_000)
+		expect(MetricUnit.expect(MetricUnit.new(2, "bar"), "pressure", "tyre")).toBe(200_000)
+		expect(MetricUnit.expect(MetricUnit.new(997, "kilogramPerCubicMeter"), "density", "water")).toBe(997)
+		expect(MetricUnit.expect(MetricUnit.new(1, "kilobytePerSecond"), "dataRate", "budget")).toBe(1_000)
+		expect(function()
+			MetricUnit.expect(MetricUnit.new(1, "joule"), "power", "output")
+		end).toThrow("MetricUnit.expect: output expects length^2·mass/time^3, got length^2·mass/time^2")
+	end)
+end)