units

package
v1.8.13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 17, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package units provides canonical unit name mappings based on UCUM and NIST standards. This ensures CalcMark supports both SI units and US customary units with standard abbreviations and full names.

Index

Constants

View Source 
const CategoryCurrency = "Currency"

Categories returns the sorted list of unit categories derived from StandardUnits and the DataSize conversion category. This is the single source of truth — frontmatter validation uses this instead of a hardcoded map. CategoryCurrency is the category name for currency values ($, €, £, ¥). Currency is NOT derived from StandardUnits — it's a standalone type that can opt in to scaling via unit_categories: [Currency].

View Source 
const CategoryCustom = "Custom"

CategoryCustom is the category name for custom units (e.g., "bananas", "eggs"). Custom units are not in StandardUnits and have no system mapping. They must be explicitly listed in unit_categories to participate in scaling.

View Source 
const CategoryDataSize = "DataSize"

CategoryDataSize is the category name for data size units (bytes, bits, etc.).

View Source 
const CategoryNumber = "Number"

CategoryNumber is the category name for plain numeric values (no unit). Like Currency, Number is not derived from StandardUnits and must be explicitly listed in unit_categories to participate in scaling.

Variables

View Source 
var StandardUnits = map[string]UnitMapping{

	"meter": {
		Canonical:   "meter",
		Symbol:      "m",
		Aliases:     []string{"meter", "meters", "metre", "metres", "m"},
		System:      "SI",
		Quantity:    "Length",
		Description: "SI base unit of length",
	},
	"millimeter": {
		Canonical:   "millimeter",
		Symbol:      "mm",
		Aliases:     []string{"millimeter", "millimeters", "millimetre", "millimetres", "mm"},
		System:      "SI",
		Quantity:    "Length",
		Description: "0.001 meters",
	},
	"centimeter": {
		Canonical:   "centimeter",
		Symbol:      "cm",
		Aliases:     []string{"centimeter", "centimeters", "centimetre", "centimetres", "cm"},
		System:      "SI",
		Quantity:    "Length",
		Description: "0.01 meters",
	},
	"kilometer": {
		Canonical:   "kilometer",
		Symbol:      "km",
		Aliases:     []string{"kilometer", "kilometers", "kilometre", "kilometres", "km"},
		System:      "SI",
		Quantity:    "Length",
		Description: "1000 meters",
	},

	"inch": {
		Canonical:   "inch",
		Symbol:      "in",
		Aliases:     []string{"inch", "inches", "in"},
		System:      "US_Customary",
		Quantity:    "Length",
		Description: "1/12 foot, 0.0254 meters",
	},
	"foot": {
		Canonical:   "foot",
		Symbol:      "ft",
		Aliases:     []string{"foot", "feet", "ft"},
		System:      "US_Customary",
		Quantity:    "Length",
		Description: "12 inches, 0.3048 meters",
	},
	"yard": {
		Canonical:   "yard",
		Symbol:      "yd",
		Aliases:     []string{"yard", "yards", "yd"},
		System:      "US_Customary",
		Quantity:    "Length",
		Description: "3 feet, 0.9144 meters",
	},
	"mile": {
		Canonical:   "mile",
		Symbol:      "mi",
		Aliases:     []string{"mile", "miles", "mi"},
		System:      "US_Customary",
		Quantity:    "Length",
		Description: "5280 feet, 1609.344 meters",
	},
	"nautical mile": {
		Canonical:   "nautical mile",
		Symbol:      "nmi",
		Aliases:     []string{"nautical mile", "nautical miles", "nmi"},
		System:      "International",
		Quantity:    "Length",
		Description: "1852 meters (international standard)",
	},

	"gram": {
		Canonical:   "gram",
		Symbol:      "g",
		Aliases:     []string{"gram", "grams", "g"},
		System:      "SI",
		Quantity:    "Mass",
		Description: "0.001 kilograms",
	},
	"milligram": {
		Canonical:   "milligram",
		Symbol:      "mg",
		Aliases:     []string{"milligram", "milligrams", "mg"},
		System:      "SI",
		Quantity:    "Mass",
		Description: "0.000001 kilograms",
	},
	"kilogram": {
		Canonical:   "kilogram",
		Symbol:      "kg",
		Aliases:     []string{"kilogram", "kilograms", "kg"},
		System:      "SI",
		Quantity:    "Mass",
		Description: "SI base unit of mass, 1000 grams",
	},
	"metric ton": {
		Canonical:   "metric ton",
		Symbol:      "t",
		Aliases:     []string{"metric ton", "metric tons", "tonne", "tonnes", "t"},
		System:      "SI",
		Quantity:    "Mass",
		Description: "1000 kilograms",
	},

	"ounce": {
		Canonical:   "ounce",
		Symbol:      "oz",
		Aliases:     []string{"ounce", "ounces", "oz", "us oz"},
		System:      "US_Customary",
		Quantity:    "Mass",
		Description: "Standard (avoirdupois) ounce, 1/16 pound, 28.349523125 grams",
	},
	"pound": {
		Canonical:   "pound",
		Symbol:      "lb",
		Aliases:     []string{"pound", "pounds", "lb", "lbs", "us lb"},
		System:      "US_Customary",
		Quantity:    "Mass",
		Description: "Standard (avoirdupois) pound, 453.59237 grams",
	},

	"troy ounce": {
		Canonical:   "troy ounce",
		Symbol:      "troy oz",
		Aliases:     []string{"troy ounce", "troy ounces", "troy oz"},
		System:      "Troy",
		Quantity:    "Mass",
		Description: "Troy ounce, used for precious metals, 31.1035 grams",
	},
	"troy pound": {
		Canonical:   "troy pound",
		Symbol:      "troy lb",
		Aliases:     []string{"troy pound", "troy pounds", "troy lb"},
		System:      "Troy",
		Quantity:    "Mass",
		Description: "Troy pound, 12 troy ounces, 373.2417 grams",
	},

	"short ton": {
		Canonical:   "short ton",
		Symbol:      "short ton",
		Aliases:     []string{"short ton", "short tons"},
		System:      "US_Customary",
		Quantity:    "Mass",
		Description: "US short ton, 2000 pounds, 907.185 kg",
	},
	"long ton": {
		Canonical:   "long ton",
		Symbol:      "long ton",
		Aliases:     []string{"long ton", "long tons"},
		System:      "Imperial",
		Quantity:    "Mass",
		Description: "Imperial long ton, 2240 pounds, 1016.047 kg",
	},

	"milliliter": {
		Canonical:   "milliliter",
		Symbol:      "ml",
		Aliases:     []string{"milliliter", "milliliters", "millilitre", "millilitres", "ml"},
		System:      "SI",
		Quantity:    "Volume",
		Description: "0.001 liters, 1 cubic centimeter",
	},
	"liter": {
		Canonical:   "liter",
		Symbol:      "l",
		Aliases:     []string{"liter", "liters", "litre", "litres", "l"},
		System:      "SI",
		Quantity:    "Volume",
		Description: "SI base unit of volume, 1 cubic decimeter",
	},

	"teaspoon": {
		Canonical:   "teaspoon",
		Symbol:      "tsp",
		Aliases:     []string{"teaspoon", "teaspoons", "tsp"},
		System:      "US_Customary",
		Quantity:    "Volume",
		Description: "1/3 tablespoon, approximately 4.929 milliliters",
	},
	"tablespoon": {
		Canonical:   "tablespoon",
		Symbol:      "tbsp",
		Aliases:     []string{"tablespoon", "tablespoons", "tbsp"},
		System:      "US_Customary",
		Quantity:    "Volume",
		Description: "3 teaspoons, approximately 14.787 milliliters",
	},
	"cup": {
		Canonical:   "cup",
		Symbol:      "cup",
		Aliases:     []string{"cup", "cups", "us cup"},
		System:      "US_Customary",
		Quantity:    "Volume",
		Description: "US legal cup, 240 milliliters",
	},
	"fluid ounce": {
		Canonical:   "fluid ounce",
		Symbol:      "fl oz",
		Aliases:     []string{"fluid ounce", "fluid ounces", "fl oz", "us fl oz"},
		System:      "US_Customary",
		Quantity:    "Volume",
		Description: "US fluid ounce, 29.5735 milliliters",
	},
	"pint": {
		Canonical:   "pint",
		Symbol:      "pt",
		Aliases:     []string{"pint", "pints", "pt", "us pt"},
		System:      "US_Customary",
		Quantity:    "Volume",
		Description: "US liquid pint, 2 cups, 473.176 milliliters",
	},
	"quart": {
		Canonical:   "quart",
		Symbol:      "qt",
		Aliases:     []string{"quart", "quarts", "qt", "us qt"},
		System:      "US_Customary",
		Quantity:    "Volume",
		Description: "US liquid quart, 2 pints, 946.353 milliliters",
	},
	"gallon": {
		Canonical:   "gallon",
		Symbol:      "gal",
		Aliases:     []string{"gallon", "gallons", "gal", "us gal"},
		System:      "US_Customary",
		Quantity:    "Volume",
		Description: "US liquid gallon, 4 quarts, 3.785411784 liters",
	},

	"imperial gallon": {
		Canonical:   "imperial gallon",
		Symbol:      "imp gal",
		Aliases:     []string{"imperial gallon", "imperial gallons", "imp gal"},
		System:      "Imperial",
		Quantity:    "Volume",
		Description: "Imperial gallon, 4.54609 liters",
	},
	"imperial quart": {
		Canonical:   "imperial quart",
		Symbol:      "imp qt",
		Aliases:     []string{"imperial quart", "imperial quarts", "imp qt"},
		System:      "Imperial",
		Quantity:    "Volume",
		Description: "Imperial quart, 1.13652 liters",
	},
	"imperial pint": {
		Canonical:   "imperial pint",
		Symbol:      "imp pt",
		Aliases:     []string{"imperial pint", "imperial pints", "imp pt"},
		System:      "Imperial",
		Quantity:    "Volume",
		Description: "Imperial pint, 568.261 milliliters",
	},
	"imperial cup": {
		Canonical:   "imperial cup",
		Symbol:      "imp cup",
		Aliases:     []string{"imperial cup", "imperial cups", "imp cup"},
		System:      "Imperial",
		Quantity:    "Volume",
		Description: "Imperial cup, 284.131 milliliters",
	},
	"imperial fluid ounce": {
		Canonical:   "imperial fluid ounce",
		Symbol:      "imp fl oz",
		Aliases:     []string{"imperial fluid ounce", "imperial fluid ounces", "imp fl oz"},
		System:      "Imperial",
		Quantity:    "Volume",
		Description: "Imperial fluid ounce, 28.4131 milliliters",
	},

	"celsius": {
		Canonical:   "celsius",
		Symbol:      "C",
		Aliases:     []string{"celsius", "c", "°c", "degc"},
		System:      "SI",
		Quantity:    "Temperature",
		Description: "Celsius temperature scale, 0°C = freezing point of water",
	},
	"fahrenheit": {
		Canonical:   "fahrenheit",
		Symbol:      "F",
		Aliases:     []string{"fahrenheit", "f", "°f", "degf"},
		System:      "Imperial",
		Quantity:    "Temperature",
		Description: "Fahrenheit temperature scale, 32°F = freezing point of water",
	},
	"kelvin": {
		Canonical:   "kelvin",
		Symbol:      "K",
		Aliases:     []string{"kelvin", "k"},
		System:      "SI",
		Quantity:    "Temperature",
		Description: "Absolute temperature scale, 0 K = absolute zero",
	},

	"m/s": {
		Canonical:   "m/s",
		Symbol:      "m/s",
		Aliases:     []string{"m/s", "mps", "meters per second", "metres per second"},
		System:      "SI",
		Quantity:    "Speed",
		Description: "Meters per second, SI unit of speed",
	},
	"meters per second": {
		Canonical:   "m/s",
		Symbol:      "m/s",
		Aliases:     []string{"m/s", "mps", "meters per second", "metres per second"},
		System:      "SI",
		Quantity:    "Speed",
		Description: "Meters per second, SI unit of speed",
	},
	"km/h": {
		Canonical:   "km/h",
		Symbol:      "km/h",
		Aliases:     []string{"km/h", "kph", "kmh", "kilometers per hour", "kilometres per hour"},
		System:      "SI",
		Quantity:    "Speed",
		Description: "Kilometers per hour",
	},
	"kilometers per hour": {
		Canonical:   "km/h",
		Symbol:      "km/h",
		Aliases:     []string{"km/h", "kph", "kmh", "kilometers per hour", "kilometres per hour"},
		System:      "SI",
		Quantity:    "Speed",
		Description: "Kilometers per hour",
	},
	"mph": {
		Canonical:   "mph",
		Symbol:      "mph",
		Aliases:     []string{"mph", "miles per hour"},
		System:      "Imperial",
		Quantity:    "Speed",
		Description: "Miles per hour",
	},
	"miles per hour": {
		Canonical:   "mph",
		Symbol:      "mph",
		Aliases:     []string{"mph", "miles per hour"},
		System:      "Imperial",
		Quantity:    "Speed",
		Description: "Miles per hour",
	},
	"knot": {
		Canonical:   "knot",
		Symbol:      "knot",
		Aliases:     []string{"knot", "knots"},
		System:      "Nautical",
		Quantity:    "Speed",
		Description: "Nautical mile per hour, 1 knot = 1.852 km/h",
	},

	"joule": {
		Canonical:   "joule",
		Symbol:      "J",
		Aliases:     []string{"joule", "joules", "j"},
		System:      "SI",
		Quantity:    "Energy",
		Description: "SI unit of energy, 1 joule = 1 newton-meter",
	},
	"kilojoule": {
		Canonical:   "kilojoule",
		Symbol:      "kJ",
		Aliases:     []string{"kilojoule", "kilojoules", "kj"},
		System:      "SI",
		Quantity:    "Energy",
		Description: "1000 joules",
	},
	"calorie": {
		Canonical:   "calorie",
		Symbol:      "cal",
		Aliases:     []string{"calorie", "calories", "cal"},
		System:      "CGS",
		Quantity:    "Energy",
		Description: "Thermochemical calorie, 1 cal = 4.184 J",
	},
	"kilocalorie": {
		Canonical:   "kilocalorie",
		Symbol:      "kcal",
		Aliases:     []string{"kilocalorie", "kilocalories", "kcal"},
		System:      "CGS",
		Quantity:    "Energy",
		Description: "Food calorie (Calorie), 1 kcal = 4184 J",
	},
	"kwh": {
		Canonical:   "kwh",
		Symbol:      "kWh",
		Aliases:     []string{"kwh", "kilowatt-hour", "kilowatt-hours"},
		System:      "SI",
		Quantity:    "Energy",
		Description: "Kilowatt-hour, commonly used for electricity, 1 kWh = 3.6 MJ",
	},

	"watt": {
		Canonical:   "watt",
		Symbol:      "W",
		Aliases:     []string{"watt", "watts", "w"},
		System:      "SI",
		Quantity:    "Power",
		Description: "SI unit of power, 1 watt = 1 joule/second",
	},
	"kilowatt": {
		Canonical:   "kilowatt",
		Symbol:      "kW",
		Aliases:     []string{"kilowatt", "kilowatts", "kw"},
		System:      "SI",
		Quantity:    "Power",
		Description: "1000 watts",
	},
	"megawatt": {
		Canonical:   "megawatt",
		Symbol:      "MW",
		Aliases:     []string{"megawatt", "megawatts", "mw"},
		System:      "SI",
		Quantity:    "Power",
		Description: "1 million watts",
	},
	"horsepower": {
		Canonical:   "horsepower",
		Symbol:      "hp",
		Aliases:     []string{"horsepower", "hp"},
		System:      "Imperial",
		Quantity:    "Power",
		Description: "Mechanical horsepower, 1 hp = 745.7 W",
	},

	"square meter": {
		Canonical:   "square meter",
		Symbol:      "m2",
		Aliases:     []string{"square meter", "square meters", "square metre", "square metres", "m²", "m2", "sq m"},
		System:      "SI",
		Quantity:    "Area",
		Description: "SI unit of area",
	},
	"square kilometer": {
		Canonical:   "square kilometer",
		Symbol:      "km2",
		Aliases:     []string{"square kilometer", "square kilometers", "square kilometre", "square kilometres", "km²", "km2", "sq km"},
		System:      "SI",
		Quantity:    "Area",
		Description: "1,000,000 square meters",
	},
	"square centimeter": {
		Canonical:   "square centimeter",
		Symbol:      "cm2",
		Aliases:     []string{"square centimeter", "square centimeters", "square centimetre", "square centimetres", "cm²", "cm2", "sq cm"},
		System:      "SI",
		Quantity:    "Area",
		Description: "0.0001 square meters",
	},
	"hectare": {
		Canonical:   "hectare",
		Symbol:      "ha",
		Aliases:     []string{"hectare", "hectares", "ha"},
		System:      "SI",
		Quantity:    "Area",
		Description: "10,000 square meters",
	},

	"square foot": {
		Canonical:   "square foot",
		Symbol:      "ft2",
		Aliases:     []string{"square foot", "square feet", "ft²", "ft2", "sq ft"},
		System:      "Imperial",
		Quantity:    "Area",
		Description: "0.0929 square meters",
	},
	"square inch": {
		Canonical:   "square inch",
		Symbol:      "in2",
		Aliases:     []string{"square inch", "square inches", "in²", "in2", "sq in"},
		System:      "Imperial",
		Quantity:    "Area",
		Description: "0.000645 square meters",
	},
	"square yard": {
		Canonical:   "square yard",
		Symbol:      "yd2",
		Aliases:     []string{"square yard", "square yards", "yd²", "yd2", "sq yd"},
		System:      "Imperial",
		Quantity:    "Area",
		Description: "0.836 square meters",
	},
	"square mile": {
		Canonical:   "square mile",
		Symbol:      "mi2",
		Aliases:     []string{"square mile", "square miles", "mi²", "mi2", "sq mi"},
		System:      "Imperial",
		Quantity:    "Area",
		Description: "2.59 million square meters",
	},
	"acre": {
		Canonical:   "acre",
		Symbol:      "ac",
		Aliases:     []string{"acre", "acres", "ac"},
		System:      "US_Customary",
		Quantity:    "Area",
		Description: "4,047 square meters",
	},

	"newton": {
		Canonical:   "newton",
		Symbol:      "N",
		Aliases:     []string{"newton", "newtons"},
		System:      "SI",
		Quantity:    "Force",
		Description: "SI unit of force, 1 N = 1 kg·m/s²",
	},
	"kilonewton": {
		Canonical:   "kilonewton",
		Symbol:      "kN",
		Aliases:     []string{"kilonewton", "kilonewtons"},
		System:      "SI",
		Quantity:    "Force",
		Description: "1000 newtons",
	},
	"dyne": {
		Canonical:   "dyne",
		Symbol:      "dyn",
		Aliases:     []string{"dyne", "dynes"},
		System:      "CGS",
		Quantity:    "Force",
		Description: "CGS unit of force, 1 dyne = 10⁻⁵ N",
	},
	"kilogram-force": {
		Canonical:   "kilogram-force",
		Symbol:      "kgf",
		Aliases:     []string{"kilogram-force", "kilopond", "kiloponds", "kgf"},
		System:      "SI",
		Quantity:    "Force",
		Description: "Force exerted by 1 kg under standard gravity, 9.80665 N",
	},
	"pound-force": {
		Canonical:   "pound-force",
		Symbol:      "lbf",
		Aliases:     []string{"pound-force", "pound-forces", "lbf"},
		System:      "Imperial",
		Quantity:    "Force",
		Description: "Force exerted by 1 avoirdupois pound under standard gravity, 4.448222 N",
	},
	"poundal": {
		Canonical:   "poundal",
		Symbol:      "pdl",
		Aliases:     []string{"poundal", "poundals", "pdl"},
		System:      "Imperial",
		Quantity:    "Force",
		Description: "Imperial absolute unit of force, 0.138255 N",
	},

	"newton-second": {
		Canonical:   "newton-second",
		Symbol:      "N·s",
		Aliases:     []string{"newton-second", "newton-seconds"},
		System:      "SI",
		Quantity:    "Impulse",
		Description: "SI unit of impulse (force × time)",
	},
	"pound-force-second": {
		Canonical:   "pound-force-second",
		Symbol:      "lbf·s",
		Aliases:     []string{"pound-force-second", "pound-force-seconds"},
		System:      "Imperial",
		Quantity:    "Impulse",
		Description: "Imperial unit of impulse, 4.448222 N·s",
	},

	"pascal": {
		Canonical:   "pascal",
		Symbol:      "Pa",
		Aliases:     []string{"pascal", "pascals", "pa"},
		System:      "SI",
		Quantity:    "Pressure",
		Description: "SI unit of pressure, 1 Pa = 1 N/m²",
	},
	"kilopascal": {
		Canonical:   "kilopascal",
		Symbol:      "kPa",
		Aliases:     []string{"kilopascal", "kilopascals", "kpa"},
		System:      "SI",
		Quantity:    "Pressure",
		Description: "1000 pascals",
	},
	"megapascal": {
		Canonical:   "megapascal",
		Symbol:      "MPa",
		Aliases:     []string{"megapascal", "megapascals", "mpa"},
		System:      "SI",
		Quantity:    "Pressure",
		Description: "1 million pascals",
	},
	"bar": {
		Canonical:   "bar",
		Symbol:      "bar",
		Aliases:     []string{"bar", "bars"},
		System:      "SI",
		Quantity:    "Pressure",
		Description: "100,000 pascals",
	},
	"millibar": {
		Canonical:   "millibar",
		Symbol:      "mbar",
		Aliases:     []string{"millibar", "millibars", "mbar"},
		System:      "SI",
		Quantity:    "Pressure",
		Description: "100 pascals, commonly used in meteorology",
	},
	"atmosphere": {
		Canonical:   "atmosphere",
		Symbol:      "atm",
		Aliases:     []string{"atmosphere", "atmospheres", "atm"},
		System:      "SI",
		Quantity:    "Pressure",
		Description: "Standard atmosphere, 101,325 pascals",
	},
	"torr": {
		Canonical:   "torr",
		Symbol:      "Torr",
		Aliases:     []string{"torr", "torrs"},
		System:      "SI",
		Quantity:    "Pressure",
		Description: "1/760 of an atmosphere, approximately 133.322 Pa",
	},
	"psi": {
		Canonical:   "psi",
		Symbol:      "psi",
		Aliases:     []string{"psi", "pounds per square inch"},
		System:      "Imperial",
		Quantity:    "Pressure",
		Description: "Pounds per square inch, approximately 6894.76 Pa",
	},
	"pounds per square inch": {
		Canonical:   "psi",
		Symbol:      "psi",
		Aliases:     []string{"psi", "pounds per square inch"},
		System:      "Imperial",
		Quantity:    "Pressure",
		Description: "Pounds per square inch, approximately 6894.76 Pa",
	},
	"inch of mercury": {
		Canonical:   "inch of mercury",
		Symbol:      "inHg",
		Aliases:     []string{"inch of mercury", "inches of mercury", "inhg"},
		System:      "Imperial",
		Quantity:    "Pressure",
		Description: "Commonly used in aviation and weather, approximately 3386.39 Pa",
	},
	"inches of mercury": {
		Canonical:   "inch of mercury",
		Symbol:      "inHg",
		Aliases:     []string{"inch of mercury", "inches of mercury", "inhg"},
		System:      "Imperial",
		Quantity:    "Pressure",
		Description: "Commonly used in aviation and weather, approximately 3386.39 Pa",
	},

	"m/s^2": {
		Canonical:   "m/s^2",
		Symbol:      "m/s²",
		Aliases:     []string{"m/s^2", "meters per second squared"},
		System:      "SI",
		Quantity:    "Acceleration",
		Description: "SI unit of acceleration",
	},
	"meters per second squared": {
		Canonical:   "m/s^2",
		Symbol:      "m/s²",
		Aliases:     []string{"m/s^2", "meters per second squared"},
		System:      "SI",
		Quantity:    "Acceleration",
		Description: "SI unit of acceleration",
	},
	"cm/s^2": {
		Canonical:   "cm/s^2",
		Symbol:      "cm/s²",
		Aliases:     []string{"cm/s^2", "centimeters per second squared"},
		System:      "CGS",
		Quantity:    "Acceleration",
		Description: "CGS unit of acceleration",
	},
	"centimeters per second squared": {
		Canonical:   "cm/s^2",
		Symbol:      "cm/s²",
		Aliases:     []string{"cm/s^2", "centimeters per second squared"},
		System:      "CGS",
		Quantity:    "Acceleration",
		Description: "CGS unit of acceleration",
	},
	"ft/s^2": {
		Canonical:   "ft/s^2",
		Symbol:      "ft/s²",
		Aliases:     []string{"ft/s^2", "feet per second squared"},
		System:      "Imperial",
		Quantity:    "Acceleration",
		Description: "Imperial unit of acceleration",
	},
	"feet per second squared": {
		Canonical:   "ft/s^2",
		Symbol:      "ft/s²",
		Aliases:     []string{"ft/s^2", "feet per second squared"},
		System:      "Imperial",
		Quantity:    "Acceleration",
		Description: "Imperial unit of acceleration",
	},
	"standard-gravity": {
		Canonical:   "standard-gravity",
		Symbol:      "g₀",
		Aliases:     []string{"standard-gravity", "standard gravity", "standard gravities"},
		System:      "SI",
		Quantity:    "Acceleration",
		Description: "Standard acceleration due to gravity, 9.80665 m/s²",
	},
	"standard gravity": {
		Canonical:   "standard-gravity",
		Symbol:      "g₀",
		Aliases:     []string{"standard-gravity", "standard gravity", "standard gravities"},
		System:      "SI",
		Quantity:    "Acceleration",
		Description: "Standard acceleration due to gravity, 9.80665 m/s²",
	},

	"hertz": {
		Canonical:   "hertz",
		Symbol:      "Hz",
		Aliases:     []string{"hertz", "hz"},
		System:      "SI",
		Quantity:    "Frequency",
		Description: "SI unit of frequency, 1 Hz = 1 cycle per second",
	},
	"kilohertz": {
		Canonical:   "kilohertz",
		Symbol:      "kHz",
		Aliases:     []string{"kilohertz", "khz"},
		System:      "SI",
		Quantity:    "Frequency",
		Description: "1000 hertz",
	},
	"megahertz": {
		Canonical:   "megahertz",
		Symbol:      "MHz",
		Aliases:     []string{"megahertz", "mhz"},
		System:      "SI",
		Quantity:    "Frequency",
		Description: "1 million hertz",
	},
	"gigahertz": {
		Canonical:   "gigahertz",
		Symbol:      "GHz",
		Aliases:     []string{"gigahertz", "ghz"},
		System:      "SI",
		Quantity:    "Frequency",
		Description: "1 billion hertz",
	},
	"terahertz": {
		Canonical:   "terahertz",
		Symbol:      "THz",
		Aliases:     []string{"terahertz", "thz"},
		System:      "SI",
		Quantity:    "Frequency",
		Description: "1 trillion hertz",
	},
}

