Stage 3 Draft / February 3, 2020

Intl.ListFormat

1 ListFormat Objects

1.1 Abstract Operations for ListFormat Objects

1.1.1 DeconstructPattern ( pattern, placeables )

The DeconstructPattern abstract operation is called with arguments pattern (which must be a String) and placeables (which must be a Record), and deconstructs the pattern string into a list of parts. The placeables record is a record whose keys are placeables tokens used in the pattern string, and values are parts records which will be used in the result List to represent the token part. Example: 

        Input:
          DeconstructPattern("AA{xx}BB{yy}CC", {
            [[xx]]: {[[Type]]: "hour", [[Value]]: "15"},
            [[yy]]: {[[Type]]: "minute", [[Value]]: "06"}
          })

        Output (List of parts records):
          «
            {[[Type]]: "literal", [[Value]]: "AA"},
            {[[Type]]: "hour", [[Value]]: "15"},
            {[[Type]]: "literal", [[Value]]: "BB"},
            {[[Type]]: "minute", [[Value]]: "06"},
            {[[Type]]: "literal", [[Value]]: "CC"}
          »

  1. Let patternParts be PartitionPattern(pattern).
  2. Let result be a new empty List.
  3. For each element patternPart of patternParts, in List order, do
    1. Let part be patternPart.[[Type]].
    2. If part is "literal", then
      1. Append Record { [[Type]]: "literal", [[Value]]: patternPart.[[Value]] } to result.
    3. Else,
      1. Assert: placeables has a field [[<part>]].
      2. Let subst be placeables.[[<part>]].
      3. If Type(subst) is List, then
        1. For each element s of subst in List order, do
          1. Append s to result.
      4. Else,
        1. Append subst to result.
  4. Return result.

1.1.2 CreatePartsFromList ( listFormat, list )

The CreatePartsFromList abstract operation is called with arguments listFormat (which must be an object initialized as a ListFormat) and list (which must be a List of String values), and creates the corresponding list of parts according to the effective locale and the formatting options of listFormat. Each part is a Record with two fields: [[Type]], which must be a string with values "element" or "literal", and [[Value]] which must be a string or a number. The following steps are taken:

  1. Let size be the number of elements of list.
  2. If size is 0, then
    1. Return a new empty List.
  3. If size is 2, then
    1. Let pattern be listFormat.[[TemplatePair]].
    2. Let first be a new Record { [[Type]]: "element", [[Value]]: list[0] }.
    3. Let second be a new Record { [[Type]]: "element", [[Value]]: list[1] }.
    4. Let placeables be a new Record { [[0]]: first, [[1]]: second }.
    5. Return DeconstructPattern(pattern, placeables).
  4. Let last be a new Record { [[Type]]: "element", [[Value]]: list[size - 1] }.
  5. Let parts be « last ».
  6. Let i be size - 2.
  7. Repeat, while i ≥ 0
    1. If i is 0, then
      1. Let pattern be listFormat.[[TemplateStart]].
    2. Else, if i is less than size - 2, then
      1. Let pattern be listFormat.[[TemplateMiddle]].
    3. Else,
      1. Let pattern be listFormat.[[TemplateEnd]].
    4. Let head be a new Record { [[Type]]: "element", [[Value]]: list[i] }.
    5. Let placeables be a new Record { [[0]]: head, [[1]]: parts }.
    6. Set parts to DeconstructPattern(pattern, placeables).
    7. Decrement i by 1.
  8. Return parts.

1.1.3 FormatList ( listFormat, list )

The FormatList abstract operation is called with arguments listFormat (which must be an object initialized as a ListFormat) and list (which must be a List of String values), and performs the following steps:

  1. Let parts be CreatePartsFromList(listFormat, list).
  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.4 FormatListToParts ( listFormat, list )

The FormatListToParts abstract operation is called with arguments listFormat (which must be an object initialized as a ListFormat) and list (which must be a List of String values), and performs the following steps:

  1. Let parts be CreatePartsFromList(listFormat, list).
  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.1.5 StringListFromIterable ( iterable )

The abstract operation StringListFromIterable performs the following steps:

  1. If iterable is undefined, then
    1. Return a new empty List.
  2. Let iteratorRecord be ? GetIterator(iterable).
  3. Let list be a new empty List.
  4. Let next be true.
  5. Repeat, while next is not false
    1. Set next to ? IteratorStep(iteratorRecord).
    2. If next is not false, then
      1. Let nextValue be ? IteratorValue(next).
      2. If Type(nextValue) is not String, then
        1. Let error be ThrowCompletion(a newly created TypeError object).
        2. Return ? IteratorClose(iteratorRecord, error).
      3. Append nextValue to the end of the List list.
  6. Return list.
Note

This algorithm raises exceptions when it encounters values that are not Strings, because there is no obvious locale-aware coercion for arbitrary values.

1.2 The Intl.ListFormat Constructor

The ListFormat constructor is the %ListFormat% intrinsic object and a standard built-in property of the Intl object. Behaviour common to all service constructor properties of the Intl object is specified in 9.1.

1.2.1 Intl.ListFormat ( [ locales [ , options ] ] )

