globalize-rpk 1.7.1 → 1.7.2

package/doc/api/currency/currency-formatter.md

@@ -0,0 +1,196 @@
+## .currencyFormatter( currency [, options] ) ➜ function( value )
+
+Return a function that formats a `currency` 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.style
+
+Optional. String `"symbol"` (default), `"accounting"`, `"code"` or `"name"`. See [`.numberFormatter( [options] )`](../number/number-formatter.md)  for more options.
+
+#### value
+
+Number to be formatted, eg. `9.99`.
+
+### Example
+
+#### Static Formatter
+
+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.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+#### Using the default options
+
+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"
+```
+
+#### Instance Formatter
+
+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`    |
+
+#### Using alternative `options.symbolForm`
+
+Using the narrow symbol form, the same symbols may be used for multiple currencies. Thus the symbol may be ambiguous, and should only be used where the context is clear.
+
+```js
+Globalize( "en" ).currencyFormatter( "HKD" )( 1 );
+// > "HK$1.00"
+
+Globalize( "en" ).currencyFormatter( "HKD", { symbolForm: "narrow" } )( 1 );
+// > "$1.00"
+```
+
+#### Configuring style
+
+For the accounting variation of the symbol format, use `style: "accounting"`.
+
+```javascript
+var formatter = Globalize( "en" ).currencyFormatter( "USD", {
+  style: "accounting"
+});
+
+formatter( -1 );
+// > "($1.00)"
+```
+
+For plural messages, use `style: "name"`.
+
+```javascript
+var formatter = Globalize( "en" ).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( "en" ).currencyFormatter( "USD", {
+  style: "code"
+});
+
+formatter( 9.99 );
+// > "9.99 USD"
+```
+
+#### Configuring inherited number options
+
+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"
+```
+
+#### Formatting Compact Currencies
+
+```js
+var shortFormatter = Globalize( "en" ).currencyFormatter( "USD", {
+  compact: "short"
+});
+
+var longFormatter = Globalize( "en" ).currencyFormatter( "USD", {
+  compact: "long"
+});
+
+shortFormatter( 12830000000 );
+// > "$13B"
+
+longFormatter( 12830000000 );
+// > "$13 billion"
+```
+
+The minimumSignificantDigits and maximumSignificantDigits options are specially useful to control the number of digits to display.
+
+```js
+Globalize( "en" ).formatCurrency( 12830000000, "USD", {
+  compact: "short",
+  minimumSignificantDigits: 3,
+  maximumSignificantDigits: 3
+});
+// > "$12.8B"
+```
+
+#### Performance Suggestion
+
+For improved performance on iterations, first create the formatter. Then, reuse it on each loop.
+
+```javascript
+var formatter = Globalize( "en" ).currencyFormatter( "USD" );
+
+renderInvoice({
+  prices: prices.map(function( price ) {
+    return formatter( price );
+  })
+});
+```

package/doc/api/currency/currency-to-parts-formatter.md

@@ -0,0 +1,117 @@
+## .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](./currency-formatter.md#parameters).
+
+#### 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:
+
+```js
+[
+  { 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()](../number/number-to-parts-formatter.md#returns) 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.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+#### Static Formatter
+
+#### Using the default options
+
+You can use the static method `Globalize.currencyToPartsFormatter()`, which uses the default locale.
+
+```javascript
+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.
+
+```javascript
+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()`][].
+
+[`Array.prototype.map()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map
+[arrow functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
+[switch statement]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch
+[template literals]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals
+[`Array.prototype.reduce()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce
+
+#### More Examples
+
+Please, see [.currencyFormatter() example](./currency-formatter.md#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.
+
+```javascript
+var formatter = Globalize( "en" ).currencyToPartsFormatter( "USD" );
+
+renderInvoice({
+  prices: prices.map(function( price ) {
+    return formatter( price );
+  })
+});
+```

package/doc/api/date/date-formatter.md

@@ -0,0 +1,203 @@
+## .dateFormatter( [options] ) ➜ function( value )
+
+Return a function that formats a date according to the given `options`. The default formatting is numeric year, month, and day (i.e., `{ skeleton: "yMd" }`.
+
+The returned function is invoked with one argument: the Date instance `value` to be formatted.
+
+### Parameters
+
+#### options.skeleton
+
+String value indicating a skeleton (see description above), eg. `{ skeleton: "GyMMMd" }`.
+
+Skeleton provides a more flexible formatting mechanism than the predefined list `full`, `long`, `medium`, or `short` represented by date, time, or datetime. Instead, they are an open-ended list of patterns containing only date field information, and in a canonical order. For a complete list of skeleton patterns [check the unicode CLDR documentation](http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table).
+
+For example:
+
+| locale | `"GyMMMd"` skeleton       |
+| ------ | ------------------------- |
+| *en*   | `"Apr 9, 2014 AD"`        |
+| *zh*   | `"公元2014年4月9日"`           |
+| *es*   | `"9 abr. de 2014 d. C."`  |
+| *ar*   | `"٩ أبريل، ٢٠١٤ م"`       |
+| *pt*   | `"9 de abr de 2014 d.C."` |
+
+#### options.date
+
+One of the following String values: `full`, `long`, `medium`, or `short`, eg., `{ date: "full" }`.
+
+#### options.time
+
+One of the following String values: `full`, `long`, `medium`, or `short`, eg., `{ time: "full" }`.
+
+#### options.datetime
+
+One of the following String values: `full`, `long`, `medium`, or `short`, eg., `{ datetime: "full" }`.
+
+#### options.raw
+
+String value indicating a machine [raw pattern (anything in the "Sym." column)](http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table) eg. `{ raw: "dd/mm" }`. Note this is NOT recommended for i18n in general. Use `skeleton` instead.
+
+#### options.timeZone
+
+String based on the time zone names of the [IANA time zone database](https://www.iana.org/time-zones), such as `"Asia/Shanghai"`, `"Asia/Kolkata"`, `"America/New_York"`.
+
+#### value
+
+Date instance to be formatted, eg. `new Date()`;
+
+### Example
+
+Prior to using any date methods, you must load `cldr/main/{locale}/ca-gregorian.json`, `cldr/main/{locale}/timeZoneNames.json`, `cldr/supplemental/metaZones.json`, `cldr/supplemental/timeData.json`, `cldr/supplemental/weekData.json`, and the CLDR content required by the number module. Read [CLDR content][] if you need more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+```javascript
+var formatter;
+
+Globalize.locale( "en" );
+formatter = Globalize.dateFormatter();
+
+formatter( new Date( 2010, 10, 30, 17, 55 ) );
+// > "11/30/2010"
+```
+
+You can use the instance method `.dateFormatter()`, which uses the instance locale.
+
+```javascript
+var enFormatter = Globalize( "en" ).dateFormatter(),
+  deFormatter = Globalize( "de" ).dateFormatter();
+
+enFormatter( new Date( 2010, 10, 30, 17, 55 ) );
+// > "11/30/2010"
+
+deFormatter( new Date( 2010, 10, 30, 17, 55 ) );
+// > "30.11.2010"
+```
+
+#### Using short, medium, long, and full presets
+
+Use convenient presets for `date`, `time`, or `datetime`. Their possible values are: `short`, `medium`, `long`, and `full`.
+
+| `presetValue`            | `Globalize( "en" ).dateFormatter( presetValue )( new Date( 2010, 10, 1, 17, 55 ) )` |
+| ------------------------ | ---------------------------------------- |
+| `{ date: "short" }`      | `"11/1/10"`                              |
+| `{ date: "medium" }`     | `"Nov 1, 2010"`                          |
+| `{ date: "long" }`       | `"November 1, 2010"`                     |
+| `{ date: "full" }`       | `"Monday, November 1, 2010"`             |
+| `{ time: "short" }`      | `"5:55 PM"`                              |
+| `{ time: "medium" }`     | `"5:55:00 PM"`                           |
+| `{ time: "long" }`       | `"5:55:00 PM PST"`                       |
+| `{ time: "full" }`       | `"5:55:00 PM Pacific Standard Time"`     |
+| `{ datetime: "short" }`  | `"11/1/10, 5:55 PM"`                     |
+| `{ datetime: "medium" }` | `"Nov 1, 2010, 5:55:00 PM"`              |
+| `{ datetime: "long" }`   | `"November 1, 2010 at 5:55:00 PM PST"`   |
+| `{ datetime: "full" }`   | `"Monday, November 1, 2010 at 5:55:00 PM Pacific Standard Time"` |
+
+For comparison, follow the same formatter `{ datetime: "short" }` on different locales.
+
+| locale           | `Globalize( locale ).dateFormatter({ datetime: "short" })( new Date( 2010, 10, 1, 17, 55 ) )` |
+| ---------------- | ---------------------------------------- |
+| *en*             | `"11/1/10, 5:55 PM"`                     |
+| *en_GB*          | `"01/11/2010 17:55"`                     |
+| *zh*             | `"10/11/1 下午5:55"`                       |
+| *zh-u-nu-native* | `"一〇/一一/一 下午五:五五"`                       |
+| *es*             | `"1/11/10 17:55"`                        |
+| *de*             | `"01.11.10 17:55"`                       |
+| *pt*             | `"01/11/10 17:55"`                       |
+| *ar*             | `"١‏/١١‏/٢٠١٠ ٥،٥٥ م"`                   |
+
+#### Using open-ended skeletons
+
+Use open-ended skeletons for more flexibility (see its description [above](#parameters)). See some examples below.
+
+| `skeleton`                   | `Globalize( "en" ).dateFormatter( skeleton )( new Date( 2010, 10, 1, 17, 55 ) )` |
+| ---------------------------- | ---------------------------------------- |
+| `{ skeleton: "E" }`          | `"Tue"`                                  |
+| `{ skeleton: "EHm" }`        | `"Tue 17:55"`                            |
+| `{ skeleton: "EHms" }`       | `"Tue 17:55:00"`                         |
+| `{ skeleton: "Ed" }`         | `"30 Tue"`                               |
+| `{ skeleton: "Ehm" }`        | `"Tue 5:55 PM"`                          |
+| `{ skeleton: "Ehms" }`       | `"Tue 5:55:00 PM"`                       |
+| `{ skeleton: "Gy" }`         | `"2010 AD"`                              |
+| `{ skeleton: "GyMMM" }`      | `"Nov 2010 AD"`                          |
+| `{ skeleton: "GyMMMEd" }`    | `"Tue, Nov 30, 2010 AD"`                 |
+| `{ skeleton: "GyMMMd" }`     | `"Nov 30, 2010 AD"`                      |
+| `{ skeleton: "H" }`          | `"17"`                                   |
+| `{ skeleton: "Hm" }`         | `"17:55"`                                |
+| `{ skeleton: "Hms" }`        | `"17:55:00"`                             |
+| `{ skeleton: "M" }`          | `"11"`                                   |
+| `{ skeleton: "MEd" }`        | `"Tue, 11/30"`                           |
+| `{ skeleton: "MMM" }`        | `"Nov"`                                  |
+| `{ skeleton: "MMMEd" }`      | `"Tue, Nov 30"`                          |
+| `{ skeleton: "MMMd" }`       | `"Nov 30"`                               |
+| `{ skeleton: "Md" }`         | `"11/30"`                                |
+| `{ skeleton: "d" }`          | `"30"`                                   |
+| `{ skeleton: "h" }`          | `"5 PM"`                                 |
+| `{ skeleton: "hm" }`         | `"5:55 PM"`                              |
+| `{ skeleton: "hms" }`        | `"5:55:00 PM"`                           |
+| `{ skeleton: "ms" }`         | `"55:00"`                                |
+| `{ skeleton: "y" }`          | `"2010"`                                 |
+| `{ skeleton: "yM" }`         | `"11/2010"`                              |
+| `{ skeleton: "yMEd" }`       | `"Tue, 11/30/2010"`                      |
+| `{ skeleton: "yMMM" }`       | `"Nov 2010"`                             |
+| `{ skeleton: "yMMMEd" }`     | `"Tue, Nov 30, 2010"`                    |
+| `{ skeleton: "yMMMd" }`      | `"Nov 30, 2010"`                         |
+| `{ skeleton: "yMd" }`        | `"11/30/2010"`                           |
+| `{ skeleton: "yQQQ" }`       | `"Q4 2010"`                              |
+| `{ skeleton: "yQQQQ" }`      | `"4th quarter 2010"`                     |
+| `{ skeleton: "GyMMMEdhms" }` | `"Tue, Nov 30, 2010 AD, 5:55:00 PM"`     |
+| `{ skeleton: "Ehms" }`       | `"Tue 5:55:00 PM"`                       |
+| `{ skeleton: "yQQQHm" }`     | `"Q4 2010, 17:55"`                       |
+| `{ skeleton: "MMMEdhm" }`    | `"Tue, Nov 30, 5:55 PM"`                 |
+| `{ skeleton: "yMMMdhm" }`    | `"Nov 30, 2010, 5:55 PM"`                |
+
+
+```javascript
+var globalize = Globalize( "en" ),
+  date = new Date( 2010, 10, 30, 17, 55 ),
+  monthDayFormatter = globalize.dateFormatter({ skeleton: "MMMd" }),
+  hourMinuteSecondFormatter = globalize.dateFormatter({ skeleton: "Hms" });
+
+monthDayFormatter( date );
+// > "Nov 30"
+
+hourMinuteSecondFormatter( date );
+// > "17:55:00"
+```
+
+#### Using time zones
+
+Using specific timeZones, i.e., using `options.timezone`. Note that prior to using it, you must load IANA time zone data.
+
+```js
+Globalize.loadTimeZone( require( "iana-tz-data" ) );
+```
+
+```js
+Globalize.locale( "en" );
+
+Globalize.dateFormatter({ datetime: "medium", timeZone: "America/Los_Angeles" })( new Date() );
+// > "Nov 1, 2010, 12:55:00 PM"
+
+Globalize.dateFormatter({ datetime: "medium", timeZone: "America/Sao_Paulo" })( new Date() )
+// > "Nov 1, 2010, 5:55:00 PM"
+
+Globalize.dateFormatter({ datetime: "full", timeZone: "Europe/Berlin" })( new Date() )
+// > "Monday, November 1, 2010 at 8:55:00 PM Central European Standard Time"
+```
+
+#### Note on performance
+
+For improved performance on iterations, first create the formatter. Then, reuse it on each loop.
+
+```javascript
+// In an application, this array could have a few hundred entries
+var dates = [ new Date( 2010, 10, 30, 17, 55 ), new Date( 2015, 3, 18, 4, 25 ) ];
+var formatter = Globalize( "en" ).dateFormatter({ time: "short" });
+
+var formattedDates = dates.map(function( date ) {
+  return formatter( date );
+});
+// > Array [ "5:55 PM", "4:25 AM" ]
+```

package/doc/api/date/date-parser.md

@@ -0,0 +1,60 @@
+## .dateParser( [options] ) ➜ function( value )
+
+Return a function that parses a string representing a date into a JavaScript Date object according to the given `options`. The default parsing assumes numeric year, month, and day (i.e., `{ skeleton: "yMd" }`).
+
+The returned function is invoked with one argument: the String `value` to be parsed.
+
+### Parameters
+
+#### options
+
+See [.dateFormatter() options](./date-formatter.md#parameters).
+
+#### value
+
+String with date to be parsed, eg. `"11/1/10, 5:55 PM"`.
+
+### Example
+
+Prior to using any date methods, you must load `cldr/main/{locale}/ca-gregorian.json`, `cldr/main/{locale}/timeZoneNames.json`, `cldr/supplemental/timeData.json`, `cldr/supplemental/weekData.json`, and the CLDR content required by the number module. Read [CLDR content][] if you need more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+You can use the static method `Globalize.dateParser()`, which uses the default locale.
+
+```javascript
+var parser;
+
+Globalize.locale( "en" );
+parser = Globalize.dateParser();
+
+parser( "1/2/2013" );
+// > Wed Jan 02 2013 00:00:00
+
+Globalize.locale( "es" );
+parser = Globalize.dateParser();
+
+parser( "1/2/2013" );
+// > Fri Feb 01 2013 00:00:00
+```
+
+You can use the instance method `.dateParser()`, which uses the instance locale.
+
+```javascript
+var esParser = Globalize( "es" ).dateParser({ date: short });
+
+esParser( "1/2/13" );
+// > Fri Feb 01 2013 00:00:00
+```
+
+For improved performance on iterations, first create the parser. Then, reuse it
+on each loop.
+
+```javascript
+var formattedDates = [ new Date( a ), new Date( b ), ... ];
+var parser = Globalize( "en" ).dateParser({ time: "short" });
+
+dates = formattedDates.map(function( formattedDate ) {
+  return parser( formattedDate );
+});
+```