StandardUnits is the canonical mappingof all supported units. Keys are normalized (lowercase) for lookup, values contain all representations.

Functions

func Categories added in v1.6.2 

func Categories() []string

func CategoryForUnit added in v1.6.2 

func CategoryForUnit(unitName string) string

CategoryForUnit returns the canonical category name for a unit. Returns CategoryCustom for units not in the standard library.

func ConventionPrefix added in v1.8.4 

func ConventionPrefix(unitName string, mc *MeasurementConfig) string

ConventionPrefix returns the prefix that should be shown for a bare ambiguous unit under the given measurement config (e.g., "us", "troy", "imp"). Returns "" if the unit is not ambiguous.

func Convert added in v1.6.2 

func Convert(value decimal.Decimal, fromUnit, toUnit string) (decimal.Decimal, error)

Convert converts a value from one unit to another. Returns an error if units are unknown or incompatible.

func DecomposeSpeedUnit added in v1.8.12 

func DecomposeSpeedUnit(unit string) (numeratorUnit, timeUnit string, ok bool)

DecomposeSpeedUnit returns the Rate components for a Speed unit. Returns the numerator unit, time unit, and whether the decomposition was found.

func GetDefaultTargetUnit added in v1.6.2 

func GetDefaultTargetUnit(unitName string, targetSystem string) string

