The highest tagged major version is
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
- Variables
- func Categories() []string
- func CategoryForUnit(unitName string) string
- func ConventionPrefix(unitName string, mc *MeasurementConfig) string
- func Convert(value decimal.Decimal, fromUnit, toUnit string) (decimal.Decimal, error)
- func DecomposeSpeedUnit(unit string) (numeratorUnit, timeUnit string, ok bool)
- func GetDefaultTargetUnit(unitName string, targetSystem string) string
- func GetSystemForUnit(unitName string) string
- func GetUnitQuantity(unitName string) (string, bool)
- func GetUnitSymbol(unitName string) (string, bool)
- func IsAmbiguousUnit(unitName string) bool
- func IsHyphenatedTripleUnit(prefix, word3 string) string
- func IsHyphenatedUnit(word1, word2 string) string
- func IsMultiWordUnit(word1, word2 string) string
- func IsSpeedUnit(unit string) bool
- func NormalizeUnitName(input string) (canonical string, found bool)
- func ResolveUnit(unitName string, mc *MeasurementConfig) string
- type ConversionInfo
- type MeasurementConfig
- type SpeedDecomposition
- type UnitMapping
Constants ¶
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].
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.
const CategoryDataSize = "DataSize"
CategoryDataSize is the category name for data size units (bytes, bits, etc.).
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 ¶
var StandardUnits = map[string]UnitMapping{}/* 103 elements not displayed */
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
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
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
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
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
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
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 ¶
GetUnitSymbol returns the standard symbol for a unit name.
func IsAmbiguousUnit ¶ added in v1.8.4
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
IsHyphenatedTripleUnit checks for 3-part hyphenated units. Examples: ("pound-force", "second") -> "pound-force-second"
func IsHyphenatedUnit ¶ added in v1.8.12
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 ¶
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
IsSpeedUnit checks if a unit belongs to the Speed category.
func NormalizeUnitName ¶
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