formatNumeral
formatNumeral(
numeral,locales?,options?):string
Defined in: packages/math-numbers/src/format-numeral.ts:52
Renders a decimal numeral for a human, by Intl.NumberFormat.
The seam every INum.format goes through, so there is one place that talks
to Intl rather than one per numeric type. A numeral arrives as a string
deliberately: Intl.NumberFormat.prototype.format accepts one and reads it
at full precision, whereas routing a Decimal or a binary128 through a
number first would cap it at ~15 significant digits.
locales and options are new Intl.NumberFormat(locales, options)’s own,
unchanged and uninterpreted — including the default, which is the ambient
locale. A caller who needs a machine-neutral rendering must ask for one
explicitly ("en-US" with useGrouping: false).
Beyond what Intl accepts. Intl refuses maximumFractionDigits above
100 and maximumSignificantDigits above 21, because that is all a binary64
can justify — so a request for 150 places throws at construction rather than
rounding. An arbitrary-precision value can carry them, so such a request is
honoured here instead: the numeral is rounded with this package’s own decimal
arithmetic, and the locale’s separators, grouping sizes and digit set are
recovered from formatToParts probes to re-emit it. The result is what
Intl would give if it had no ceiling.
Two option shapes cannot be rendered that way, and asking for more digits
with either still throws: notation: "compact" and unitDisplay of "long"
or "narrow" pick a CLDR pattern by magnitude and plural category, so no
probe of a different magnitude predicts them. Neither is coherent for a value
long enough to need this path.
Constructing the formatter dominates the cost, so a caller rendering many
values should build one Intl.NumberFormat itself and feed it each value’s
toString().
Parameters
Section titled “Parameters”numeral
Section titled “numeral”number | bigint | StringNumericLiteral
The value as a decimal numeral, or "NaN"/"Infinity"/
"-Infinity", all of which Intl accepts.
locales?
Section titled “locales?”LocalesArgument
Passed straight to Intl.NumberFormat.
options?
Section titled “options?”NumberFormatOptions
Passed straight to Intl.NumberFormat, and allowed to ask for
more digits than Intl itself would take.
Returns
Section titled “Returns”string
The localized rendering.