Intl.PluralForm Specification Proposal

Proposal Details

Current Stage: 1 / Nov 2015

1PluralRules Objects#

1.1Abstract Operations for PluralRules Objects#

1.1.1InitializePluralRules (pluralRules, locales, options)#

The abstract operation InitializePluralRules accepts the arguments pluralRules (which must be an object), locales, and options. It initializes pluralRules as a PluralRules object. It performs the following steps:

  1. If pluralRules has an [[initializedIntlObject]] internal slot with value true, throw a TypeError exception.
  2. Set pluralRules.[[initializedIntlObject]] to true.
  3. Let requestedLocales be ? CanonicalizeLocaleList(locales).
  4. If options is undefined, then
    1. Let options be ObjectCreate(%ObjectPrototype%).
  5. Else
    1. Let options be ? ToObject(options).
  6. Let opt be a new Record.
  7. Let s be ? GetOption(options, "type", "string", « "cardinal", "ordinal" », "cardinal").
  8. Set pluralRules.[[type]] to s.
  9. Let localeData be %PluralRules%.[[localeData]].
  10. Let r be ResolveLocale(%PluralRules%.[[availableLocales]], requestedLocales, opt, %PluralRules%.[[relevantExtensionKeys]], localeData).
  11. Set pluralRules.[[locale]] to the value of r.[[locale]].
  12. Let dataLocale be r.[[dataLocale]].
  13. Let dataLocaleData be Get(localeData, dataLocale).
  14. Let pluralRules be Get(dataLocaleData, "pluralRules").
  15. Assert: pluralRules is an object (see 1.3.3).
  16. Set pluralRules.[[pluralRule]] to Get(pluralRules, s).
  17. Set pluralRules.[[boundResolve]] to undefined.
  18. Set pluralRules.[[initializedPluralRules]] to true.
  19. Return pluralRules.

1.1.2Plural Rules Functions#

A PluralRules select function is an anonymous function that takes one argument value, and performs the following steps:

  1. Let pluralRules be the this value.
  2. Assert: Type(pluralRules) is Object and pluralRules has an [[initializedPluralRules]] internal slot whose value is true.
  3. If value is not provided, let value be undefined.
  4. Let x be ? ToNumber(value).
  5. Return ResolvePlural(pluralRules, x).

1.1.3ResolvePlural (pluralRules, x)#

When the ResolvePlural abstract operation is called with arguments pluralRules (which must be an object initialized as a PluralRules) and x (which must be a Number value), it returns a String value representing the plural form of x according to the effective locale and the options of pluralRules.

The following steps are taken:

  1. Assert: Type(pluralRules) is an Object, and pluralRules's internal slot[[initializedPluralRules]] is true.
  2. Assert: Type(x) is a Number value.
  3. Let pluralRuleFunction be the value of pluralRules.[[pluralRule]].
  4. If the result of isFinite(x) is false, then
    1. If x is NaN, then
      1. Let n be an ILD String value indicating the NaN value.
    2. Else
      1. If x < 0, then
        1. let n be -Infinity.
      2. Else
        1. Let n be Infinity.
  5. Else
    1. If x < 0, then
      1. Let n be -x.
    2. Else
      1. Let n be x.
  6. NOTE n might need to be transform ToString() to preserve decimals.
  7. Let result be pluralRuleFunction(n).
  8. Return result.
