Integrate Money with .Net's formatting and parsing infrastructure

[matthew25187]

Adds native formatting and parsing support to the Money type, so that a monetary value can be formatted and parsed exactly as an intrinsic numeric type is.

var money = Money.Create(1234.5m, Iso4217CurrencyCurrent.NZD);

money.ToString("C2", new CultureInfo("en-NZ"));   // NZ$1,234.50
money.ToString("I2", new CultureInfo("de-DE"));   // 1.234,50 NZD
Money.Parse("NZD1,234.50", enNz);                 // round-trips

Breaking change

C now emits the currency symbol rather than the ISO 4217 currency code. Use I where you previously used C.

Format	Before	After
money.ToString("C2", enNz)	NZD1,234.50	NZ$1,234.50
money.ToString("I2", enNz)	—	NZD1,234.50

The mapping now matches the meaning the specifier has for the intrinsic numeric types, so a caller writing money.ToString("C2", culture) gets what decimal.ToString("C2", culture) would give them. This warrants a major version bump for the package.

Format specifiers

Specifier	Emits	Example (NZD, en-NZ)
C	Currency symbol	NZ$1,234.50
H	Narrow currency symbol	$1,234.50
I	ISO 4217 currency code	NZD1,234.50
N	Currency name	New Zealand Dollar1,234.50
G, or no format	The amount alone	1234.5
currency code	The code, asserting the currency	NZD1,234.50

Each may carry a precision (C2, I3); the default is the number of minor units of the currency.

The culture governs presentation, not currency

A Money value carries its own currency, so the culture supplied determines only the separators, group sizes, token placement and sign. Which currency is denoted, and the default precision, come from the value.

Money.Create(1234567.5m, Iso4217CurrencyCurrent.NZD).ToString("C", enIn);   // NZ$12,34,567.50

The amount is grouped in the Indian style because that culture was asked for, but the value is still denoted in New Zealand Dollars. Substituting the culture's symbol would assert that a quantity of New Zealand Dollars is the same quantity of Rupees, which is false and which neither a reader nor a subsequent parse could detect.

Parsing

A currency is identified from a currency code, which is never ambiguous, or from a symbol where the currency it denotes can be established with certainty. Measured against CLDR, 159 of the 164 currencies carrying a symbol are resolvable without any culture at all; only GBP, JPY, KRW, USD and VEF need one, being the currencies holding a bare shared glyph.

Where the currency cannot be determined, parsing fails. It never selects one on the value's behalf, and never resolves a shared symbol from the culture of the current thread.

MoneyStyles lets a caller accept only the elements they expect, as NumberStyles does for the intrinsic numeric types. ParseExact accepts a value only where formatting the result reproduces it under one of the named formats.

Defects found and fixed

Four pre-existing defects surfaced during the work:

• Parse silently truncated NZD1,234.50 to 1234. The pattern admitted no group separators, so the minor units were discarded whenever one was present. The most consequential of these.
• netstandard1.0 did not build, owing to unguarded nullable annotations.
• MoneyInfo.CurrentMoney threw when first read, interpreting the subtags of the current culture with Enum.TryParse where neither is a System.Enum.
• CompareTo(object) threw for a Money argument; Equals(object) used the reflection-based comparison on modern targets.

Two further defects were introduced and fixed within the branch: a value with no currency emitted the culture's symbol, and a malformed precision fell through to the number formatter, which emitted the culture's symbol in place of the value's currency.

Currency symbol data

ISO 4217 defines no currency symbols, so they are sourced from Unicode CLDR by a new generator script following the conventions of the existing ones. Iso4217CurrencyCodeAttribute and the existing generators are untouched. Symbols are exposed through GetCurrencySymbol extension methods on both currency code enums, in the standard and narrow forms CLDR publishes.

The Unicode copyright notice required by the licence is recorded in THIRD-PARTY-NOTICES.md and in the generated source.

Notable design decisions

• CurrencyFormatInfo has no CurrencySymbol. NumberFormatInfo needs one because decimal carries no currency; a Money value does, so the symbol always comes from the value. CurrencyCode is retained because it is what resolves a shared symbol when parsing.
• CurrencySymbols is internal. Symbols have no unique identity — $ is shared by thirty currencies — so a public symbol type would offer naming without round-tripping.
• Resource lookup no longer mutates the shared resource manager culture, which was not safe to do from several threads at once.

Verification

• All four target frameworks build with no errors and no warnings.
• 395 tests pass, up from 239.
• Satellite assemblies were confirmed to survive packing (64 assemblies, 16 cultures across 4 frameworks), and a CI step now asserts this. The step was itself tested against a package with the satellites removed, to establish that it fails.

Left to the reviewer

• The package version bump for the breaking change.
• The legacy Parse/TryParse overloads now route through the new parser. This fixes the truncation defect but does widen them to accept unambiguous currency symbols. Say if you would prefer them frozen.

🤖 Generated with Claude Code