locale-sensitive-functions.html

<emu-clause id="locale-sensitive-functions">
  <h1>Locale Sensitive Functions of the ECMAScript Language Specification</h1>

  <p>
    The ECMAScript Language Specification, edition 10 or successor, describes several locale-sensitive functions. An ECMAScript implementation that implements this specification shall implement these functions as described here.
  </p>

  <emu-note>
    The Collator, NumberFormat, or DateTimeFormat objects created in the algorithms in this clause are only used within these algorithms. They are never directly accessed by ECMAScript code and need not actually exist within an implementation.
  </emu-note>

  <emu-clause id="sup-properties-of-the-string-prototype-object">
    <h1>Properties of the String Prototype Object</h1>

    <emu-clause id="sup-String.prototype.localeCompare">
      <h1>String.prototype.localeCompare ( _that_ [ , _locales_ [ , _options_ ] ] )</h1>

      <p>
        This definition supersedes the definition provided in es2024, <emu-xref href="#sec-string.prototype.localecompare"></emu-xref>.
      </p>

      <p>
        When the `localeCompare` method is called with argument _that_ and optional arguments _locales_, and _options_, the following steps are taken:
      </p>

      <emu-alg>
        1. Let _O_ be ? RequireObjectCoercible(*this* value).
        1. Let _S_ be ? ToString(_O_).
        1. Let _thatValue_ be ? ToString(_that_).
        1. Let _collator_ be ? Construct(%Intl.Collator%, &laquo; _locales_, _options_ &raquo;).
        1. Return CompareStrings(_collator_, _S_, _thatValue_).
      </emu-alg>

      <emu-note>
        The `localeCompare` method itself is not directly suitable as an argument to `Array.prototype.sort` because the latter requires a function of two arguments.
      </emu-note>

      <emu-note>
        The `localeCompare` function is intentionally generic; it does not require that its *this* value be a String object. Therefore, it can be transferred to other kinds of objects for use as a method.
      </emu-note>
    </emu-clause>

    <emu-clause id="sup-string.prototype.tolocalelowercase">
      <h1>String.prototype.toLocaleLowerCase ( [ _locales_ ] )</h1>

      <p>
        This definition supersedes the definition provided in es2024, <emu-xref href="#sec-string.prototype.tolocalelowercase"></emu-xref>.
      </p>

      <p>
        This function interprets a String value as a sequence of code points, as described in es2024, <emu-xref href="#sec-ecmascript-language-types-string-type"></emu-xref>. The following steps are taken:
      </p>

      <emu-alg>
        1. Let _O_ be ? RequireObjectCoercible(*this* value).
        1. Let _S_ be ? ToString(_O_).
        1. Return ? TransformCase(_S_, _locales_, ~lower~).
      </emu-alg>

      <emu-note>
        The `toLocaleLowerCase` function is intentionally generic; it does not require that its *this* value be a String object. Therefore, it can be transferred to other kinds of objects for use as a method.
      </emu-note>

      <emu-clause id="sec-transform-case" type="abstract operation">
        <h1>
          TransformCase (
            _S_: a String,
            _locales_: an ECMAScript language value,
            _targetCase_: ~lower~ or ~upper~,
          )
        </h1>
        <dl class="header">
          <dt>description</dt>
          <dd>It interprets _S_ as a sequence of UTF-16 encoded code points, as described in es2024, <emu-xref href="#sec-ecmascript-language-types-string-type"></emu-xref>, and returns the result of implementation- and locale-dependent (ILD) transformation into _targetCase_ as a new String value.</dd>
        </dl>
        <emu-alg>
          1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
          1. If _requestedLocales_ is not an empty List, then
            1. Let _requestedLocale_ be _requestedLocales_[0].
          1. Else,
            1. Let _requestedLocale_ be DefaultLocale().
          1. Let _noExtensionsLocale_ be the String value that is _requestedLocale_ with any Unicode locale extension sequences removed.
          1. Let _availableLocales_ be an Available Locales List which includes the language tags for which the Unicode Character Database contains language-sensitive case mappings. If the implementation supports additional locale-sensitive case mappings, _availableLocales_ should also include their corresponding language tags.
          1. Let _match_ be LookupMatchingLocaleByPrefix(_availableLocales_, _noExtensionsLocale_).
          1. If _match_ is not *undefined*, let _locale_ be _match_.[[locale]]; else let _locale_ be *"und"*.
          1. Let _codePoints_ be StringToCodePoints(_S_).
          1. If _targetCase_ is ~lower~, then
            1. Let _newCodePoints_ be a List whose elements are the result of a lowercase transformation of _codePoints_ according to an implementation-derived algorithm using _locale_ or the Unicode Default Case Conversion algorithm.
          1. Else,
            1. Assert: _targetCase_ is ~upper~.
            1. Let _newCodePoints_ be a List whose elements are the result of an uppercase transformation of _codePoints_ according to an implementation-derived algorithm using _locale_ or the Unicode Default Case Conversion algorithm.
          1. Return CodePointsToString(_newCodePoints_).
        </emu-alg>

        <p>
          Code point mappings may be derived according to a tailored version of the Default Case Conversion Algorithms of the Unicode Standard. Implementations may use locale-sensitive tailoring defined in the file <a href="https://unicode.org/Public/UCD/latest/ucd/SpecialCasing.txt"><code>SpecialCasing.txt</code></a> of the Unicode Character Database and/or CLDR and/or any other custom tailoring. Regardless of tailoring, a conforming implementation's case transformation algorithm must always yield the same result given the same input code points, locale, and target case.
        </p>

        <emu-note>
          The case mapping of some code points may produce multiple code points, and therefore the result may not be the same length as the input. Because both `toLocaleUpperCase` and `toLocaleLowerCase` have context-sensitive behaviour, the functions are not symmetrical. In other words, `s.toLocaleUpperCase().toLocaleLowerCase()` is not necessarily equal to `s.toLocaleLowerCase()` and `s.toLocaleLowerCase().toLocaleUpperCase()` is not necessarily equal to `s.toLocaleUpperCase()`.
        </emu-note>
      </emu-clause>
    </emu-clause>

    <emu-clause id="sup-string.prototype.tolocaleuppercase">
      <h1>String.prototype.toLocaleUpperCase ( [ _locales_ ] )</h1>

      <p>
        This definition supersedes the definition provided in es2024, <emu-xref href="#sec-string.prototype.tolocaleuppercase"></emu-xref>.
      </p>

      <p>
        This function interprets a String value as a sequence of code points, as described in es2024, <emu-xref href="#sec-ecmascript-language-types-string-type"></emu-xref>. The following steps are taken:
      </p>

      <emu-alg>
        1. Let _O_ be ? RequireObjectCoercible(*this* value).
        1. Let _S_ be ? ToString(_O_).
        1. Return ? TransformCase(_S_, _locales_, ~upper~).
      </emu-alg>

      <emu-note>
        The `toLocaleUpperCase` function is intentionally generic; it does not require that its *this* value be a String object. Therefore, it can be transferred to other kinds of objects for use as a method.
      </emu-note>
    </emu-clause>
  </emu-clause>

  <emu-clause id="sup-properties-of-the-number-prototype-object">
    <h1>Properties of the Number Prototype Object</h1>

    <p>
      The following definition(s) refer to the abstract operation thisNumberValue as defined in es2024, <emu-xref href="#sec-properties-of-the-number-prototype-object"></emu-xref>.
    </p>

    <emu-clause id="sup-number.prototype.tolocalestring">
      <h1>Number.prototype.toLocaleString ( [ _locales_ [ , _options_ ] ] )</h1>

      <p>
        This definition supersedes the definition provided in es2024, <emu-xref href="#sec-number.prototype.tolocalestring"></emu-xref>.
      </p>

      <p>
        When the `toLocaleString` method is called with optional arguments _locales_ and _options_, the following steps are taken:
      </p>

      <emu-alg>
        1. Let _x_ be ? ThisNumberValue(*this* value).
        1. Let _numberFormat_ be ? Construct(%Intl.NumberFormat%, &laquo; _locales_, _options_ &raquo;).
        1. Return FormatNumeric(_numberFormat_, ! ToIntlMathematicalValue(_x_)).
      </emu-alg>
    </emu-clause>
  </emu-clause>

  <emu-clause id="sup-properties-of-the-bigint-prototype-object">
    <h1>Properties of the BigInt Prototype Object</h1>

    <p>
      The following definition(s) refer to the abstract operation thisBigIntValue as defined in es2024, <emu-xref href="#sec-properties-of-the-bigint-prototype-object"></emu-xref>.
    </p>

    <emu-clause id="sup-bigint.prototype.tolocalestring">
      <h1>BigInt.prototype.toLocaleString ( [ _locales_ [ , _options_ ] ] )</h1>

      <p>
        This definition supersedes the definition provided in es2024, <emu-xref href="#sec-bigint.prototype.tolocalestring"></emu-xref>.
      </p>

      <p>
        When the `toLocaleString` method is called with optional arguments _locales_ and _options_, the following steps are taken:
      </p>

      <emu-alg>
        1. Let _x_ be ? ThisBigIntValue(*this* value).
        1. Let _numberFormat_ be ? Construct(%Intl.NumberFormat%, &laquo; _locales_, _options_ &raquo;).
        1. Return FormatNumeric(_numberFormat_, ℝ(_x_)).
      </emu-alg>
    </emu-clause>
  </emu-clause>

  <emu-clause id="sup-properties-of-the-date-prototype-object">
    <h1>Properties of the Date Prototype Object</h1>

    <p>
      The following definition(s) refer to the abstract operation thisTimeValue as defined in es2024, <emu-xref href="#sec-properties-of-the-date-prototype-object"></emu-xref>.
    </p>

    <emu-clause id="sup-date.prototype.tolocalestring">
      <h1>Date.prototype.toLocaleString ( [ _locales_ [ , _options_ ] ] )</h1>

      <p>
        This definition supersedes the definition provided in es2024, <emu-xref href="#sec-date.prototype.tolocalestring"></emu-xref>.
      </p>

      <p>
        When the `toLocaleString` method is called with optional arguments _locales_ and _options_, the following steps are taken:
      </p>

      <emu-alg>
        1. Let _dateObject_ be the *this* value.
        1. Perform ? RequireInternalSlot(_dateObject_, [[DateValue]]).
        1. Let _x_ be _dateObject_.[[DateValue]].
        1. If _x_ is *NaN*, return *"Invalid Date"*.
        1. Let _dateFormat_ be ? CreateDateTimeFormat(%Intl.DateTimeFormat%, _locales_, _options_, ~any~, ~all~).
        1. Return ! FormatDateTime(_dateFormat_, _x_).
      </emu-alg>
    </emu-clause>

    <emu-clause id="sup-date.prototype.tolocaledatestring">
      <h1>Date.prototype.toLocaleDateString ( [ _locales_ [ , _options_ ] ] )</h1>

      <p>
        This definition supersedes the definition provided in es2024, <emu-xref href="#sec-date.prototype.tolocaledatestring"></emu-xref>.
      </p>

      <p>
        When the `toLocaleDateString` method is called with optional arguments _locales_ and _options_, the following steps are taken:
      </p>

      <emu-alg>
        1. Let _dateObject_ be the *this* value.
        1. Perform ? RequireInternalSlot(_dateObject_, [[DateValue]]).
        1. Let _x_ be _dateObject_.[[DateValue]].
        1. If _x_ is *NaN*, return *"Invalid Date"*.
        1. Let _dateFormat_ be ? CreateDateTimeFormat(%Intl.DateTimeFormat%, _locales_, _options_, ~date~, ~date~).
        1. Return ! FormatDateTime(_dateFormat_, _x_).
      </emu-alg>
    </emu-clause>

    <emu-clause id="sup-date.prototype.tolocaletimestring">
      <h1>Date.prototype.toLocaleTimeString ( [ _locales_ [ , _options_ ] ] )</h1>

      <p>
        This definition supersedes the definition provided in es2024, <emu-xref href="#sec-date.prototype.tolocaletimestring"></emu-xref>.
      </p>

      <p>
        When the `toLocaleTimeString` method is called with optional arguments _locales_ and _options_, the following steps are taken:
      </p>

      <emu-alg>
        1. Let _dateObject_ be the *this* value.
        1. Perform ? RequireInternalSlot(_dateObject_, [[DateValue]]).
        1. Let _x_ be _dateObject_.[[DateValue]].
        1. If _x_ is *NaN*, return *"Invalid Date"*.
        1. Let _timeFormat_ be ? CreateDateTimeFormat(%Intl.DateTimeFormat%, _locales_, _options_, ~time~, ~time~).
        1. Return ! FormatDateTime(_timeFormat_, _x_).
      </emu-alg>
    </emu-clause>
  </emu-clause>

  <emu-clause id="sup-properties-of-the-array-prototype-object">
    <h1>Properties of the Array Prototype Object</h1>

    <emu-clause id="sup-array.prototype.tolocalestring">
      <h1>Array.prototype.toLocaleString ( [ _locales_ [ , _options_ ] ] )</h1>

      <p>
        This definition supersedes the definition provided in es2024, <emu-xref href="#sec-array.prototype.tolocalestring"></emu-xref>.
      </p>

      <p>
        When the `toLocaleString` method is called with optional arguments _locales_ and _options_, the following steps are taken:
      </p>

      <emu-alg>
        1. Let _array_ be ? ToObject(*this* value).
        1. Let _len_ be ? LengthOfArrayLike(_array_).
        1. Let _separator_ be the implementation-defined list-separator String value appropriate for the host environment's current locale (such as *", "*).
        1. Let _R_ be the empty String.
        1. Let _k_ be 0.
        1. Repeat, while _k_ &lt; _len_,
          1. If _k_ &gt; 0, then
            1. Set _R_ to the string-concatenation of _R_ and _separator_.
          1. Let _nextElement_ be ? Get(_array_, ! ToString(𝔽(_k_))).
          1. If _nextElement_ is not *undefined* or *null*, then
            1. Let _S_ be ? ToString(? Invoke(_nextElement_, *"toLocaleString"*, &laquo; _locales_, _options_ &raquo;)).
            1. Set _R_ to the string-concatenation of _R_ and _S_.
          1. Set _k_ to _k_ + 1.
        1. Return _R_.
      </emu-alg>

      <emu-note>
        This algorithm's steps mirror the steps taken in es2024, <emu-xref href="#sec-array.prototype.tolocalestring"></emu-xref>, with the exception that Invoke(_nextElement_, *"toLocaleString"*) now takes _locales_ and _options_ as arguments.
      </emu-note>

      <emu-note>
        The elements of the array are converted to Strings using their `toLocaleString` methods, and these Strings are then concatenated, separated by occurrences of an implementation-defined locale-sensitive separator String. This function is analogous to `toString` except that it is intended to yield a locale-sensitive result corresponding with conventions of the host environment's current locale.
      </emu-note>

      <emu-note>
        The `toLocaleString` function is intentionally generic; it does not require that its *this* value be an Array object. Therefore it can be transferred to other kinds of objects for use as a method.
      </emu-note>
    </emu-clause>
  </emu-clause>
</emu-clause>