Skip to content

Latest commit

 

History

History
117 lines (79 loc) · 4.08 KB

currency-to-parts-formatter.md

File metadata and controls

117 lines (79 loc) · 4.08 KB
Raw

.currencyToPartsFormatter( currency [, options] ) ➜ function( value )

Return a function that formats a currency into parts tokens according to the given options or locale's defaults.

The returned function is invoked with one argument: the Number value to be formatted.

Parameters

currency

3-letter currency code as defined by ISO 4217, eg. "USD".

options

Please, see .currencyFormatter() options.

value

Number to be formatted, eg. 9.99.

Returns

An Array of objects containing the formatted currency in parts. The returned structure looks like this:

[
  { type: "day", value: "17" },
  { type: "weekday", value: "Monday" }
]

Possible types are the following:

  • currency

    The currency string, such as the symbols "$" and "€" or the name "Dollar", "Euro" depending on which style is used.

Please, see .numberToPartsFormatter() for details about the inherited number parts such as decimal, fraction, group, infinity, integer, literal, minusSign, nan, plusSign, percentSign, and compact.

Example

Prior to using any currency methods, you must load cldr/main/{locale}/currencies.json, cldr/supplemental/currencyData.json, and the CLDR content required by the number module. If using plural messages, you also must load the CLDR content required by the plural module. Read CLDR content if you need more information.

Static Formatter

Using the default options

You can use the static method Globalize.currencyToPartsFormatter(), which uses the default locale.

var formatter;

Globalize.locale( "en" );
formatter = Globalize.currencyToPartsFormatter( "USD" );

formatter( 9.99 );
// > [
//   { "type": "currency", "value": "$" },
//   { "type": "integer", "value": "9" },
//   { "type": "decimal", "value": "." },
//   { "type": "fraction", "value": "99" }
// ]

Instance Formatter

You can use the instance method .currencyFormatter(), which uses the instance locale.

var deFormatter = Globalize( "de" ).currencyToPartsFormatter( "EUR" ),
  zhFormatter = Globalize( "zh" ).currencyToPartsFormatter( "EUR" );

deFormatter( 9.99 );
// > [
//   { "type": "integer", "value": "9" },
//   { "type": "decimal", "value": "," },
//   { "type": "fraction", "value": "99" },
//   { "type": "literal", "value": " " },
//   { "type": "currency", "value": "€" }
// ]

zhFormatter( 9.99 );
// > [
//   { "type": "currency", "value": "€" },
//   { "type": "integer", "value": "9" },
//   { "type": "decimal", "value": "." },
//   { "type": "fraction", "value": "99" }
// ]

The information is available separately and it can be formatted and concatenated again in a customized way. For example by using Array.prototype.map(), arrow functions, a switch statement, template literals, and Array.prototype.reduce().

More Examples

Please, see .currencyFormatter() example for additional examples such as using alternative symbolForm, configuring style (symbol, accounting, and name styles), and the inherited number options (e.g., compact numbers).

Performance Suggestion

For improved performance on iterations, first create the formatter. Then, reuse it on each loop.

var formatter = Globalize( "en" ).currencyToPartsFormatter( "USD" );

renderInvoice({
  prices: prices.map(function( price ) {
    return formatter( price );
  })
});