Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
Showing
8 changed files
with
261 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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` | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters