globalize-rpk 1.7.0

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

@@ -0,0 +1,202 @@
+## .numberFormatter( [options] ) ➜ function( value )
+
+Return a function that formats a number according to the given options.
+
+The returned function is invoked with one argument: the Number `value` to be formatted.
+
+### Parameters
+
+#### options.style
+
+Optional. String `decimal` (default), or `percent`.
+
+#### options.minimumIntegerDigits 
+
+Optional. Non-negative integer Number value indicating the minimum integer digits to be used. Numbers will be padded with leading zeroes if necessary.
+
+#### options.minimumFractionDigits, options.maximumFractionDigits
+
+Optional. Non-negative integer Number values indicating the minimum and maximum fraction digits to be used. Numbers will be rounded or padded with trailing zeroes if necessary. Either one or both of these properties must be present. If they are, they will override minimum and maximum fraction digits derived from the CLDR patterns.
+
+#### options.minimumSignificantDigits, options.maximumSignificantDigits
+
+Optional. Positive integer Number values indicating the minimum and maximum fraction digits to be shown. Either none or both of these properties are present. If they are, they override minimum and maximum integer and fraction digits. The formatter uses however many integer and fraction digits are required to display the specified number of significant digits.
+
+#### options.round
+
+Optional. String with rounding method `ceil`, `floor`, `round` (default), or `truncate`.
+
+#### options.useGrouping
+
+Optional. Boolean (default is true) value indicating whether a grouping separator should be used.
+
+#### options.compact
+
+Optional. String `short` or `long` indicating which compact number format should be used to represent the number.
+
+### Examples
+
+#### Static Formatter
+
+Prior to using any number methods, you must load `cldr/main/{locale}/numbers.json` and `cldr/supplemental/numberingSystems.json`. Read [CLDR content][] if you need more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+You can use the static method `Globalize.numberFormatter()`, which uses the default locale.
+
+```javascript
+var formatter;
+
+Globalize.locale( "en" );
+formatter = Globalize.numberFormatter();
+
+formatter( 3.141592 );
+// > "3.142"
+```
+
+#### Instance Formatter
+
+You can use the instance method `.numberFormatter()`, which uses the instance
+locale.
+
+```javascript
+var arFormatter = Globalize( "ar" ).numberFormatter(),
+  esFormatter = Globalize( "es" ).numberFormatter(),
+  zhFormatter = Globalize( "zh-u-nu-native" ).numberFormatter();
+
+arFormatter( 3.141592 );
+// > "٣٫١٤٢"
+
+esFormatter( 3.141592 );
+// > "3,142"
+
+zhFormatter( 3.141592 );
+// > "三.一四二"
+```
+
+#### Configuring decimal places
+
+The number of decimal places can be decreased or increased using `minimumFractionDigits` and `maximumFractionDigits`.
+
+```javascript
+Globalize.numberFormatter({ maximumFractionDigits: 2 })( 3.141592 );
+// > "3.14"
+
+Globalize.numberFormatter({ minimumFractionDigits: 2 })( 1.5 );
+// > "1.50"
+```
+
+#### Configuring significant digits
+
+The number of significant (non-zero) digits can be decreased or increased using `minimumSignificantDigits` and `maximumSignificantDigits`.
+
+```javascript
+var formatter = Globalize.numberFormatter({
+  minimumSignificantDigits: 1,
+  maximumSignificantDigits: 3
+});
+
+formatter( 3.141592 );
+// > "3.14"
+
+formatter = Globalize.numberFormatter({
+  minimumSignificantDigits: 1,
+  maximumSignificantDigits: 3
+});
+
+formatter( 12345 );
+// > "12,300"
+
+formatter = Globalize.numberFormatter({
+  minimumSignificantDigits: 1,
+  maximumSignificantDigits: 3
+});
+
+formatter( 0.00012345 );
+// > "0.000123"
+```
+
+#### Formatting Percentages
+
+Numbers can be formatted as percentages.
+
+```javascript
+var enFormatter = Globalize( "en" ).numberFormatter({
+  style: "percent",
+  minimumFractionDigits: 1,
+  maximumFractionDigits: 1
+});
+
+var frFormatter = Globalize( "fr" ).numberFormatter({
+  style: "percent",
+  minimumFractionDigits: 2,
+  maximumFractionDigits: 2
+});
+
+enFormatter( 0.0016 );
+// > "0.2%"
+
+enFormatter( 0.0014 );
+// > "0.1%"
+
+frFormatter( 0.0005 );
+// > "0,05 %"
+```
+
+#### Formatting Compact Numbers
+
+Long numbers can be represented in a compact format, with `short` using abbreviated units and `long` using the full unit name.
+
+```javascript
+var shortFormatter = Globalize( "en" ).numberFormatter({
+  compact: "short"
+});
+
+var longFormatter = Globalize( "en" ).numberFormatter({
+  compact: "long"
+});
+
+shortFormatter( 27588910 );
+// > "28M"
+
+longFormatter( 27588910 );
+// > "28 million"
+```
+
+The minimumSignificantDigits and maximumSignificantDigits options are specially useful to control the number of digits to display.
+
+```js
+Globalize( "en" ).formatNumber( 27588910, {
+  compact: "short",
+  minimumSignificantDigits: 3,
+  maximumSignificantDigits: 3
+});
+// > "27.6M"
+```
+
+#### Configuring Rounding
+
+Numbers with a decreased amount of decimal places can be rounded up, rounded down, rounded arithmetically, or truncated by setting the `round` option to `ceil`, `floor`, `round` (default), or `truncate`.
+
+```javascript
+var formatter = Globalize.numberFormatter({
+  maximumFractionDigits: 2,
+  round: "ceil"
+});
+
+formatter( 3.141592 );
+// > "3.15"
+```
+
+#### Performance Suggestions
+
+For improved performance on iterations, the formatter should be created before the loop.  Then, it can be reused in each iteration.
+
+```javascript
+var numbers = [ 1, 1, 2, 3, ... ];
+var formatter = Globalize( "en" ).numberFormatter();
+
+formattedNumbers = numbers.map(function( number ) {
+  return formatter( number );
+});
+```

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

