diff --git a/README.md b/README.md index 9a3cd746c..d39dd416d 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ Node.js module. - [Date module](#date_module) - [Message module](#message_module) - [Number module](#number_module) + - [Currency module](#currency_module) - [Plural module](#plural_module) - more to come... - [Error reference](#error) @@ -96,10 +97,11 @@ information on its usage. | File | Minified + gzipped size | Summary | |---|--:|---| -| globalize.js | 1.1KB | [Core library](#core) | -| globalize/date.js | +4.8KB | [Date module](#date_module) provides date formatting and parsing | +| globalize.js | 1.3KB | [Core library](#core) | +| globalize/currency.js | +2.6KB | [Currency module](#currency_module) provides currency formatting and parsing | +| globalize/date.js | +3.8KB | [Date module](#date_module) provides date formatting and parsing | | globalize/message.js | +0.5KB | [Message module](#message_module) provides message translation | -| globalize/number.js | +3.0KB | [Number module](#number_module) provides number formatting and parsing | +| globalize/number.js | +2.9KB | [Number module](#number_module) provides number formatting and parsing | | globalize/plural.js | +1.7KB | [Plural module](#plural_module) provides pluralization support | @@ -166,6 +168,7 @@ requirements. See table below. | Module | Required CLDR JSON files | |---|---| | Core module | cldr/supplemental/likelySubtags.json | +| Currency module | cldr/main/`locale`/currencies.json
cldr/supplemental/currencyData.json
+CLDR JSON files from number module | | Date module | cldr/main/`locale`/ca-gregorian.json
cldr/main/`locale`/timeZoneNames.json
cldr/supplemental/timeData.json
cldr/supplemental/weekData.json
+CLDR JSON files from number module | | Number module | cldr/main/`locale`/numbers.json
cldr/supplemental/numberingSystems.json | | Plural module | cldr/supplemental/plurals.json | @@ -310,6 +313,22 @@ to you in different flavors): [Read more...](doc/api/number/parse-number.md) + +#### Currency module + +- **`.currencyFormatter( currency [, options] )`** + + Return a function that formats a currency according to the given options or + locale's defaults. + + [Read more...](doc/api/currency/currency-formatter.md) + +- **`.formatCurrency( value, currency [, options] )`** + + Format a currency according to the given options or locale's defaults. + + [Read more...](doc/api/currency/format-currency.md) + ### Plural module @@ -379,6 +398,11 @@ to you in different flavors): setting the Global locale with `Globalize.locale( )`. [Read more...](doc/error/e-default-locale-not-defined.md) +- **`E_MISSING_PLURAL_MODULE`** + + Thrown when plural module is needed, but not loaded, eg. to format currencies + using the named form. [Read more...](doc/error/e-missing-plural-module.md) + - **`E_UNSUPPORTED`** Thrown for unsupported features, eg. to format unsupported date patterns. diff --git a/doc/api/currency/currency-formatter.md b/doc/api/currency/currency-formatter.md new file mode 100644 index 000000000..4e0602ec8 --- /dev/null +++ b/doc/api/currency/currency-formatter.md @@ -0,0 +1,127 @@ +## .currencyFormatter( currency [, options] ) + +Return a function that formats a currency according to the given options or +locale's defaults. + +### Parameters + +**currency** + +3-letter currency code as defined by ISO 4217, eg. `USD`. + +**options** Optional + +A JSON object including none or any of the following options. + +> **style** Optional +> +> String `symbol` (default), `accounting`, `code` or `name`. + +See [`.numberFormatter( [options] )`](../number/number-formatter.md) for more +options. + +### Example + +You can use the static method `Globalize.currencyFormatter()`, which uses the +default locale. + +```javascript +var formatter; + +Globalize.locale( "en" ); +formatter = Globalize.currencyFormatter( "USD" ); + +formatter( 9.99 ); // "$9.99" +``` + +You can use the instance method `.currencyFormatter()`, which uses the instance +locale. + +```javascript +var deFormatter = Globalize( "de" ).currencyFormatter( "EUR" ), + zhFormatter = Globalize( "zh" ).currencyFormatter( "EUR" ); + +deFormatter( 9.99 ); // "9,99 €" +zhFormatter( 9.99 ); // "€ 9.99" +``` + +For comparison, follow the formatting output of different symbols in different +locales. + +| 3-letter currency code | en (English) | de (German) | zh (Chinese) | +| --- | --- | --- | --- | +| `.currencyFormatter( "USD" )( 1 )` | `$1.00` | `1,00 $` | `US$ 1.00` | +| `.currencyFormatter( "EUR" )( 1 )` | `€1.00` | `1,00 €` | `€ 1.00` | +| `.currencyFormatter( "CNY" )( 1 )` | `CN¥1.00` | `1,00 CN¥` | `¥ 1.00` | +| `.currencyFormatter( "JPY" )( 1 )` | `¥1` | `1 ¥` | `JP¥ 1` | +| `.currencyFormatter( "GBP" )( 1 )` | `£1.00` | `1,00 £` | `£ 1.00` | +| `.currencyFormatter( "BRL" )( 1 )` | `R$1.00` | `1,00 R$` | `R$ 1.00` | + +For the accounting variation of the symbol format, use `style: "accounting"`. + +```javascript +var formatter; + +Globalize.locale( "en" ); +formatter = Globalize.currencyFormatter( "USD", { style: "accounting" } ); + +formatter( -1 ); // "($1.00)" +``` + +For plural messages, use `style: "name"`. + +```javascript +var formatter; + +Globalize.locale( "en" ); +formatter = Globalize.currencyFormatter( "USD", { style: "name" } ); + +formatter( 0 ); // "0.00 US dollars" +formatter( 1 ); // "1.00 US dollar" +``` + +For comparison, follow the formatting output of different symbols in different +locales using the plural messages `Globalize( locale ).currencyFormatter( currency, +{ style: "name" } )( 1 )`. + +| 3-letter currency code | en (English) | de (German) | zh (Chinese) | +| --- | --- | --- | --- | +| `USD` | `1.00 US dollar` | `1,00 US-Dollar` | `1.00美元` | +| `EUR` | `1.00 euro` | `1,00 Euro` | `1.00欧元` | +| `CNY` | `1.00 Chinese yuan` | `1,00 Chinesischer Yuan` | `1.00人民币` | +| `JPY` | `1 Japanese yen` | `1 Japanischer Yen` | `1日元` | +| `GBP` | `1.00 British pound sterling` | `1,00 Britisches Pfund Sterling` | `1.00英镑` | +| `BRL` | `1.00 Brazilian real` | `1,00 Brasilianischer Real` | `1.00巴西雷亚尔` | + +For the international currency code, use `style: "code"`. + +```javascript +var formatter; + +Globalize.locale( "en" ); +formatter = Globalize.currencyFormatter( "USD", { style: "code" } ); + +formatter( 9.99 ); +// "9.99 USD" +``` + +Override the number of digits, grouping separators, rounding function or any +other [`.numberFormatter()` options](../number/number-formatter.md). + +```javascript +var formatter; + +Globalize.locale( "en" ); +formatter = Globalize.currencyFormatter( "USD", { + minimumFractionDigits: 0, + style: "name" +}); + +formatter( 1 ); // "1 US dollar" + +formatter = Globalize.currencyFormatter( "USD", { + round: "ceil" +}); + +formatter( 1.491 ); // "$1.50" +``` diff --git a/doc/api/currency/format-currency.md b/doc/api/currency/format-currency.md new file mode 100644 index 000000000..ec7fbac37 --- /dev/null +++ b/doc/api/currency/format-currency.md @@ -0,0 +1,45 @@ +## .formatCurrency( value, currency [, options] ) + +Format a currency ( `value`, `currency` ) according to the given `options`. + +*Important*: Use [`.currencyFormatter( currency [, options] +)`](./currency-formatter.md) instead when formatting more then one number, for +improved performance. + +### Parameters + +**value** + +Number to be formatted, eg. `9.99`. + +**currency** + +3-letter currency code as defined by ISO 4217, eg. `USD`. + +**options** Optional + +See [`.currencyFormatter( currency [, options] )`](./currency-formatter.md). + +### Example + +You can use the static method `Globalize.formatCurrency()`, which uses the default +locale. + +```javascript +Globalize.locale( "en" ); +Globalize.formatCurrency( 1, "USD" ); // "$9.99" +Globalize.formatCurrency( 1, "EUR" ); // "€9.99" +``` + +You can use the instance method `.formatCurrency()`, which uses the instance +locale. + +```javascript +var de = new Globalize( "de" ); + +de.formatCurrency( 9.99, "USD" ); // "9,99 $" +de.formatCurrency( 9.99, "EUR" ); // "9,99 €" +``` + +See [`.currencyFormatter( currency [, options] )`](./currency-formatter.md) for +more examples. diff --git a/doc/error/e-missing-plural-module.md b/doc/error/e-missing-plural-module.md new file mode 100644 index 000000000..f86f9c875 --- /dev/null +++ b/doc/error/e-missing-plural-module.md @@ -0,0 +1,10 @@ +## E_MISSING_PLURAL_MODULE + +Thrown when plural module is needed, but not loaded, eg. formatting currencies +using plural messages. + +Error object: + +| Attribute | Value | +| --- | --- | +| code | `E_MISSING_PLURAL_MODULE` | diff --git a/examples/amd-bower/index.html b/examples/amd-bower/index.html index a5f9913ef..77a174e64 100644 --- a/examples/amd-bower/index.html +++ b/examples/amd-bower/index.html @@ -21,6 +21,7 @@

Requirements

Demo output

Now:

A number:

+

A currency:

Plurals: