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¶
new Cosmo("de").number(123400.5); // "123.400,5"
new Cosmo("en").precision(1, 2); // "1.00"
new Cosmo("en").percentage(0.2); // "20%"
new Cosmo("en").unit("digital", "gigabyte", 2.19); // "2.19 gigabytes"
new 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 supportedValues("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 Map<String, Object> with camelCase keys.
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. |
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¶
Cosmo c = new Cosmo("en");
c.number(1234.5, Map.of("minimumFractionDigits", 2)); // "1,234.50"
c.number(1234.567, Map.of("maximumFractionDigits", 2)); // "1,234.57"
c.number(2.005, Map.of("maximumFractionDigits", 2,
"roundingMode", "halfEven")); // "2"
c.number(1234.5, Map.of("useGrouping", false)); // "1234.5"
c.percentage(0.1234, 1); // "12.3%"
Compact & scientific notation¶
new Cosmo("en").scientific(12345); // "1.2345E4"
new Cosmo("en").compact(1200); // "1.2K"
new 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¶
new Cosmo("en").spellout(120); // "one hundred twenty"
new Cosmo("en").ordinal(2); // "2nd"
new 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.