Numbers¶
Format decimals, percentages, units, scientific and compact notation, and spelled-out or ordinal forms — all in the locale's conventions, straight from ICU. For currency amounts, see Money & currency.
The instance locale determines grouping and decimal separators, digits (such as
Western 0-9 or Arabic-Indic ٠-٩), and sign and percent placement. The methods
below let you control rounding, precision, notation, and units.
Method overview¶
| Method | Use it for | Returns |
|---|---|---|
number(value, options?) |
A plain decimal in the locale's style | "123.400,5" |
precision(value, fractionDigits?, options?) |
A decimal with a fixed number of fraction digits (default 2) | "1.00" |
percentage(value, precision?, options?) |
A fraction rendered as a percent | "20%" |
unit(category, unit, value, width?) |
A measurement with its localised unit | "2.19 gigabytes" |
compact(value, width?) |
A short magnitude for large numbers | "1.2K" / "1.2 thousand" |
scientific(value) |
Exponential notation | "1.2345E4" |
spellout(value) |
A number written out in words | "one hundred twenty" |
ordinal(value) |
Ordinal text | "2nd" |
symbol(name) |
A single locale notation symbol | "٫" (Persian decimal mark) |
All of number(), precision(), percentage(), and money() accept
the same options bag; the rest take simple positional
arguments described inline.
Decimals, percentages & units¶
Cosmo("de").number(123400.5) # "123.400,5"
Cosmo("en").precision(1, 2) # "1.00"
Cosmo("en").percentage(0.2) # "20%"
Cosmo("en").unit("digital", "gigabyte", 2.19) # "2.19 gigabytes"
Cosmo("tr").unit("temperature", "celsius", 26, "short") # "26°C"
number() formats a plain decimal in the locale's style — note how de swaps
the roles of . and ,. Pass the options bag to
control rounding, fraction digits, and grouping.
precision() is the shortcut for a fixed number of fraction digits: it
always renders exactly fractionDigits places (default 2), padding with trailing
zeros and rounding as needed. precision(1) → "1.00" and precision(1.002) →
"1.00" — never "1.0". It is shorthand for
number(value, { minimumFractionDigits: n, maximumFractionDigits: n }), and like
the others it stays fully localised (de → "1,00"). Pass the
options bag as a trailing argument to allow more fraction digits
(e.g. { maximumFractionDigits: 3 }) or change the rounding mode.
percentage() takes a fraction, not a pre-multiplied percent: 0.2 →
20%. The optional second argument is the maximum fraction digits (default 3),
so percentage(0.1234, 1) → "12.3%". Anything you can pass number() you can
also pass as a third options argument; an explicit maximumFractionDigits there
overrides the precision shortcut.
unit() pairs a measurement type and unit with a value and an optional
width. The type/unit names are the CLDR identifiers
(digital/gigabyte, temperature/celsius, length/meter, …). The width
selects verbosity:
width |
Example (celsius, 26) |
Notes |
|---|---|---|
none / long / full |
26 degrees Celsius |
Spelled-out unit name (the default is full/long) |
medium |
26°C |
"short" ICU display |
short |
26°C |
"narrow" ICU display — tightest |
Finding valid unit identifiers
unit() accepts the ECMA-402 sanctioned units only. List the ones your runtime
supports with supported_values("unit") and pass them as the unit argument. The category argument ("digital", "temperature", …)
is descriptive grouping — ICU does not require it to match, but keeping it
accurate documents intent.
Number-formatting options¶
number(), precision(), percentage(), and money() accept
per-call formatting options.
Pass a dictionary with camelCase keys, such as maximumFractionDigits.
The default rounding mode is halfExpand (round half away from zero).
| Key | Type / values | What it does |
|---|---|---|
minimumIntegerDigits |
int | Zero-pads the whole part (5 → "005" at 3). |
minimumFractionDigits |
int | Pads the fraction with trailing zeros up to N places. |
maximumFractionDigits |
int | Rounds the fraction to at most N places. |
minimumSignificantDigits |
int | Keep at least N significant digits. |
maximumSignificantDigits |
int | Round to at most N significant digits. |
roundingMode |
ceil · floor · expand · trunc · halfExpand · halfTrunc · halfEven |
How the last kept digit is rounded. |
roundingIncrement |
1,2,5,10,20,25,50,100,…,5000 |
Round to a multiple (e.g. 25 → nearest 0.25 with 2 fraction digits — "nickel rounding"). |
useGrouping |
always · auto · min2 · true/false |
Thousands separators. Any truthy value enables grouping. |
Significant vs fraction digits
ICU treats significant-digit limits and fraction-digit limits as mutually exclusive. Set one or the other, not both — significant digits win where both are supplied.
Options in practice¶
c = Cosmo("en")
c.number(1234.5, {"minimumFractionDigits": 2}) # "1,234.50"
c.number(1234.567, {"maximumFractionDigits": 2}) # "1,234.57"
c.number(2.005, {"maximumFractionDigits": 2,
"roundingMode": "halfEven"}) # "2"
c.number(1234.5, {"useGrouping": False}) # "1234.5"
c.percentage(0.1234, 1) # "12.3%"
Compact & scientific notation¶
Cosmo("en").scientific(12345) # "1.2345E4"
Cosmo("en").compact(1200) # "1.2K"
Cosmo("en").compact(1200, "long") # "1.2 thousand"
compact() shortens large magnitudes for dashboards, social counters, and tight
columns. The width chooses between the symbol form (short, the default —
1.2K) and the spelled scale word (long/full — 1.2 thousand), both
fully localised (German 1,2 Tsd., Japanese 1.2万). scientific() renders
exponential notation at full double precision.
Spelled-out & ordinal numbers¶
Cosmo("en").spellout(120) # "one hundred twenty"
Cosmo("en").ordinal(2) # "2nd"
Cosmo("fa").symbol("decimal") # "٫"
spellout() writes a number out in words (cheques, accessibility, voice UIs);
ordinal() gives the ordinal text (1st, 2nd, 3rd, localised). symbol()
returns a single locale notation symbol by name (decimal, group, percent,
minusSign, plusSign, nan, infinity, currency) — useful when you compose a
number inside a custom template and need just the separator.
Practical examples¶
A file-size display. Pick the unit by magnitude, then format with the
digital category at a tight width:
def file_size(c, num_bytes):
if num_bytes < 1024:
return c.unit("digital", "byte", num_bytes, "short")
mb = round(num_bytes / 1_048_576, 1)
return c.unit("digital", "megabyte", mb, "short")
file_size(Cosmo("en"), 5_242_880) # "5 MB"
A percentage with a guaranteed decimal. Combine the precision shortcut with
an options bag to also pin a minimum:
"Nickel rounding" with roundingIncrement. Round a price to the nearest 0.05: