Skip to content

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:

Cosmo("en").percentage(0.5, 2, {"minimumFractionDigits": 2})  # "50.00%"

"Nickel rounding" with roundingIncrement. Round a price to the nearest 0.05:

Cosmo("en").number(2.13, {"maximumFractionDigits": 2,
                          "roundingIncrement": 5,
                          "minimumFractionDigits": 2})  # "2.15"