units

package
v1.8.4 Latest Latest
Warning

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

 Go to latest Published: Mar 14, 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",
	},
}

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 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 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 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 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.