Map and look up unit abbreviations by strings instead of enums

[angularsen]

Blocks #1181

QuantityType enum is already deprecated and will be removed in #982 in order to better support third-party quantities and units.

The same could be done for the 100+ unit enums, like LengthUnit

Instead of

string abbreviation = UnitAbbreviationsCache.Default.GetDefaultAbbreviation(unitInfo.GetType(), (int)unitInfo);

We could support, without breaking change:

string abbreviation = UnitAbbreviationsCache.Default.GetDefaultAbbreviation("Length", "Millimeter");

Optionally, we could deprecate the enum-based overloads and remove them in #982 or future major version bump.

Related to discussion:
#1062 (comment)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[bdbonazz]

@angularsen
Do you think this way of implementing the solution is acceptable?

bdbonazz@daa7942

If so, I'll add the necessary tests and comments, and submit a PR.

[angularsen]

Hi, I think the proposed implementation is heavier than necessary.

What already exists

The building blocks for string-based lookup are already in place:

• QuantityInfoLookup.GetUnitByName("Length", "Meter") → returns UnitInfo
• UnitInfo has a .UnitKey property
• UnitAbbreviationsCache.GetDefaultAbbreviation(UnitKey) already works

So today you can already do:

var unitInfo = Quantity.ByName["Length"].UnitInfos.First(u => u.Name == "Meter");
var abbreviation = UnitAbbreviationsCache.Default.GetDefaultAbbreviation(unitInfo.UnitKey);

My suggestion

I haven't verified this works, but something like this should.
Rather than generating a GetUnitKey(string) switch method on all 130+ quantity types, we can add a simple convenience overload on UnitAbbreviationsCache that delegates to the existing infrastructure:

public string GetDefaultAbbreviation(string quantityName, string unitName, IFormatProvider? formatProvider = null)
{
    var unitInfo = Quantity.DefaultProvider.GetUnitByName(quantityName, unitName);
    return GetDefaultAbbreviation(unitInfo.UnitKey, formatProvider);
}

This gives the same API surface with no codegen changes and no new generated code across 130+ files.

Would you be open to submitting a PR with this simpler approach?

[bdbonazz]

@angularsen
Hi, thanks for the suggestion.
It seems that

public string GetDefaultAbbreviation(string quantityName, string unitName, IFormatProvider? formatProvider = null)
{
    var unitInfo = Quantities.GetUnitByName(quantityName, unitName);
    return GetDefaultAbbreviation(unitInfo.UnitKey, formatProvider);
}

just works, without modifying any other files
This way we get a UnitInfo from which we extract a UnitKey

But

public string GetDefaultAbbreviation(UnitKey unitKey, IFormatProvider? formatProvider = null)

calls

IReadOnlyList<string> GetUnitAbbreviations(UnitKey unitKey, IFormatProvider? formatProvider = null)

that calls

internal IReadOnlyList<string> GetAbbreviationsWithFallbackCulture(UnitInfo unitInfo, CultureInfo culture)

extracting a UnitInfo from the UnitKey.

Question

Do you think it might be a good idea to do add another GetUnitAbbreviations overload

IReadOnlyList<string> GetUnitAbbreviations(UnitInfo unitInfo, IFormatProvider? formatProvider = null)

And modify the rest of the class accordingly?

[angularsen]

Good observation! You're right that the UnitKey -> UnitInfo round-trip is unnecessary when you already have a UnitInfo.

This is actually part of a broader asymmetry in this class: discovery and parsing APIs return UnitInfo, but UnitAbbreviationsCache only accepts UnitKey — which internally just looks up the UnitInfo again. So callers end up doing .UnitKey extraction, and then we undo it internally.

I think it makes sense to add UnitInfo overloads for the public methods in this class that currently take UnitKey and immediately resolve it to UnitInfo internally. That includes GetDefaultAbbreviation, GetUnitAbbreviations, and the MapUnitToAbbreviation/MapUnitToDefaultAbbreviation methods. The UnitKey overloads would just delegate to the UnitInfo ones.

Want to submit a PR for this?

@lipchev any opinions on what methods should take UnitKey vs UnitInfo vs both?

---

Analysis: UnitKey vs UnitInfo asymmetry across the public API

Background

UnitKey is a lightweight readonly record struct (Type + int) used as a boxing-free identifier for units. UnitInfo is a rich class with metadata (name, conversions, base units) that contains a .UnitKey property — it's a superset.

There's an asymmetry in the API: discovery and parsing operations return UnitInfo, but most operational APIs only accept UnitKey. This forces consumers to extract .UnitKey and sometimes causes internal re-lookups of the same UnitInfo.

Where consumers get each type

Source	What you get
IQuantity.UnitKey (any quantity instance)	UnitKey
IQuantity.UnitInfo (any quantity instance, .NET 5+)	UnitInfo
IQuantity<TUnit>.UnitInfo (typed quantity, .NET 5+)	UnitInfo<TUnit>
Typed enum (LengthUnit.Meter)	implicitly converts to UnitKey
UnitParser.GetUnitFromAbbreviation(...)	UnitInfo
QuantityInfoLookup.GetUnitByName(...)	UnitInfo
QuantityInfo.UnitInfos (enumerating units)	UnitInfo
QuantityInfo[unitKey] indexer	UnitInfo

