Skip to content

Money & currency

A money value is an amount plus a currency. Money() formats the pair using the locale's symbol, placement, and grouping, with the currency's minor units: most currencies show two fraction digits, JPY shows none, and a few (e.g. BHD) show three. Cosmo only formats a value; it never converts between currencies. For plain numbers, percentages, and units, see Numbers.

Money is not currency conversion

Money(100, "AUD") formats 100 AUD in the locale's style. It does not convert 100 of anything into AUD — do the conversion yourself first, then format the result. Cosmo bundles no exchange-rate data.

Money() at a glance

Argument Default Meaning
value — The numeric amount (already in the target currency).
code / currency the currency modifier ISO 4217 code, e.g. "AUD", "JPY".
precision currency's minor units Override fraction digits (sets both min and max).
strict false Throw instead of returning "" when no currency is resolved.
options {} Any number-formatting option.

Use the optional parameters in Money(value, code, precision, strict, options).

Formatting an amount

new Cosmo("en-US").Money(12.3, "AUD");    // "A$12.30"
new Cosmo("en-AU").Money(1234.5);         // "$1,234.50"  (inferred from region)
new Cosmo("ja-JP").Money(1234.5, "JPY");  // "¥1,235"

How the currency is resolved

Money() looks for a currency in this order, taking the first that is set:

  1. an explicit code passed to the call;
  2. the currency modifier set on the instance at construction;
  3. the locale's region, mapped to its currency.

The symbol is always the locale's disambiguated form — en_US writes Australian dollars as A$, not the ambiguous $ — so amounts in different currencies never collide visually. Amounts are rounded to the currency's minor units with the halfExpand default.

Setting a default currency once

If every amount in a context uses the same currency, set it as a modifier and drop the per-call code:

var eur = new Cosmo("de-DE", new Modifiers(currency: "EUR"));
eur.Money(1234.5);       // "1.234,50 €"
eur.Money(99);           // "99,00 €"

Overriding precision and grouping

precision overrides the currency's natural minor units; the rest of the number options apply too. A common case is showing a whole-dollar summary without cents:

var c = new Cosmo("en-US");
c.Money(1234.5, "USD", precision: 0);                // "$1,235"
c.Money(1234.5, "USD", options: new NumberOptions { UseGrouping = false }); // "$1234.50"

Strict mode: failing loudly on a missing currency

By default Money() returns "" when it cannot resolve a currency — handy in a template, dangerous in a payment path. Pass strict to turn the silent empty string into a thrown InvalidArgumentException:

new Cosmo("en").Money(10);                        // ""  (no currency anywhere)
new Cosmo("en").Money(10, strict: true);          // throws CosmoArgumentException

Currency names & symbols

To display a currency on its own — its localised name or symbol, with no amount attached — use Currency():

var c = new Cosmo("en-US");
c.Currency("AUD");              // "Australian Dollar"
c.Currency("AUD", symbol: true);// "A$"

Currency() is part of the wider locale metadata family (alongside Language(), Country(), and friends) — that page covers it in full, including the strict-symbol behaviour. For a low-to-high money range ("$3.00 – $5.00"), see MoneyRange().

Practical examples

An invoice line. Format the unit price, quantity, and line total with one currency-bound instance, and show the currency name in the footer:

var c = new Cosmo("en-AU", new Modifiers(currency: "AUD"));
int qty = 3; double unitPrice = 19.95;
string line = $"{qty} × {c.Money(unitPrice)} = {c.Money(qty * unitPrice)}";
// "3 × $19.95 = $59.85"
string footer = $"All prices in {c.Currency("AUD")}.";
// "All prices in Australian Dollar."

Round-trip with the parser. Money() formats; ParseMoney() reads a formatted string back into amount and currency, which is useful for importing user-entered values.