When the Intl.ListFormat function is called with optional arguments locales and options, the following steps are taken:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let listFormat be ? OrdinaryCreateFromConstructor(NewTarget, "%ListFormatPrototype%", « [[InitializedListFormat]], [[Locale]], [[Type]], [[Style]], [[TemplatePair]], [[TemplateStart]], [[TemplateMiddle]], [[TemplateEnd]] »).
  3. Let requestedLocales be ? CanonicalizeLocaleList(locales).
  4. If options is undefined, then
    1. Let options be ObjectCreate(null).
  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 %ListFormat%.[[LocaleData]].
  10. Let r be ResolveLocale(%ListFormat%.[[AvailableLocales]], requestedLocales, opt, %ListFormat%.[[RelevantExtensionKeys]], localeData).
  11. Set listFormat.[[Locale]] to r.[[locale]].
  12. Let type be ? GetOption(options, "type", "string", « "conjunction", "disjunction", "unit" », "conjunction").
  13. Set listFormat.[[Type]] to type.
  14. Let style be ? GetOption(options, "style", "string", « "long", "short", "narrow" », "long").
  15. Set listFormat.[[Style]] to style.
  16. Let dataLocale be r.[[dataLocale]].
  17. Let dataLocaleData be localeData.[[<dataLocale>]].
  18. Let dataLocaleTypes be dataLocaleData.[[<type>]].
  19. Let templates be dataLocaleTypes.[[<style>]].
  20. Set listFormat.[[TemplatePair]] to templates.[[Pair]].
  21. Set listFormat.[[TemplateStart]] to templates.[[Start]].
  22. Set listFormat.[[TemplateMiddle]] to templates.[[Middle]].
  23. Set listFormat.[[TemplateEnd]] to templates.[[End]].
  24. Return listFormat.

1.3 Properties of the Intl.ListFormat Constructor

The Intl.ListFormat constructor has the following properties:

1.3.1 Intl.ListFormat.prototype

The value of Intl.ListFormat.prototype is %ListFormatPrototype%.

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

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

When the supportedLocalesOf method is called with arguments locales and options, the following steps are taken:

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

1.3.3 Internal slots

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

The value of the [[RelevantExtensionKeys]] internal slot is « ».

Note 1
Intl.ListFormat does not have any relevant extension keys.

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

  • [[LocaleData]][Locale] must have a formats field for all locale values. The value of this field must be a record, which must have fields with the names of the three list formatting types: conjunction, disjunction, and unit. Each record must have fields with the names of three formatting styles: long, short, and narrow. Each of those fields must be records themselves, and each must have fields with names: Pair, Start, Middle, and End. Each of those fields must be a template string as specified in LDML List Format 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/). In LDML's listPattern, conjunction corresponds to "standard", disjunction corresponds to "or", and unit corresponds to "unit".
Note 3
Among the list types, conjunction stands for "and"-based lists (e.g., "A, B, and C"), disjunction stands for "or"-based lists (e.g., "A, B, or C"), and unit stands for lists of values with units (e.g., "5 pounds, 12 ounces").

1.4 Properties of the Intl.ListFormat Prototype Object

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

1.4.1 Intl.ListFormat.prototype.constructor

The initial value of Intl.ListFormat.prototype.constructor is the intrinsic object %ListFormat%.

1.4.2 Intl.ListFormat.prototype [ @@toStringTag ]

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

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

1.4.3 Intl.ListFormat.prototype.format ( list )

When the format method is called with an argument list, the following steps are taken:

  1. Let lf be the this value.
  2. If Type(lf) is not Object, throw a TypeError exception.
  3. If lf does not have an [[InitializedListFormat]] internal slot, throw a TypeError exception.
  4. Let stringList be ? StringListFromIterable(list).
  5. Return FormatList(lf, stringList).

1.4.4 Intl.ListFormat.prototype.formatToParts ( list )

When the formatToParts method is called with an argument list, the following steps are taken:

  1. Let lf be the this value.
  2. If Type(lf) is not Object, throw a TypeError exception.
  3. If lf does not have an [[InitializedListFormat]] internal slot, throw a TypeError exception.
  4. Let stringList be ? StringListFromIterable(list).
  5. Return FormatListToParts(lf, stringList).

1.4.5 Intl.ListFormat.prototype.resolvedOptions ()

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

  1. Let lf be the this value.
  2. If Type(lf) is not Object, throw a TypeError exception.
  3. If lf does not have an [[InitializedListFormat]] internal slot, throw a TypeError exception.
  4. Let options be ! ObjectCreate(%ObjectPrototype%).
  5. For each row of Table 1, except the header row, in table order, do
    1. Let p be the Property value of the current row.
    2. Let v be the value of lf's internal slot whose name is the Internal Slot value of the current row.
    3. Assert: v is not undefined.
    4. Perform ! CreateDataPropertyOrThrow(options, p, v).
  6. Return options.
Table 1: Resolved Options of ListFormat Instances
Internal Slot Property
[[Locale]] "locale"
[[Type]] "type"
[[Style]] "style"

1.5 Properties of Intl.ListFormat Instances

Intl.ListFormat instances inherit properties from %ListFormatPrototype%.

Intl.ListFormat instances have an [[InitializedListFormat]] internal slot.

Intl.ListFormat instances 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 list format styles.
  • [[Type]] is one of the String values "conjunction", "disjunction", or "unit", identifying the list of types used.
  • [[Style]] is one of the String values "long", "short", or "narrow", identifying the list formatting style used.
  • [[TemplatePair]] is a template for lists of size two. It is expected to be a valid template pattern, as described below.
  • [[TemplateStart]] is a template for lists of size greater than two, to be used at the start of the output. It is expected to be a valid template pattern, as described below.
  • [[TemplateMiddle]] is a template for lists of size greater than two, to be used in the middle of the output. It is expected to be a valid template pattern, as described below.
  • [[TemplateEnd]] is a template for lists of size greater than two, to be used at the end of the output. It is expected to be a valid template pattern, as described below.

The four internal slots [[TemplatePair]], [[TemplateStart]], [[TemplateMiddle]], and [[TemplateEnd]] are all expected to be valid template patterns. They should each contain one instance of the substring "{0}" and once instance of the substring "{1}", and the substring "{0}" should occur before the substring "{1}".

A Copyright & Software License

Copyright Notice

© 2020 Mozilla, Ecma International

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.