Analysis by class

UnitAbbreviationsCache -- add UnitInfo overloads

All 16 non-constructor public methods internally resolve UnitKey -> UnitInfo via Quantities.GetUnitInfo(). The core implementations (PerformAbbreviationMapping, GetAbbreviationsWithFallbackCulture) already work on UnitInfo.

Recommendation: Make UnitInfo overloads the real implementations for 4 method groups:

• GetDefaultAbbreviation(UnitInfo, IFormatProvider?)
• GetUnitAbbreviations(UnitInfo, IFormatProvider?)
• MapUnitToAbbreviation(UnitInfo, IFormatProvider?, IEnumerable<string>)
• MapUnitToDefaultAbbreviation(UnitInfo, IFormatProvider?, string)

The UnitKey, generic TUnitType, and (Type, int) overloads all delegate to the UnitInfo one. Purely additive, no breaking changes.

UnitConverter -- leave as UnitKey (correct as-is)

Despite also resolving UnitKey -> UnitInfo internally, UnitConverter is different:

1. Caching is keyed on UnitKey -- both FrozenQuantityConverter and DynamicQuantityConverter use UnitConversionKey (wrapping two UnitKeys) as cache keys. Adding UnitInfo overloads wouldn't skip this caching layer.
2. The typical caller has UnitKey -- conversion is called from quantity instances (quantity.UnitKey), not from parsing results.
3. The protected layer already takes UnitInfo -- ConvertValueInternal(value, fromUnitInfo, toUnitInfo) and TryConvertValueInternal are the internal seam. Subclasses that need to work with UnitInfo already do.
4. String-based methods bypass UnitKey entirely -- ConvertValueByName and ConvertValueByAbbreviation resolve to UnitInfo internally and pass it straight to the protected methods.

Adding UnitInfo public overloads here would expand the API surface without a clear consumer benefit.

UnitParser -- no changes needed

Two sets of methods exist:

• Legacy: Parse<TUnitType>() returns typed enum. Internally gets UnitInfo, extracts .UnitKey, converts to enum.
• Newer: GetUnitFromAbbreviation() returns UnitInfo directly.

The newer methods are already the right pattern. Changing the legacy return types would be a massive breaking change for no gain -- consumers using the typed path want the enum.

QuantityInfo / QuantityInfoLookup / Quantity -- no changes needed

Already well-designed:

• Discovery methods return UnitInfo (correct -- callers want metadata).
• UnitInfo.From(value) handles "I have UnitInfo, give me a quantity" -- no need for a Quantity.From(value, UnitInfo) overload.
• The UnitKey indexer on QuantityInfo is appropriate -- it's a lookup operation.

Summary

Class	Current input	Change needed
UnitAbbreviationsCache	UnitKey only	Add UnitInfo overloads
UnitConverter	UnitKey (public), UnitInfo (protected)	None
UnitParser	strings	None
QuantityInfo/Lookup	UnitKey, strings, TUnit	None

Related

#1649 adds IQuantity.UnitInfo / IQuantity<TUnit>.UnitInfo as a convenience property, so consumers can get UnitInfo directly from a quantity instance without the verbose quantity.QuantityInfo[quantity.UnitKey] pattern. This pairs well with the UnitAbbreviationsCache overloads proposed above.

Performance note

The UnitKey -> UnitInfo lookup is a Dictionary.TryGetValue (or FrozenDictionary on .NET 8+) with a fast custom hash -- single-digit nanoseconds. The motivation for this change is API ergonomics, not performance.

[lipchev]

Good observation! You're right that the UnitKey -> UnitInfo round-trip is unnecessary when you already have a UnitInfo.

This is actually part of a broader asymmetry in this class: discovery and parsing APIs return UnitInfo, but UnitAbbreviationsCache only accepts UnitKey — which internally just looks up the UnitInfo again. So callers end up doing .UnitKey extraction, and then we undo it internally.

I think it makes sense to add UnitInfo overloads for the public methods in this class that currently take UnitKey and immediately resolve it to UnitInfo internally. That includes GetDefaultAbbreviation, GetUnitAbbreviations, and the MapUnitToAbbreviation/MapUnitToDefaultAbbreviation methods. The UnitKey overloads would just delegate to the UnitInfo ones.

Want to submit a PR for this?

@lipchev any opinions on what methods should take UnitKey vs UnitInfo vs both?

The UnitAbbreviationsCache (and the UnitConverter etc.) is constructed with a set of QuantityInfo objects which are expected to hold a set of UnitInfo specific to the given QuantityInfo (which may or may not be from the default configuration).
By making the UnitInfo overload internal, my intention was to avoid the scenario where the user passes in a seemingly valid UnitInfo (obviously every UnitInfo by itself is valid), that isn't the same as the one in the cached QuantityInfo.
Saying "the given unit with key ... was not found for the configured quantity" made sense.. Trying to explain the other one isn't trivial.