Note 1 The computations rely on String values and locations within numeric strings that are dependent upon the implementation and the effective locale of pluralRules (“ILD") or upon the implementation. The ILD String mentioned, must not contain any characters in the General Category “Number, decimal digit" as specified by the Unicode Standard. Note 2 It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at http://cldr.unicode.org/).

1.2The Intl.PluralRules Constructor#

The PluralRules constructor is a standard built-in property of the Intl object. Behaviour common to all service constructor properties of the Intl object is specified in .

1.2.1Intl.PluralRules ([ locales [ , options ]])#

When the Intl.PluralRules function is called with optional arguments the following steps are taken:

  1. If NewTarget is undefined, let newTarget be the active function object, else let newTarget be NewTarget.
  2. Let pluralRules be ? OrdinaryCreateFromConstructor(newTarget, %PluralRulesPrototype%).
  3. Return InitializePluralRules(pluralRules, locales, options).

1.3Properties of the Intl.PluralRules Constructor#

The Intl.PluralRules constructor has the following properties:

1.3.1Intl.PluralRules.prototype#

The value of Intl.PluralRules.prototype is %PluralRulesPrototype%.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

1.3.2Intl.PluralRules.supportedLocalesOf (locales [, options ])#

When the supportedLocalesOf method of %PluralRules% is called, the following steps are taken:

  1. Let availableLocales be %PluralRules%.[[availableLocales]].
  2. Let requestedLocales be CanonicalizeLocaleList(locales).
  3. Return SupportedLocales(availableLocales, requestedLocales, options).

The value of the length property of the supportedLocalesOf method is 1.

1.3.3Internal slots#

The value of the [[availableLocales]] internal slot is implementation defined within the constraints described in .

The value of the [[relevantExtensionKeys]] internal slot is ["ptc", "pto"].

Note 1 Unicode Technical Standard 35 describes two locale extension keys that are relevant to pluralization process, "ptc" for language plural type cardinal, and "pto" for plural type ordinal.

The value of the [[localeData]] internal slot is implementation defined within the constraints described in and the following additional constraints:

  • [[localeData]][locale] must have a pluralRules property for all locale values. The value of this property must be an object, which must have properties with the names of the two plural types: "ordinal" and "cardinal". Each of these properties in turn must be a function. These functions expect a numeric argument and the return must be string value "zero", "one", "two", "few", "many" or "other". The returned string represents the pluralization form of the numeric argument as specified in LDML Language Plural Rules.
Note 2 It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at http://cldr.unicode.org/).

1.4Properties of the Intl.PluralRules Prototype Object#

The Intl.PluralRules prototype object is itself an Intl.PluralRules instance as specified in 1.5, whose internal slots are set as if it had been constructed by the expression Construct(%PluralRules%).

In the following descriptions of functions that are properties or [[Get]] attributes of properties of %PluralRulesPrototype%, the phrase "this PluralRules object" refers to the object that is the this value for the invocation of the function; a TypeError exception is thrown if the this value is not an object or an object that does not have an [[initializedPluralRules]] internal slot with value true.

1.4.1Intl.PluralRules.prototype.constructor#

The initial value of Intl.PluralRules.prototype.constructor is %PluralRules%.

1.4.2Intl.PluralRules.prototype [ @@toStringTag ]#

The initial value of the @@toStringTag property is the string value "Object".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

1.4.3get Intl.PluralRules.prototype.select#

Intl.PluralRules.prototype.select is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let pf be this value.
  2. If Type(pf) is not Object, throw a TypeError exception.
  3. If pf.[[boundResolve]] is undefined, then
    1. Let F be a new built-in function object as defined in 1.1.2.
    2. The value of F’s length property is 1.
    3. Let bf be BoundFunctionCreate(F, pf).
    4. Set pf.[[boundResolve]] to bf.
  4. Return pf.[[boundResolve]].

1.4.4Intl.PluralRules.prototype.resolvedOptions ()#

This function provides access to the locale and options computed during initialization of the object.

The function returns a new object whose properties and attributes are set as if constructed by an object literal assigning to each of the following properties the value of the corresponding internal slot of this PluralRules object (see 1.5): locale, type, and pluralCategories. Properties whose corresponding internal slots are not present are not assigned.

1.5Properties of Intl.PluralRules Instances#

Intl.PluralRules instances inherit properties from %PluralRulesPrototype%.

Intl.PluralRules instances and other objects that have been successfully initialized as a PluralRules have [[initializedIntlObject]] and [[initializedPluralRules]] internal slots whose values are true.

Objects that have been successfully initialized as a PluralRules object also have several internal slots that are computed by the constructor:

  • [[locale]] is a String value with the language tag of the locale whose localization is used by the plural rules.
  • [[type]] is one of the String values "cardinal", or "ordinal", identifying the plural rules used.
  • [[pluralCategories]] is an array of unique string values, from the the list "zero", "one", "two", "few", "many" and "other", that are relevant for the locale whose localization is specified in LDML Language Plural Rules.

Finally, objects that have been successfully initialized as a PluralRules have a [[boundResolve]] internal slot that caches the function returned by the select accessor (1.4.3).