@@ -0,0 +1,130 @@
+## .numberParser( [options] ) ➜ function( value )
+
+Return a function that parses a String representing a number according to the given options. If value is invalid, `NaN` is returned.
+
+The returned function is invoked with one argument: the String representing a number `value` to be parsed.
+
+### Parameters
+
+#### options
+
+See [.numberFormatter() options](./number-formatter.md#parameters).
+
+#### value
+
+String with number to be parsed, eg. `"3.14"`.
+
+### Example
+
+Prior to using any number methods, you must load `cldr/main/{locale}/numbers.json` and `cldr/supplemental/numberingSystems.json`. Read [CLDR content][] if you need more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+You can use the static method `Globalize.numberParser()`, which uses the default locale.
+
+```javascript
+var parser;
+
+Globalize.locale( "en" );
+parser = Globalize.numberParser();
+
+parser( "3.14" );
+// > 3.14
+```
+
+You can use the instance method `.numberParser()`, which uses the instance locale.
+
+```javascript
+var enParser = Globalize( "en" ).numberParser(),
+  esParser = Globalize( "es" ).numberParser();
+
+enParser( "3.14" );
+// > 3.14
+
+esParser( "3,14" );
+// > 3.14
+```
+
+Some more examples.
+
+```javascript
+var enParser = Globalize( "en" ).numberParser();
+
+enParser( "12,735" );
+// > 12735
+
+enParser( "12,735.00" );
+// > 12735
+
+Globalize( "en" ).numberParser({ style: "percent" })( "100%" );
+// > 1
+
+enParser( "∞" );
+// > Infinity
+
+enParser( "-3" );
+// > -3
+
+enParser( "-∞" );
+// > -Infinity
+
+enParser( "invalid-stuff" );
+// > NaN
+
+enParser( "invalid-stuff-that-includes-number-123" );
+// > NaN
+
+enParser( "invalid-stuff-123-that-includes-number" );
+// > NaN
+
+enParser( "123-invalid-stuff-that-includes-number" );
+// > NaN
+
+// Invalid decimal separator. (note `.` is used as decimal separator for English)
+enParser( "3,14" );
+// > NaN
+
+// Invalid grouping separator position.
+enParser( "127,35.00" );
+// > NaN
+```
+
+Loose matching examples.
+
+```js
+var svParser = Globalize( "sv" ).numberParser();
+
+// Swedish uses NO-BREAK-SPACE U+00A0 as grouping separator.
+svParser( "1\xA0000,50" );
+// > 1000.5
+
+// The parser is lenient and accepts various space characters like regular space
+// SPACE U+0020. Technically, it accepts any character of the Unicode general
+// category [:Zs:].
+svParser( "1 000,50" );
+// > 1000.5
+
+var fiParser = Globalize( "fi" ).numberParser();
+
+// Finish uses MINUS SIGN U+2212 for the minus sign.
+fiParser( "\u22123" );
+// > -3
+
+// The parser is lenient and accepts various hyphen characters like regular
+// HYPHEN-MINUS U+002D. Technically, it accepts any character of the Unicode
+// general category [:Dash:].
+fiParser( "-3" );
+// > -3
+```
+
+For improved performance on iterations, first create the parser. Then, reuse it
+on each loop.
+
+```javascript
+var formattedNumbers = [ "1", "1", "2", "3", ... ];
+var parser = Globalize( "en" ).numberParser();
+
+numbers = formattedNumbers.map(function( formattedNumber ) {
+  return parser( formattedNumber );
+});
+```

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

@@ -0,0 +1,140 @@
+## .numberToPartsFormatter( [options] ) ➜ function( value )
+
+Return a function that formats a number into parts tokens according to the given options.
+
+The returned function is invoked with one argument: the Number `value` to be formatted.
+
+### Parameters
+
+#### options
+
+Please, see [.numberFormatter() options](./number-formatter.md#parameters).
+
+### Returns
+
+An Array of objects containing the formatted number in parts. The returned structure looks like this:
+
+- `decimal`
+
+  The decimal separator string, e.g., `"."`.
+
+- `fraction`
+
+  The fraction number.
+
+- `group`
+
+  The group separator string, e.g., `","`.
+
+- `infinity`
+
+  The Infinity string, e.g., `"∞"`.
+
+- `integer`
+
+  The integer number.
+
+- `literal`
+
+  Any literal strings or whitespace in the formatted number.
+
+- `minusSign`
+
+  The minus sign string, e.g., `"-"`.
+
+- `nan`
+
+  The NaN string, e.g., `"NaN"`.
+
+- `plusSign`
+
+  The plus sign string, e.g., `"+"`.
+
+- `percentSign`
+
+  The percent sign string, e.g., `"%"`. 
+
+- `compact`
+
+  The compact string, e.g., `"thousand"`. 
+
+### Examples
+
+Prior to using any number methods, you must load `cldr/main/{locale}/numbers.json` and `cldr/supplemental/numberingSystems.json`. Read [CLDR content][] if you need more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+#### Static Formatter
+
+You can use the static method `Globalize.numberToPartsFormatter()`, which uses the default locale.
+
+```javascript
+var formatter;
+
+Globalize.locale( "en" );
+formatter = Globalize.numberToPartsFormatter();
+
+formatter( 3.141592 );
+// > [
+//   { "type": "integer", "value": "3" },
+//   { "type": "decimal", "value": "." },
+//   { "type": "fraction", "value": "142" }
+// ]
+```
+
+#### Instance Formatter
+
+You can use the instance method `.numberFormatter()`, which uses the instance
+locale.
+
+```javascript
+var arFormatter = Globalize( "ar" ).numberToPartsFormatter(),
+  esFormatter = Globalize( "es" ).numberToPartsFormatter(),
+  zhFormatter = Globalize( "zh-u-nu-native" ).numberToPartsFormatter();
+
+arFormatter( 3.141592 );
+// > [
+//   { "type": "integer", "value": "٣" },
+//   { "type": "decimal", "value": "٫" },
+//   { "type": "fraction", "value": "١٤٢" }
+// ]
+
+esFormatter( 3.141592 );
+// > [
+//   { "type": "integer", "value": "3" },
+//   { "type": "decimal", "value": "," },
+//   { "type": "fraction", "value": "142" }
+// ]
+
+zhFormatter( 3.141592 );
+// > [
+//   { "type": "integer", "value": "三" },
+//   { "type": "decimal", "value": "." },
+//   { "type": "fraction", "value": "一四二" }
+// ]
+```
+
+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 [.numberFormatter() example](./number-formatter.md#example) for additional examples such as configuring decimal places, significant digits, percentages, and compact numbers.
+
+#### Performance Suggestions
+
+For improved performance on iterations, the formatter should be created before the loop.  Then, it can be reused in each iteration.
+
+```javascript
+var numbers = [ 1, 1, 2, 3, ... ];
+var formatter = Globalize( "en" ).numberFormatter();
+
+formattedNumbers = numbers.map(function( number ) {
+  return formatter( number );
+});
+```

package/doc/api/plural/plural-generator.md

@@ -0,0 +1,84 @@
+## .pluralGenerator( [options] ) ➜ function( value )
+
+It supports the creation of internationalized messages with plural inflection by returning a function that returns the value's plural group: `zero`, `one`, `two`, `few`, `many`, or `other`.
+
+The returned function is invoked with one argument: the Number `value` for which to return the plural group.
+
+### Parameters
+
+#### options.type
+
+Optional. String `cardinal` (default), or `ordinal`.
+
+#### value
+
+A Number for which to return the plural group.
+
+### Example
+
+Prior to using any plural method, you must load either `supplemental/plurals.json` for cardinals or `supplemental/ordinals.json` for ordinals.
+
+Read [CLDR content][] if you need more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+You can use the static method `Globalize.pluralGenerator()`, which uses the default locale.
+
+```javascript
+var plural;
+
+Globalize.locale( "en" );
+
+// Cardinals
+plural = Globalize.pluralGenerator();
+
+plural( 0 );
+// > "other"
+
+plural( 1 );
+// > "one"
+
+plural( 2 );
+// > "other"
+
+// Ordinals
+plural = Globalize.pluralGenerator({ type: "ordinal" });
+
+plural( 0 );
+// > "other"
+
+plural( 1 );
+// > "one"
+
+plural( 2 );
+// > "two"
+```
+
+You can use the instance method `.pluralGenerator()`, which uses the instance locale.
+
+```javascript
+var plural = Globalize( "zh" ).pluralGenerator();
+
+plural( 1 );
+// > "other"
+```
+
+For comparison (cardinals):
+
+|               | en (English) | ru (Russian) | ar (Arabic) |
+| ------------- | ------------ | ------------ | ----------- |
+| `plural( 0 )` | `other`      | `many`       | `zero`      |
+| `plural( 1 )` | `one`        | `one`        | `one`       |
+| `plural( 2 )` | `other`      | `few`        | `two`       |
+| `plural( 3 )` | `other`      | `few`        | `few`       |
+| `plural( 5 )` | `other`      | `many`       | `few`       |
+
+For comparison (ordinals):
+
+|                                    | en (English) | ru (Russian) | ar (Arabic) |
+| ---------------------------------- | ------------ | ------------ | ----------- |
+| `plural( 0, { type: "ordinal" } )` | `other`      | `other`      | `other`     |
+| `plural( 1, { type: "ordinal" } )` | `one`        | `other`      | `other`     |
+| `plural( 2, { type: "ordinal" } )` | `two`        | `other`      | `other`     |
+| `plural( 3, { type: "ordinal" } )` | `few`        | `other`      | `other`     |
+| `plural( 5, { type: "ordinal" } )` | `other`      | `other`      | `other`     |

package/doc/api/relative-time/relative-time-formatter.md

@@ -0,0 +1,60 @@
+## .relativeTimeFormatter( unit [, options] ) ➜ function( value )
+
+Returns a function that formats a relative time according to the given unit, options, and the default/instance locale.
+
+The returned function is invoked with one argument: the number `value` to be formatted.
+
+### Parameters
+
+#### unit
+
+String value indicating the unit to be formatted. eg. "day", "week", "month", etc.
+
+#### options.form
+
+String, e.g., `"short"` or `"narrow"`, or falsy for default long form.
+
+#### value
+
+The number to be formatted.
+
+
+### Example
+
+Prior to using any relative time methods, you must load `cldr/main/{locale}/dateFields.json` and the CLDR content required by the number and plural modules. Read [CLDR content][] if you need more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+You can use the static method `Globalize.relativeTimeFormatter()`, which uses the default locale.
+
+```javascript
+var formatter;
+
+Globalize.locale( "en" );
+formatter = Globalize.relativeTimeFormatter( "month" );
+
+formatter( 1 );
+// > "next month"
+
+formatter( 3 );
+// > "in 3 months"
+
+formatter( -1 );
+// > "last month"
+
+formatter( -3 );
+// > "3 months ago"
+```
+
+You can use the instance method `.relativeTimeFormatter()`, which uses the instance locale.
+
+```javascript
+var globalize = new Globalize( "en" ),
+	formatter = globalize.relativeTimeFormatter( "week" );
+
+formatter( 1 );
+// > "next week"
+```
+
+
+

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

@@ -0,0 +1,72 @@
+## .unitFormatter( unit [, options] ) ➜ function( value )
+
+Returns a function that formats a unit according to the given unit, options, and the default/instance locale.
+
+The returned function is invoked with one argument: the number `value` to be formatted.
+
+### Parameters
+
+#### unit
+
+String value indicating the unit to be formatted. eg. "day", "week", "month", etc. Could also be a compound unit, eg. "mile-per-hour" or "mile/hour"
+
+#### options.form
+
+Optional. String, e.g., `"long"` (default), `"short"` or `"narrow"`.
+
+#### options.numberFormatter
+
+Optional. A number formatter function. Defaults to `Globalize.numberFormatter()` for the current locale using the default options.
+
+#### value
+
+The number to be formatted.
+
+### Example
+
+Prior to using any unit methods, you must load `cldr/main/{locale}/units.json` and the CLDR content required by the plural module. Read [CLDR content][] if you need more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+You can use the static method `Globalize.unitFormatter()`, which uses the default locale.
+
+```javascript
+var customNumberFormatter, formatter;
+
+Globalize.locale( "en" );
+formatter = Globalize.unitFormatter( "month", { form: "long" } );
+
+formatter( 1 );
+// > "1 month"
+
+formatter( 3 );
+// > "3 months"
+
+formatter( 3000 );
+// > "3,000 months"
+```
+
+You can pass a custom number formatter to format the number of units.
+
+```javascript
+var customNumberFormatter, formatter;
+
+Globalize.locale( "en" );
+customNumberFormatter = Globalize.numberFormatter({ useGrouping = false })
+formatter = Globalize.unitFormatter( "mile-per-hour", {
+	form: "narrow", numberFormatter: customNumberFormatter
+} );
+
+formatter(5000)
+// > "5000mph"
+```
+
+You can use the instance method `.unitFormatter()`, which uses the instance locale.
+
+```javascript
+var globalize = new Globalize( "en" ),
+	formatter = globalize.unitFormatter( "mile-per-hour", { form: "narrow" } );
+
+formatter( 10 );
+// > "10mph"
+```