The Money type

A monetary value is meaningless without a currency: “47.95” is not money until you know whether it is dollars, yen, or dinars. The Money type captures both pieces together, following the Money pattern described in Martin Fowler’s Patterns of Enterprise Application Architecture.

Amount and currency together

Money is a readonly struct that stores a decimal amount alongside an optional ISO 4217 currency (Iso4217CurrencyCurrent). When no currency is supplied, it reports the ISO 4217 reserved code XXX (“no currency”) through its IsoCurrencyCode property. Because the amount and currency travel as one value, you cannot accidentally lose track of which currency an amount is denominated in as it passes through your code.

You never construct a Money directly; its constructors are private. Instead you use the Money.Create factory overloads, which validate the supplied currency. A currency must be a defined enum member and a national or supranational currency (or the XTS testing code) — otherwise Create throws an ArgumentException. This keeps placeholder and funds-only codes out of real monetary values.

Currency-safe arithmetic

Money defines arithmetic operators (+, -, *, /, %) against decimal, so you can compute with amounts naturally while the currency and rounding settings carry through to the result. It also defines implicit conversions to and from decimal, so a Money behaves like a number in expressions.

Two Money values add, subtract and take a remainder only when they share a currency, and dividing one by the other gives their ratio as a decimal. Mixing currencies throws an InvalidOperationException, so 5 USD + 3 EUR is an error rather than 8 USD. The expressions with no meaning as an amount of money, money * money, number / money and number % money, don’t compile. Negation (-money), ++ and -- keep the currency.

A decimal converted to Money has no currency (XXX), so it doesn’t combine with a value in a currency. Start a running total in the currency it sums, Money.Create(0m, currency), rather than Money total = 0m;. The ratio a / b is a decimal too, so Money x = a / b; gives a value with no currency; divide by a number, as in total / 3, to keep it.

Ordering enforces a key invariant: two Money values whose currencies differ have no order. The relational operators (<, >, <=, >=) throw an InvalidOperationException for them, and CompareTo throws an ArgumentException. Two amounts in different currencies are effectively different types, and ordering them by amount alone would produce a misleading answer, so the type refuses rather than guessing.

Anything that orders values through CompareTo therefore fails on a collection that mixes currencies. LINQ’s OrderBy, Min and Max pass the ArgumentException on as it is. List<T>.Sort and Array.Sort wrap it in an InvalidOperationException, with the ArgumentException as its InnerException. Group or convert the values by currency first.

Equality is different: it always has an answer. Values in different currencies are simply not equal, so Equals, == and != agree and never throw. Dictionary<Money, …>, Contains, Distinct and EqualityComparer<Money> see the same answer as ==. A value with no currency, such as default(Money), counts as the currency XXX, so it is not equal to, and can’t be ordered against, a value in a real currency.

Rounding as part of the value

Currencies differ in how many minor units (decimal places) they use, and financial calculations need predictable rounding. A Money value can carry a RoundingPrecision and an optional RoundingMethod (MidpointRounding). When the value is converted back to a decimal, that rounding is applied automatically — with a precision but no explicit method, rounding follows the IEEE 754 default. The currency’s own minor-unit count is available separately through CurrencyMinorUnits. Keeping the rounding policy attached to the value means the same rule applies everywhere the amount is used, rather than relying on each call site to remember it.

Why represent money this way

  • No orphaned amounts. The currency is part of the value, so an amount can never drift away from the currency it belongs to.
  • Mistakes become errors, not silent bugs. Ordering values in different currencies throws instead of returning a wrong-but-plausible result.
  • One rounding policy. Precision and method are stored on the value and applied consistently on conversion to decimal.
  • Familiar ergonomics. Implicit decimal conversions and arithmetic operators let Money slot into existing numeric code with minimal friction.

This site uses Just the Docs, a documentation theme for Jekyll.