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:
diff --git a/examples/amd-bower/main.js b/examples/amd-bower/main.js
index a7bff4386..aee804607 100644
--- a/examples/amd-bower/main.js
+++ b/examples/amd-bower/main.js
@@ -28,22 +28,29 @@ require([
"globalize",
// CLDR content.
+ "json!cldr-data/main/en/currencies.json",
"json!cldr-data/main/en/ca-gregorian.json",
"json!cldr-data/main/en/numbers.json",
+ "json!cldr-data/supplemental/currencyData.json",
"json!cldr-data/supplemental/likelySubtags.json",
"json!cldr-data/supplemental/plurals.json",
"json!cldr-data/supplemental/timeData.json",
"json!cldr-data/supplemental/weekData.json",
// Extend Globalize with Date and Number modules.
+ "globalize/currency",
"globalize/date",
"globalize/number",
"globalize/plural"
-], function( Globalize, enGregorian, enNumbers, likelySubtags, pluralsData, timeData, weekData ) {
+], function( Globalize, enCurrencies, enGregorian, enNumbers, currencyData, likelySubtags,
+ pluralsData, timeData, weekData ) {
+
var en, pluralData;
// At this point, we have Globalize loaded. But, before we can use it, we need to feed it on the appropriate I18n content (Unicode CLDR). Read Requirements on Getting Started on the root's README.md for more information.
Globalize.load(
+ currencyData,
+ enCurrencies,
enGregorian,
enNumbers,
likelySubtags,
@@ -63,6 +70,9 @@ require([
// Use Globalize to format numbers.
document.getElementById( "number" ).innerHTML = en.formatNumber( 12345.6789 );
+ // Use Globalize to format currencies.
+ document.getElementById( "currency" ).innerHTML = en.formatCurrency( 69900, "USD" );
+
// Use Globalize to format a message with plural inflection.
pluralData = {
one: "{0} result",
diff --git a/examples/node-npm/main.js b/examples/node-npm/main.js
index d7150fd01..cb2d25407 100644
--- a/examples/node-npm/main.js
+++ b/examples/node-npm/main.js
@@ -5,8 +5,10 @@ var Globalize = require( "globalize" );
// Before we can use Globalize, we need to feed it on the appropriate I18n content (Unicode CLDR). Read Requirements on Getting Started on the root's README.md for more information.
Globalize.load(
+ cldrData( "main/en/currencies" ),
cldrData( "main/en/ca-gregorian" ),
cldrData( "main/en/numbers" ),
+ cldrData( "supplemental/currencyData" ),
cldrData( "supplemental/likelySubtags" ),
cldrData( "supplemental/plurals" ),
cldrData( "supplemental/timeData" ),
@@ -22,6 +24,9 @@ console.log( Globalize.formatDate( new Date(), { datetime: "medium" } ) );
// Use Globalize to format numbers.
console.log( Globalize.formatNumber( 12345 ) );
+// Use Globalize to format currencies.
+console.log( Globalize.formatCurrency( 69900, "USD" ) );
+
// Use Globalize to format a message with plural inflection.
console.log( Globalize.formatPlural( 12345, {
one: "{0} result",
diff --git a/examples/plain-javascript/index.html b/examples/plain-javascript/index.html
index 326db9a0f..3057b1a3f 100644
--- a/examples/plain-javascript/index.html
+++ b/examples/plain-javascript/index.html
@@ -19,6 +19,7 @@ Requirements
Demo output
Now:
A number:
+ A currency:
Plurals:
@@ -45,6 +46,9 @@ Demo output
+
+
+