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.

Pass precision and strict in the options object.

Formatting an amount

Cosmo("en_US").money(12.3, "AUD")         # "A$12.30"
Cosmo("en_AU").money(1234.5)              # "$1,234.50"  (inferred from region)
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:

eur = Cosmo("de_DE", {"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:

c = Cosmo("en_US")
c.money(1234.5, "USD", {"precision": 0})             # "$1,235"
c.money(1234.5, "USD", {"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:

Cosmo("en").money(10)                             # ""
Cosmo("en").money(10, {"strict": True})           # raises InvalidArgumentError

Currency names & symbols

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

c = Cosmo("en_US")
c.currency("AUD")               # "Australian Dollar"
c.currency("AUD", 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 money_range().

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:

c = Cosmo("en_AU", {"currency": "AUD"})
qty, unit_price = 3, 19.95
line = f"{qty} × {c.money(unit_price)} = {c.money(qty * unit_price)}"
# "3 × $19.95 = $59.85"
footer = f"All prices in {c.currency('AUD')}."
# "All prices in Australian Dollar."

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