1.8.0

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
← CLDR.GeneralCLDR.Units →