GetDefaultTargetUnit returns the preferred unit to convert to within a target system. For example, GetDefaultTargetUnit("grams", "imperial") returns "ounces". Returns "" if no suitable target exists.

func GetSystemForUnit added in v1.6.2 

func GetSystemForUnit(unitName string) string

GetSystemForUnit returns the measurement system for a unit from canonical.go. Returns "" if the unit is not in StandardUnits.

func GetUnitQuantity added in v1.8.2 

func GetUnitQuantity(unitName string) (string, bool)

GetUnitQuantity returns the quantity type for a unit name (e.g., "Length", "Mass", "Volume"). Returns the quantity and true if found, empty string and false otherwise.

func GetUnitSymbol 

func GetUnitSymbol(unitName string) (string, bool)

GetUnitSymbol returns the standard symbol for a unit name.

func IsAmbiguousUnit added in v1.8.4 

func IsAmbiguousUnit(unitName string) bool

IsAmbiguousUnit returns true if the given unit name is ambiguous — i.e., it has different definitions depending on measurement convention.

func IsHyphenatedTripleUnit added in v1.8.12 

func IsHyphenatedTripleUnit(prefix, word3 string) string

IsHyphenatedTripleUnit checks for 3-part hyphenated units. Examples: ("pound-force", "second") -> "pound-force-second"

