Skip to main content
Version: 1.6.5

CLDR.Numbers

The CLDR.Numbers namespace allows you to:

  • Format decimal numbers and currencies
  • Compute the plural category for cardinal and ordinal numbers
  • Get currency symbols, display name, pluralized name and fraction info.

adjustDecimal​

Adjust a decimal numbers integer, significant and fraction digits, and apply the given rounding mode.

Syntax​

adjustDecimal(num, options?): Decimal

Parameters​

  • num: number | string | Decimal
    • The number to adjust.
  • options?: DecimalAdjustOptions
    • Options to control the decimal number adjustment.

Examples​

const cldr = framework.get('en');
log(cldr.Numbers.adjustDecimal('1.5', { maximumFractionDigits: 0 }));
log(
  cldr.Numbers.adjustDecimal('1.5', { maximumFractionDigits: 0, round: 'down' })
);
2
1

formatCurrency​

Format a decimal number, representing an amount in a given currency, into a string.

Syntax​

formatCurrency(num, code, options?): string

Parameters​

Return value​

  • A string containing the formatted currency value.

Example​

const cldr = framework.get('en');
log(cldr.Numbers.formatCurrency('12345.6789', 'EUR'));
€12,345.68

Using a compact style with an explicit fixed divisor.

const cldr = framework.get('en');
const opts = { style: 'short', divisor: 1000 };
log(cldr.Numbers.formatCurrency('100', 'USD', opts));
log(cldr.Numbers.formatCurrency('1234567', 'USD', opts));
$0.1K
$1,235K

The cash option activates rounding to the smallest cash unit available for the given currency. For example, if the penny were eliminated in the United States, the nickel ($0.05) would become the smallest cash unit available. See the CLDR currency data for the most recent list.

Note: the round rounding mode still takes effect; only the rounding increment is changed.

const cldr = framework.get('en');
const opts = { cash: true };

// The smallest cash unit for the Danish Krone is 0.50
log(cldr.Numbers.formatCurrency('345.67', 'DKK', opts));
log(cldr.Numbers.formatCurrency('345.76', 'DKK', opts));

// The smallest cash unit for the Canadian Dollar is 0.05
log(cldr.Numbers.formatCurrency('345.67', 'CAD', opts));
log(cldr.Numbers.formatCurrency('345.76', 'CAD', opts));
DKK 345.50
DKK 346.00
CA$345.65
CA$345.75

formatCurrencyToParts​

Format a decimal number, representing an amount in a given currency, into an array of parts.

Syntax​

formatCurrencyToParts(num, code, options?): Part[]

Parameters​

Return value​

  • An array containing the formatted parts.

Example​

const cldr = framework.get('en');
log(cldr.Numbers.formatCurrencyToParts('12345.6789', 'EUR'));
[
  { type: 'currency', value: '€' },
  { type: 'integer', value: '12' },
  { type: 'group', value: ',' },
  { type: 'integer', value: '345' },
  { type: 'decimal', value: '.' },
  { type: 'fraction', value: '68' }
]

formatDecimal​

Format a decimal number to a string.

Syntax​

formatDecimal(num, options?): string

Parameters​

Return value​

  • A string containing the formatted number

Example​

const cldr = framework.get('en');
log(cldr.Numbers.formatDecimal('12345.6789', { group: true }));
12,345.679

Using a compact style with an explicit fixed divisor.

const cldr = framework.get('en');
const opts = { style: 'long', divisor: 1000 };
log(cldr.Numbers.formatDecimal('100', opts));
log(cldr.Numbers.formatDecimal('1234567', opts));
0.1 thousand
1,235 thousand

formatDecimalToParts​

Format a decimal number to an array of parts.

Syntax​

formatDecimalToParts(num, options?): Part[]

Parameters​

Return value​

  • An array containing a list of the formatted parts.

Example​

const cldr = framework.get('en');
log(cldr.Numbers.formatDecimalToParts('12345.6789', { group: true }));
[
  { type: 'integer', value: '12' },
  { type: 'group', value: ',' },
  { type: 'integer', value: '345' },
  { type: 'decimal', value: '.' },
  { type: 'fraction', value: '679' }
]

getCurrencySymbol​

Get the display symbol for a given currency.

Syntax​

getCurrencySymbol(code, width?): string

Parameters​

Example​

const cldr = framework.get('en');
log(cldr.Numbers.getCurrencySymbol('GBP'));
£

getCurrencyDisplayName​

