Intl.PluralRules Spec Proposal

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.[[InitializedIntlObject]] is 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 t be ? GetOption(options, "type", "string", « "cardinal", "ordinal" », "cardinal").
  7. Set pluralRules.[[Type]] to t.
  8. Let opt be a new Record.
  9. Let matcher be ? GetOption(options, "localeMatcher", "string", « "lookup", "best fit" », "best fit").
  10. Set opt.[[localeMatcher]] to matcher.
  11. Perform ? SetNumberFormatOptions(pluralRules, options, 0, 3).
  12. Let r be ResolveLocale(%PluralRules%.[[AvailableLocales]], requestedLocales, opt).
  13. Set pluralRules.[[Locale]] to the value of r.[[Locale]].
  14. Let pluralCategories be a List of Strings representing the possible results of plural selection.
  15. Set pluralRules.[[PluralCategories]] to CreateArrayFromList(pluralCategories).
  16. Set pluralRules.[[InitializedPluralRules]] to true.
  17. Return pluralRules.

1.1.2GetOperands (s)

When the GetOperands abstract operation is called with argument s. It performs the following steps:

  1. Assert: Type(s) is String.
  2. Let n be ? ToNumber(s).
  3. Assert: n is finite.
  4. Let dp be ? Call(%StringProto_indexOf%, s, « "." »).
  5. If dp = -1, then
    1. Set iv to n.
    2. Let f be 0.
    3. Let v be 0.
  6. Else,
    1. Let iv be the substring of s from position 0, inclusive, to position dp, exclusive.
    2. Let fv be the substring of s from position dp, exclusive.
    3. Let f be ? ToNumber(fv).
    4. Let v be ? ToLength(? Get(fv, "length")).
  7. Let i be ? abs(? ToNumber(iv)).
  8. If f ≠ 0, then
    1. Let ft be the value of fv stripped of trailing "0".
    2. Let w be ? ToLength(? Get(ft, "length")).
    3. Let t be ? ToNumber(ft).
  9. Else,
    1. Let w be 0.
    2. Let t be 0.
  10. Return a new Record { [[Number]]: n, [[IntegerDigits]]: i, [[NumberOfFractionDigits]]: v, [[NumberOfFractionDigitsWithoutTrailing]]: w, [[FractionDigits]]: f, [[FractionDigitsWithoutTrailing]]: t }.
Table 1: Internal Slots of Plural Rules Operands
Internal Slot Type Description
[[Number]] Number absolute value of the source number (integer and decimals)
[[IntegerDigits]] Number Number of digits of [[Number]].
[[NumberOfFractionDigits]] Number Number of visible fraction digits in [[Number]], with trailing zeros.
[[NumberOfFractionDigitsWithoutTrailing]] Number Number of visible fraction digits in [[Number]], without trailing zeros.
[[FractionDigits]] Number Number of visible fractional digits in [[Number]], with trailing zeros.
[[FractionDigitsWithoutTrailing]] Number Number of visible fractional digits in [[Number]], without trailing zeros.

1.1.3PluralRuleSelection (locale, type, n, operands)

When the PluralRuleSelection abstract operation is called with four arguments, it performs implementation dependent algorithm to map n to the appropriate plural representation of the Operand Record operands by selecting the rules denoted by type for the corresponding locale, or the String value "other".

1.1.4ResolvePlural (pluralRules, n)

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

The following steps are taken:

  1. Assert: Type(pluralRules) is Object and pluralRules has an [[InitializedPluralRules]] internal slot whose value is true.
  2. Assert: Type(n) is Number.
  3. If isFinite(n) is false, then
    1. Return "other".
  4. Let locale be pluralRules.[[Locale]].
  5. Let type be pluralRules.[[Type]].
  6. Let s be ? FormatNumberToString(pluralRules, n).
  7. Let operands be ? GetOperands(s).
  8. Return ? PluralRuleSelection(locale, type, n, operands).

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, throw a TypeError exception.
  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 [].

Note 1
Unicode Technical Standard 35 describes no locale extension keys that are relevant to pluralization process.
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 ordinary object. %PluralRulesPrototype% is not an Intl.PluralRules instance and does not have an [[InitializedPluralRules]] internal slot or any of the other internal slots of Intl.PluralRules instance objects.

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.3Intl.PluralRules.prototype.select( value )

When the Intl.PluralRules.prototype.select is called with an argument value, the following steps are taken:

  1. Let pluralRules be this value.
  2. If Type(pluralRules) is not Object or pluralRules does not have an [[InitializedPluralRules]] internal slot whose value is true, throw a TypeError exception.
  3. Let n be ? ToNumber(value).
  4. Return ? ResolvePlural(pluralRules, n).

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, minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits, 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.
  • [[MinimumIntegerDigits]] is a non-negative integer Number value indicating the minimum integer digits to be used. Numbers will be padded with leading zeroes if necessary.
  • [[MinimumFractionDigits]] and [[MaximumFractionDigits]] are 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.
  • [[MinimumSignificantDigits]] and [[MaximumSignificantDigits]] are 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.
  • [[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.