Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Doc: Add currency formatting
- Add `.currencyFormatter( currency [, options] )`;
- Add `.formatCurrency( value, currency [, options] )`;

Fixes #238
Closes #351
  • Loading branch information
rxaviers committed Dec 10, 2014
1 parent a267613 commit 87e1f55
Show file tree
Hide file tree
Showing 8 changed files with 261 additions and 4 deletions.
30 changes: 27 additions & 3 deletions README.md
Expand Up @@ -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)
Expand Down Expand Up @@ -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 |

<a name="browser_support"></a>
Expand Down Expand Up @@ -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<br>cldr/supplemental/currencyData.json<br>+CLDR JSON files from number module |
| Date module | cldr/main/`locale`/ca-gregorian.json<br>cldr/main/`locale`/timeZoneNames.json<br>cldr/supplemental/timeData.json<br>cldr/supplemental/weekData.json<br>+CLDR JSON files from number module |
| Number module | cldr/main/`locale`/numbers.json<br>cldr/supplemental/numberingSystems.json |
| Plural module | cldr/supplemental/plurals.json |
Expand Down Expand Up @@ -310,6 +313,22 @@ to you in different flavors):

[Read more...](doc/api/number/parse-number.md)

<a name="currency_module"></a>
#### 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)

<a name="plural_module"></a>
### Plural module

Expand Down Expand Up @@ -379,6 +398,11 @@ to you in different flavors):
setting the Global locale with `Globalize.locale( <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.
Expand Down
127 changes: 127 additions & 0 deletions 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"
```
45 changes: 45 additions & 0 deletions 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.
10 changes: 10 additions & 0 deletions 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` |
1 change: 1 addition & 0 deletions examples/amd-bower/index.html
Expand Up @@ -21,6 +21,7 @@ <h2>Requirements</h2>
<h2>Demo output</h2>
<p>Now: <span id="date"></span></p>
<p>A number: <span id="number"></span></p>
<p>A currency: <span id="currency"></span></p>
<p>Plurals:</p>
<ul>
<li><span id="plural-0"></li>
Expand Down
12 changes: 11 additions & 1 deletion examples/amd-bower/main.js
Expand Up @@ -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,
Expand All @@ -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",
Expand Down
5 changes: 5 additions & 0 deletions examples/node-npm/main.js
Expand Up @@ -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" ),
Expand All @@ -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",
Expand Down
35 changes: 35 additions & 0 deletions examples/plain-javascript/index.html
Expand Up @@ -19,6 +19,7 @@ <h2>Requirements</h2>
<h2>Demo output</h2>
<p>Now: <span id="date"></span></p>
<p>A number: <span id="number"></span></p>
<p>A currency: <span id="currency"></span></p>
<p>Plurals:</p>
<ul>
<li><span id="plural-0"></li>
Expand All @@ -45,6 +46,9 @@ <h2>Demo output</h2>
<script src="../../dist/globalize/number.js"></script>
<script src="../../dist/globalize/plural.js"></script>

<!-- Load after globalize/number.js -->
<script src="../../dist/globalize/currency.js"></script>

<script>

// At this point, we have Globalize loaded. But, before we can use it, we
Expand Down Expand Up @@ -110,6 +114,11 @@ <h2>Demo output</h2>
}
},
"numbers": {
"currencies": {
"USD": {
"symbol": "$"
}
},
"defaultNumberingSystem": "latn",
"symbols-numberSystem-latn": {
"decimal": ".",
Expand All @@ -124,6 +133,21 @@ <h2>Demo output</h2>
},
"decimalFormats-numberSystem-latn": {
"standard": "#,##0.###"
},
"currencyFormats-numberSystem-latn": {
"currencySpacing": {
"beforeCurrency": {
"currencyMatch": "[:^S:]",
"surroundingMatch": "[:digit:]",
"insertBetween": " "
},
"afterCurrency": {
"currencyMatch": "[:^S:]",
"surroundingMatch": "[:digit:]",
"insertBetween": " "
}
},
"standard": "¤#,##0.00"
}
}
}
Expand All @@ -133,6 +157,14 @@ <h2>Demo output</h2>
"_cldrVersion": "25",
"_number": "$Revision: 91 $"
},
"currencyData": {
"fractions": {
"DEFAULT": {
"_rounding": "0",
"_digits": "2"
}
}
},
"likelySubtags": {
"en": "en-Latn-US",
},
Expand All @@ -156,6 +188,9 @@ <h2>Demo output</h2>
// 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.
var pluralData = {
one: "{0} result",
Expand Down

0 comments on commit 87e1f55

Please sign in to comment.