Get the display name for a given currency.

Syntax​

getCurrencyDisplayName(code, options?): string

Parameters​

Example​

const cldr = framework.get('en');
log(cldr.Numbers.getCurrencyDisplayName('MXN'));
Mexican Peso

getCurrencyPluralName​

Get the pluralized name for a given currency.

Syntax​

getCurrencyPluralName(num, code, options?): string

Parameters​

  • num: number | string | Decimal
    • The number to use to compute the plural category. Note that you may want to adjustDecimal the number first, to ensure the number has the expected number of fraction digits, since the plural categories for 1 and 1.0 can differ.
  • code: CurrencyType
    • The 3-letter ISO 4217 code for the currency.
  • options?: DisplayNameOptions
    • Options to adjust the display name

Example​

const cldr = framework.get('en');
log(cldr.Numbers.getCurrencyPluralName('1', 'USD'));
log(cldr.Numbers.getCurrencyPluralName('17', 'USD'));
US dollar
US dollars

getCurrencyFractions​

Get the fraction info for a given currency.

Syntax​

getCurrencyFractions(code): CurrencyFractions

Parameters​

Return value​

  • A CurrencyFractions object

Example​

const cldr = framework.get('en');
log(cldr.Numbers.getCurrencyFractions('USD'));
log(cldr.Numbers.getCurrencyFractions('JPY'));
{ digits: 2, rounding: 0, cashDigits: 2, cashRounding: 0 }
{ digits: 0, rounding: 0, cashDigits: 0, cashRounding: 0 }

getCurrencyForRegion​

Get the currency code for a given region code.

Syntax​

getCurrencyForRegion(region): CurrencyType

Parameters​

  • region: string
    • The 2-letter ISO-3166-1 code for a region.

Return value​

Example​

const cldr = framework.get('en');
log(cldr.Numbers.getCurrencyForRegion('ME'));
log(cldr.Numbers.getCurrencyForRegion('CH'));
EUR
CHF

getPluralCardinal​

Get the plural category for a cardinal number.

Syntax​

getPluralCardinal(num, options?): string

Parameters​

Example​

const w = (s: string) => `${s}${' '.repeat(12 - s.length)}`;

const nums = ['0', '1', '1.0', '2', '6'];
const locales = ['en-US', 'fr-FR', 'pl-PL', 'lt-LT'];

for (const n of nums) {
  const res = locales
    .map((id) => {
      const cldr = framework.get(id);
      return `${id}=${cldr.Numbers.getPluralCardinal(n)}`;
    })
    .map(w)
    .join(' ');
  log(`${' '.repeat(4 - n.length)}${n}   ${res}`);
}
   0   en-US=other  fr-FR=one    pl-PL=many   lt-LT=other 
   1   en-US=one    fr-FR=one    pl-PL=one    lt-LT=one   
 1.0   en-US=other  fr-FR=one    pl-PL=other  lt-LT=one   
   2   en-US=other  fr-FR=other  pl-PL=few    lt-LT=few   
   6   en-US=other  fr-FR=other  pl-PL=many   lt-LT=few

getPluralOrdinal​

Get the plural category for an ordinal number.

Syntax​

getPluralOrdinal(num, options?): string

Parameters​

Example​

const endings = {
  fr: { one: 're', other: 'e' },
  en: { one: 'st', two: 'nd', few: 'rd', other: 'th' },
};

const nums = ['1', '2', '3', '4', '5'];

Object.keys(endings).forEach((id) => {
  const cldr = framework.get(id);
  const res = nums
    .map((n) => {
      const cat = cldr.Numbers.getPluralOrdinal(n);
      return `${n}${endings[id][cat]}`;
    })
    .join(' ');
  log(`${id}: ${res}`);
});
fr: 1re 2e 3e 4e 5e
en: 1st 2nd 3rd 4th 5th

parseDecimal​

Parse a string or number into a Decimal instance.

Syntax​

parseDecimal(n): Decimal

Parameters​

  • num: number | string
    • The number to convert / parse.

Example​

const en = framework.get('en');
for (const n of [0, '1.23456789', Number.MAX_SAFE_INTEGER, '1.999999e50']) {
  const d = en.Numbers.parseDecimal(n);
  log(d.toScientificString().padEnd(22), d.toString());
}
0                      0
1.23456789             1.23456789
9.007199254740991E+15  9007199254740991
1.999999E+50           199999900000000000000000000000000000000000000000000