July 14, 2017

Intl.RelativeTimeFormat Spec Proposal

1RelativeTimeFormat Objects

1.1Abstract Operations for RelativeTimeFormat Objects

1.1.1InitializeRelativeTimeFormat (relativeTimeFormat, locales, options)

The abstract operation InitializeRelativeTimeFormat accepts the arguments relativeTimeFormat (which must be an object), locales, and options. It initializes relativeTimeFormat as a RelativeTimeFormat object. It performas the following steps:

  1. If relativeTimeFormat has an [[InitializedIntlObject]] internal slot with value true, throw a TypeError exception.
  2. Set relativeTimeFormat.[[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 matcher be ? GetOption(options, "localeMatcher", "string", «"lookup", "best fit"», "best fit").
  8. Set opt.[[LocaleMatcher]] to matcher.
  9. Let localeData be %RelativeTimeFormat%.[[LocaleData]].
  10. Let r be ResolveLocale(%RelativeTimeFormat%.[[AvailableLocales]], requestedLocales, opt, %RelativeTimeFormat%.[[RelevantExtensionKeys]], localeData).
  11. Set relativeTimeFormat.[[Locale]] to the value of r.[[Locale]].
  12. Let dataLocale be r.[[DataLocale]].
  13. Let s be ? GetOption(options, "style", "string", «"long", "short", "narrow"», "long").
  14. Set relativeTimeFormat.[[Style]] to s.
  15. Let dataLocaleData be Get(localeData, dataLocale).
  16. Let fields be Get(dataLocaleData, "fields").
  17. Assert: fields is an object (see 1.3.3).
  18. Set relativeTimeFormat.[[Fields]] to fields.
  19. Let nfLocale be CreateArrayFromList(« locale »).
  20. Let nfOptions be ObjectCreate(%ObjectPrototype%).
  21. Perform ! CreateDataPropertyOrThrow(nfOptions, "useGrouping", false).
  22. Perform ! CreateDataPropertyOrThrow(nfOptions, "minimumIntegerDigits", 2).
  23. Let relativeTimeFormat.[[NumberFormat]] be ? Construct(%NumberFormat%, « nfLocale, nfOptions »).
  24. Let prLocale be CreateArrayFromList(« locale »).
  25. Let prOptions be ObjectCreate(%ObjectPrototype%).
  26. Perform ! CreateDataPropertyOrThrow(prOptions, "style", "cardinal").
  27. Let relativeTimeFormat.[[PluralRules]] be ? Construct(%PluralRules%, « prLocale, prOptions »).
  28. Set relativeTimeFormat.[[InitializedRelativeTimeFormat]] to true.
  29. Return relativeTimeFormat.

1.1.2PartitionRelativeTimePattern (relativeTimeFormat, value, unit)

When the FormatRelativeTime abstract operation is called with arguments relativeTimeFormat, value, and unit it returns a String value representing value (interpreted as a time value as specified in ES2016, 20.3.1.1) according to the effective locale and the formatting options of relativeTimeFormat.

  1. Assert: relativeTimeFormat.[[InitializedRelativeTimeFormat]] is true.
  2. Assert: Type(value) is a Number.
  3. Assert: Type(unit) is a String.
  4. If isFinite(value) is false, then throw a RangeError exception.
  5. If unit is not one of "second", "minute", "hour", "day", "week", "month", "quarter", "year", throw a RangeError exception.
  6. Let fields be relativeTimeFormat.[[Fields]].
  7. Let style be relativeTimeFormat.[[Style]].
  8. If style is equal to "short", then
    1. Let entry be unit + "-short".
  9. Else if style is equal to "narrow", then
    1. Let entry be unit + "-narrow".
  10. Else
    1. Let entry be unit.
  11. Let exists be ? HasProperty(fields, entry).
  12. If exists is false, then
    1. Let entry be unit.
  13. Let patterns be ? Get(fields, entry).
  14. Let exists be ? HasProperty(patterns, ToString(value)).
  15. If exists is true, then
    1. Let result be Get(patterns, ToString(value)).
    2. Return a List containing the Record { [[Type]]: "literal", [[Value]]: result }.
  16. If value is less than 0, then
    1. Let tl be "past".
  17. Else
    1. Let tl be "future".
  18. Let po be ? Get(patterns, tl).
  19. Let fv be ! FormatNumber(relativeTimeFormat.[[NumberFormat]], value).
  20. Let pr be ! ResolvePlural(relativeTimeFormat.[[PluralRules]], value).
  21. Let pattern be ? Get(po, pr).
  22. Return ? MakePartsList(pattern, unit, fv).

1.1.3MakePartsList ( parts, unit, value )

The MakePartsList abstract operation is called with arguments parts, a pattern String, unit, a String, and value a String. Note

Example: 

          MakePartsList("AA{0}BB", "hour", "15")  --<

        Output (List of Records):
          [
            {type: 'literal', value: 'AA'},
            {type: 'hour', value: '15'},
            {type: 'literal', value: 'BB'},
          ]

  1. Let result be a new empty List.
  2. Let beginIndex be Call(%StringProto_indexOf%, pattern, "{", 0).
  3. Let length be ! Get(parts, "length").
  4. Assert: length is a non-negative integer.
  5. Repeat while beginIndex is an integer index into pattern:
    1. Set endIndex to Call(%StringProto_indexOf%, pattern, "}", beginIndex)
    2. Assert: endIndex is not -1, otherwise the pattern would be malformed.
    3. If beginIndex is greater than nextIndex, then:
      1. Let literal be a substring of pattern from position nextIndex, inclusive, to position beginIndex, exclusive.
      2. Add new part record { [[Type]]: "literal", [[Value]]: literal } as a new element of the list result.
    4. Let p be the substring of pattern from position beginIndex, exclusive, to position endIndex, exclusive.
    5. Assert: p is "0".
    6. Add new part Record { [[Type]]: unit, [[Value]]: value } as a new element on the List result.
  6. If nextIndex is less than length, then:
    1. Let literal be the substring of pattern from position nextIndex, exclusive, to position length, exclusive.
    2. Add new part record { [[Type]]: "literal", [[Value]]: literal } as a new element of the list result.
  7. Return result.

1.1.4FormatRelativeTime (relativeTimeFormat, value, unit)

The FormatRelativeTime abstract operation is called with arguments relativeTimeFormat (which must be an object initialized as a RelativeTimeFormat), value (which must be a Number value), and unit (which must be a String denoting the value unit) and performs the following steps:

  1. Let parts be ? PartitionRelativeTimePattern(relativeTimeFormat, value, unit).
  2. Let result be an empty String.
  3. For each part in parts, do:
    1. Set result to a String value produced by concatenating result and part.[[Value]].
  4. Return result.

1.1.5FormatRelativeTimeToParts (relativeTimeFormat, value, unit)

The FormatRelativeTimeToParts abstract operation is called with arguments relativeTimeFormat (which must be an object initialized as a RelativeTimeFormat), value (which must be a Number value), and unit (which must be a String denoting the value unit) and performs the following steps:

  1. Let parts be ? PartitionRelativeTimePattern(relativeTimeFormat, value, unit).
  2. Let result be ArrayCreate(0).
  3. Let n be 0.
  4. For each part in parts, do:
    1. Let O be ObjectCreate(%ObjectPrototype%).
    2. Perform ! CreateDataPropertyOrThrow(O, "type", part.[[Type]]).
    3. Perform ! CreateDataPropertyOrThrow(O, "value", part.[[Value]]).
    4. Perform ! CreateDataPropertyOrThrow(result, ! ToString(n), O).
    5. Increment n by 1.
  5. Return result.

1.2The Intl.RelativeTimeFormat Constructor

The RelativeTimeFormat 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.RelativeTimeFormat ([ locales [ , options ]])

When the Intl.RelativeTimeFormat 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 relativeTimeFormat be ! OrdinaryCreateFromConstructor(newTarget, %RelativeTimeFormatPrototype%).
  3. Return ? InitializeRelativeTimeFormat(relativeTimeFormat, locales, options).

1.3Properties of the Intl.RelativeTimeFormat Constructor

The Intl.RelativeTimeFormat constructor has the following properties:

1.3.1Intl.RelativeTimeFormat.prototype

The value of Intl.RelativeTimeFormat.prototype is %RelativeTimeFormatPrototype%.

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

1.3.2Intl.RelativeTimeFormat.supportedLocalesOf (locales [, options ])

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

  1. Let availableLocales be %RelativeTimeFormat%.[[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 relative time formatting.

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

  • [[LocaleData]][Locale] has ordinary data properties "second", "minute", "hour", "day", "week", "month", "quarter" and "year". Additional property keys may exist with the previous names concatenated with the strings "-narrow" or "-short". The values corresponding to these property keys are objects which contain these two categories of properties:
    • "future" and "past" properties, which are objects with a property for each of the [[PluralCategories]] in the Locale. The value corresponding to those properties is a pattern which may contain "{0}" to be replaced by a formatted number.
    • Optionally, additional properties whose key is the result of ToString of a Number, and whose values are literal Strings which are not treated as templates.
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.RelativeTimeFormat Prototype Object

The Intl.RelativeTimeFormat prototype object is itself an ordinary object. %RelativeTimeFormatPrototype% is not an Intl.RelativeTimeFormat instance and does not have an [[InitializedRelatimveTimeFormat]] internal slot or any of the other internal slots of Intl.RelativeTimeFormat instance objects.

In the following descriptions of functions that are properties or [[Get]] attributes of properties of %RelativeTimeFormatPrototype%, the phrase "this RelativeTimeFormat 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 [[InitializedRelativeTimeFormat]] internal slot with value true.

1.4.1Intl.RelativeTimeFormat.prototype.constructor

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

1.4.2Intl.RelativeTimeFormat.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.RelativeTimeFormat.prototype.format( value, unit )

When the Intl.RelativeTimeFormat.prototype.format is called with an optional argument value, the following steps are taken:

  1. Let relativeTimeFormat be this value.
  2. If Type(relativeTimeFormat) is not Object or relativeTimeFormat does not have an [[InitializedRelativeTimeFormat]] internal slot whose value is true, throw a TypeError exception.
  3. Let value be ? ToNumber(value).
  4. Let unit be ? ToString(unit).
  5. Return ? FormatRelativeTime(relativeTimeFormat, value, unit).

1.4.4Intl.RelativeTimeFormat.prototype.formatToParts( value, unit )

When the Intl.RelativeTimeFormat.prototype.formatToParts is called with an optional argument value, the following steps are taken:

  1. Let relativeTimeFormat be this value.
  2. If Type(relativeTimeFormat) is not Object or relativeTimeFormat does not have an [[InitializedRelativeTimeFormat]] internal slot whose value is true, throw a TypeError exception.
  3. Let value be ? ToNumber(value).
  4. Let unit be ? ToString(unit).
  5. Return ? FormatRelativeTimeToParts(relativeTimeFormat, value, unit).

1.4.5Intl.RelativeTimeFormat.prototype.resolvedOptions ()

This function provides access to the locale and formatting 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 RelativeTimeFormat object (see 1.5): locale and style.

1.5Properties of Intl.RelativeTimeFormat Instances

Intl.RelativeTimeFormat instances inherit properties from %RelativeTimeFormatPrototype%.

Intl.RelativeTimeFormat instances and other objects that have been successfully initialized as a RelativeTimeFormat have [[InitializedIntlObject]] and [[InitializedRelativeTimeFormat]] internal slots whose values are true.

Objects that have been successfully initialized as a RelativeTimeFormat 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 for formatting.
  • [[Style]] is one of the String values "long", "short", or "narrow", identifying the relative time format style used.