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

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 in the ICU unit documentation, 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 NumberOptions object with PascalCase properties, such as MaximumFractionDigits. The table below lists the corresponding option names.

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

var c = new Cosmo("en");
c.Number(1234.5, new NumberOptions { MinimumFractionDigits = 2 });          // "1,234.50"
c.Number(1234.567, new NumberOptions { MaximumFractionDigits = 2 });        // "1,234.57"
c.Number(2.005, new NumberOptions { MaximumFractionDigits = 2,
                                    RoundingMode = "halfEven" });           // "2"
c.Number(1234.5, new NumberOptions { 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.

Practical examples

A file-size display. Pick the unit by magnitude, then format with the digital category at a tight width:

string FileSize(Cosmo c, long bytes) {
    if (bytes < 1024) return c.Unit("digital", "byte", bytes, "short");
    double mb = Math.Round(bytes / 1_048_576.0, 1);
    return c.Unit("digital", "megabyte", mb, "short");
}
FileSize(new 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:

new Cosmo("en").Percentage(0.5, 2, new NumberOptions { MinimumFractionDigits = 2 }); // "50.00%"

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

new Cosmo("en").Number(2.13, new NumberOptions {
    MaximumFractionDigits = 2,
    RoundingIncrement = 5,
    MinimumFractionDigits = 2
});  // "2.15"