func IsHyphenatedUnit added in v1.8.12 

func IsHyphenatedUnit(word1, word2 string) string

IsHyphenatedUnit checks if a word followed by a hyphen and another word forms a known hyphenated unit. Returns the combined form if found. Examples: ("pound", "force") -> "pound-force" 

("newton", "second") -> "newton-second"
("kilowatt", "hour") -> "kilowatt-hour"

func IsMultiWordUnit 

func IsMultiWordUnit(word1, word2 string) string

IsMultiWordUnit checks if the combination of two words is a known multi-word unit. Returns the combined form if found (preserving user's spelling), empty string otherwise. Examples: ("nautical", "mile") -> "nautical mile" 

("nautical", "miles") -> "nautical miles"
("metric", "ton") -> "metric ton"

func IsSpeedUnit added in v1.8.12 

func IsSpeedUnit(unit string) bool

IsSpeedUnit checks if a unit belongs to the Speed category.

func NormalizeUnitName 

func NormalizeUnitName(input string) (canonical string, found bool)

NormalizeUnitName converts any unit alias to its canonical form. Returns the canonical name and true if found, empty string and false otherwise.

func ResolveUnit added in v1.8.4 

func ResolveUnit(unitName string, mc *MeasurementConfig) string

ResolveUnit maps a bare ambiguous unit name to its qualified canonical name using the active measurement conventions. Non-ambiguous units and already-qualified units (like "troy oz", "imp gal") pass through unchanged.

Examples with default config (US Customary): 

ResolveUnit("oz", nil)   → "oz"     (unchanged — US is default)
ResolveUnit("gallon", nil) → "gallon" (unchanged — US is default)

With imperial volume: 

ResolveUnit("gallon", &MeasurementConfig{Volume: "imperial"}) → "imperial gallon"
ResolveUnit("imp gal", ...) → "imp gal" (already qualified, unchanged)

Types

type ConversionInfo added in v1.6.2 

type ConversionInfo struct {
	Category     string                // "Length", "Mass", etc. (matches canonical.go Quantity)
	ToBaseUnit   func(float64) float64 // Convert to base unit (e.g., feet -> meters)
	FromBaseUnit func(float64) float64 // Convert from base unit (e.g., meters -> feet)
}

ConversionInfo contains metadata about a unit for conversion purposes.

func GetUnitInfo added in v1.6.2 

func GetUnitInfo(unitName string) (ConversionInfo, bool)

GetUnitInfo returns conversion info for a unit name (case-insensitive). This is the primary lookup for raw conversion functions (ToBaseUnit/FromBaseUnit).

type MeasurementConfig added in v1.8.4 

type MeasurementConfig struct {
	// Volume: "us" (default) or "imperial"
	Volume string

	// Mass: "standard" (default, avoirdupois — everyday weight: 1 oz = 28.35g)
	// or "troy" (precious metals: 1 troy oz = 31.10g)
	Mass string

	// Ton: "short" (default, US 2000 lb), "long" (Imperial 2240 lb), or "metric" (1000 kg)
	Ton string
}

MeasurementConfig configures how ambiguous unit names are interpreted. Each axis controls an independent dimension of unit ambiguity. Only axes that differ from US Customary defaults need to be specified.

func DefaultMeasurement added in v1.8.4 

func DefaultMeasurement() *MeasurementConfig

DefaultMeasurement returns the default measurement config (US Customary).

type SpeedDecomposition added in v1.8.12 

type SpeedDecomposition struct {
	NumeratorUnit string // Length unit (e.g., "km", "mi", "m", "nmi")
	TimeUnit      string // Time unit (e.g., "hour", "second")
}

SpeedDecomposition maps a Speed unit to its Rate components.

type UnitMapping 

type UnitMapping struct {
	Canonical   string   // Canonical name (e.g., "meter")
	Symbol      string   // Standard symbol (e.g., "m")
	Aliases     []string // Alternative names (e.g., "meters", "metre", "metres")
	System      string   // "SI", "US_Customary", "Imperial"
	Quantity    string   // Type: "Length", "Mass", "Volume", "Temperature", etc.
	Description string   // Human-readable description
}

UnitMapping defines a canonical unit with its various representations.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.