datetimeformat.html

<emu-clause id="datetimeformat-objects">
  <h1>DateTimeFormat Objects</h1>

  <emu-clause id="sec-datetimeformat-abstracts">
    <h1>Abstract Operations For DateTimeFormat Objects</h1>

    <p>
      Several DateTimeFormat algorithms use values from the following table, which provides internal slots, property names and allowable values for the components of date and time formats:
    </p>

    <emu-table id="table-datetimeformat-components">
      <emu-caption>Components of date and time formats</emu-caption>
      <table class="real-table">
        <thead>
          <tr>
            <th>Internal Slot</th>
            <th>Property</th>
            <th>Values</th>
          </tr>
        </thead>
        <tr>
          <td>[[Weekday]]</td>
          <td>`"weekday"`</td>
          <td>`"narrow"`, `"short"`, `"long"`</td>
        </tr>
        <tr>
          <td>[[Era]]</td>
          <td>`"era"`</td>
          <td>`"narrow"`, `"short"`, `"long"`</td>
        </tr>
        <tr>
          <td>[[Year]]</td>
          <td>`"year"`</td>
          <td>`"2-digit"`, `"numeric"`</td>
        </tr>
        <tr>
          <td>[[Month]]</td>
          <td>`"month"`</td>
          <td>`"2-digit"`, `"numeric"`, `"narrow"`, `"short"`, `"long"`</td>
        </tr>
        <tr>
          <td>[[Day]]</td>
          <td>`"day"`</td>
          <td>`"2-digit"`, `"numeric"`</td>
        </tr>
        <tr>
          <td>[[Hour]]</td>
          <td>`"hour"`</td>
          <td>`"2-digit"`, `"numeric"`</td>
        </tr>
        <tr>
          <td>[[Minute]]</td>
          <td>`"minute"`</td>
          <td>`"2-digit"`, `"numeric"`</td>
        </tr>
        <tr>
          <td>[[Second]]</td>
          <td>`"second"`</td>
          <td>`"2-digit"`, `"numeric"`</td>
        </tr>
        <tr>
          <td>[[TimeZoneName]]</td>
          <td>`"timeZoneName"`</td>
          <td>`"short"`, `"long"`</td>
        </tr>
      </table>
    </emu-table>

    <emu-clause id="sec-initializedatetimeformat" aoid="InitializeDateTimeFormat">
      <h1>InitializeDateTimeFormat ( _dateTimeFormat_, _locales_, _options_ )</h1>

      <p>
        The abstract operation InitializeDateTimeFormat accepts the arguments _dateTimeFormat_ (which must be an object), _locales_, and _options_. It initializes _dateTimeFormat_ as a DateTimeFormat object. This abstract operation functions as follows:
      </p>

      <emu-alg>
        1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
        1. Let _options_ be ? ToDateTimeOptions(_options_, `"any"`, `"date"`).
        1. Let _opt_ be a new Record.
        1. Let _matcher_ be ? GetOption(_options_, `"localeMatcher"`, `"string"`, &laquo; `"lookup"`, `"best fit"` &raquo;, `"best fit"`).
        1. Set _opt_.[[localeMatcher]] to _matcher_.
        1. Let _hour12_ be ? GetOption(_options_, `"hour12"`, `"boolean"`, *undefined*, *undefined*).
        1. Let _hourCycle_ be ? GetOption(_options_, `"hourCycle"`, `"string"`, &laquo; `"h11"`, `"h12"`, `"h23"`, `"h24"` &raquo;, *undefined*).
        1. If _hour12_ is not *undefined*, then
          1. Let _hourCycle_ be *null*.
        1. Set _opt_.[[hc]] to _hourCycle_.
        1. Let _localeData_ be %DateTimeFormat%.[[LocaleData]].
        1. Let _r_ be ResolveLocale( %DateTimeFormat%.[[AvailableLocales]], _requestedLocales_, _opt_, %DateTimeFormat%.[[RelevantExtensionKeys]], _localeData_).
        1. Set _dateTimeFormat_.[[Locale]] to _r_.[[locale]].
        1. Set _dateTimeFormat_.[[Calendar]] to _r_.[[ca]].
        1. Set _dateTimeFormat_.[[HourCycle]] to _r_.[[hc]].
        1. Set _dateTimeFormat_.[[NumberingSystem]] to _r_.[[nu]].
        1. Let _dataLocale_ be _r_.[[dataLocale]].
        1. Let _timeZone_ be ? Get(_options_, `"timeZone"`).
        1. If _timeZone_ is not *undefined*, then
          1. Let _timeZone_ be ? ToString(_timeZone_).
          1. If the result of IsValidTimeZoneName(_timeZone_) is *false*, then
            1. Throw a *RangeError* exception.
          1. Let _timeZone_ be CanonicalizeTimeZoneName(_timeZone_).
        1. Else,
          1. Let _timeZone_ be DefaultTimeZone().
        1. Set _dateTimeFormat_.[[TimeZone]] to _timeZone_.
        1. Let _opt_ be a new Record.
        1. For each row of <emu-xref href="#table-datetimeformat-components"></emu-xref>, except the header row, in table order, do
          1. Let _prop_ be the name given in the Property column of the row.
          1. Let _value_ be ? GetOption(_options_, _prop_, `"string"`, &laquo; the strings given in the Values column of the row &raquo;, *undefined*).
          1. Set _opt_.[[&lt;_prop_&gt;]] to _value_.
        1. Let _dataLocaleData_ be _localeData_.[[&lt;_dataLocale_&gt;]].
        1. Let _formats_ be _dataLocaleData_.[[formats]].
        1. Let _matcher_ be ? GetOption(_options_, `"formatMatcher"`, `"string"`, &laquo; `"basic"`, `"best fit"` &raquo;, `"best fit"`).
        1. If _matcher_ is `"basic"`, then
          1. Let _bestFormat_ be BasicFormatMatcher(_opt_, _formats_).
        1. Else,
          1. Let _bestFormat_ be BestFitFormatMatcher(_opt_, _formats_).
        1. For each row in <emu-xref href="#table-datetimeformat-components"></emu-xref>, except the header row, in table order, do
          1. Let _prop_ be the name given in the Property column of the row.
          1. Let _p_ be _bestFormat_.[[&lt;_prop_&gt;]].
          1. If _p_ not *undefined*, then
            1. Set _dateTimeFormat_'s internal slot whose name is the Internal Slot column of the row to _p_.
        1. If _dateTimeFormat_.[[Hour]] is not *undefined*, then
          1. Let _hcDefault_ be _dataLocaleData_.[[HourCycle]].
          1. Let _hc_ be _dateTimeFormat_.[[HourCycle]].
          1. If _hc_ is *null*, then
            1. Set _hc_ to _hcDefault_.
          1. If _hour12_ is not *undefined*, then
            1. If _hour12_ is *true*, then
              1. If _hcDefault_ is `"h11"` or `"h23"`, then
                1. Set _hc_ to `"h11"`.
              1. Else,
                1. Set _hc_ to `"h12"`.
            1. Else,
              1. Assert: _hour12_ is *false*.
              1. If _hcDefault_ is `"h11"` or `"h23"`, then
                1. Set _hc_ to `"h23"`.
              1. Else,
                1. Set _hc_ to `"h24"`.
          1. Set _dateTimeFormat_.[[HourCycle]] to _hc_.
          1. If _dateTimeformat_.[[HourCycle]] is `"h11"` or `"h12"`, then
            1. Let _pattern_ be _bestFormat_.[[pattern12]].
          1. Else,
            1. Let _pattern_ be _bestFormat_.[[pattern]].
        1. Else,
          1. Set _dateTimeFormat_.[[HourCycle]] to *undefined*.
          1. Let _pattern_ be _bestFormat_.[[pattern]].
        1. Set _dateTimeFormat_.[[Pattern]] to _pattern_.
        1. Return _dateTimeFormat_.
      </emu-alg>
    </emu-clause>

    <emu-clause id="sec-todatetimeoptions" aoid="ToDateTimeOptions">
      <h1>ToDateTimeOptions ( _options_, _required_, _defaults_ )</h1>

      <p>
        When the ToDateTimeOptions abstract operation is called with arguments _options_, _required_, and _defaults_, the following steps are taken:
      </p>

      <emu-alg>
        1. If _options_ is *undefined*, let _options_ be *null*; otherwise let _options_ be ? ToObject(_options_).
        1. Let _options_ be ObjectCreate(_options_).
        1. Let _needDefaults_ be *true*.
        1. If _required_ is `"date"` or `"any"`, then
          1. For each of the property names `"weekday"`, `"year"`, `"month"`, `"day"`, do
            1. Let _prop_ be the property name.
            1. Let _value_ be ? Get(_options_, _prop_).
            1. If _value_ is not *undefined*, let _needDefaults_ be *false*.
        1. If _required_ is `"time"` or `"any"`, then
          1. For each of the property names `"hour"`, `"minute"`, `"second"`, do
            1. Let _prop_ be the property name.
            1. Let _value_ be ? Get(_options_, _prop_).
            1. If _value_ is not *undefined*, let _needDefaults_ be *false*.
        1. If _needDefaults_ is *true* and _defaults_ is either `"date"` or `"all"`, then
          1. For each of the property names `"year"`, `"month"`, `"day"`, do
            1. Perform ? CreateDataPropertyOrThrow(_options_, _prop_, `"numeric"`).
        1. If _needDefaults_ is *true* and _defaults_ is either `"time"` or `"all"`, then
          1. For each of the property names `"hour"`, `"minute"`, `"second"`, do
            1. Perform ? CreateDataPropertyOrThrow(_options_, _prop_, `"numeric"`).
        1. Return _options_.
      </emu-alg>
    </emu-clause>

    <emu-clause id="sec-basicformatmatcher" aoid="BasicFormatMatcher">
      <h1>BasicFormatMatcher ( _options_, _formats_ )</h1>

      <p>
        When the BasicFormatMatcher abstract operation is called with two arguments _options_ and _formats_, the following steps are taken:
      </p>

      <emu-alg>
        1. Let _removalPenalty_ be 120.
        1. Let _additionPenalty_ be 20.
        1. Let _longLessPenalty_ be 8.
        1. Let _longMorePenalty_ be 6.
        1. Let _shortLessPenalty_ be 6.
        1. Let _shortMorePenalty_ be 3.
        1. Let _bestScore_ be -*Infinity*.
        1. Let _bestFormat_ be *undefined*.
        1. Assert: Type(_formats_) is List.
        1. For each element _format_ of _formats_ in List order, do
          1. Let _score_ be 0.
          1. For each _property_ shown in <emu-xref href="#table-datetimeformat-components"></emu-xref>, do
            1. Let _optionsProp_ be _options_.[[&lt;_property_&gt;]].
            1. Let _formatProp_ be _format_.[[&lt;_property_&gt;]].
            1. If _optionsProp_ is *undefined* and _formatProp_ is not *undefined*, then decrease _score_ by _additionPenalty_.
            1. Else if _optionsProp_ is not *undefined* and _formatProp_ is *undefined*, then decrease _score_ by _removalPenalty_.
            1. Else if _optionsProp_ ≠ _formatProp_,
              1. Let _values_ be &laquo; `"2-digit"`, `"numeric"`, `"narrow"`, `"short"`, `"long"` &raquo;.
              1. Let _optionsPropIndex_ be the index of _optionsProp_ within _values_.
              1. Let _formatPropIndex_ be the index of _formatProp_ within _values_.
              1. Let _delta_ be max(min(_formatPropIndex_ - _optionsPropIndex_, 2), -2).
              1. If _delta_ = 2, decrease _score_ by _longMorePenalty_.
              1. Else if _delta_ = 1, decrease _score_ by _shortMorePenalty_.
              1. Else if _delta_ = -1, decrease _score_ by _shortLessPenalty_.
              1. Else if _delta_ = -2, decrease _score_ by _longLessPenalty_.
          1. If _score_ > _bestScore_, then
            1. Let _bestScore_ be _score_.
            1. Let _bestFormat_ be _format_.
        1. Return _bestFormat_.
      </emu-alg>
    </emu-clause>

    <emu-clause id="sec-bestfitformatmatcher" aoid="BestFitFormatMatcher">
      <h1>BestFitFormatMatcher ( _options_, _formats_ )</h1>

      <p>
        When the BestFitFormatMatcher abstract operation is called with two arguments _options_ and _formats_, it performs implementation dependent steps, which should return a set of component representations that a typical user of the selected locale would perceive as at least as good as the one returned by BasicFormatMatcher.
      </p>
    </emu-clause>

    <emu-clause id="sec-datetime-format-functions">
      <h1>DateTime Format Functions</h1>

      <p>A DateTime format function is an anonymous built-in function that has a [[DateTimeFormat]] internal slot.</p>
      <p>When a DateTime format function _F_ is called with optional argument _date_, the following steps are taken:</p>

      <emu-alg>
        1. Let _dtf_ be _F_.[[DateTimeFormat]].
        1. Assert: Type(_dtf_) is Object and _dtf_ has an [[InitializedDateTimeFormat]] internal slot.
        1. If _date_ is not provided or is *undefined*, then
          1. Let _x_ be Call(%Date_now%, *undefined*).
        1. Else,
          1. Let _x_ be ? ToNumber(_date_).
        1. Return FormatDateTime(_dtf_, _x_).
      </emu-alg>

      <p>
        The `length` property of a DateTime format function is 1.
      </p>
    </emu-clause>

    <emu-clause id="sec-partitiondatetimepattern" aoid="PartitionDateTimePattern">
      <h1>PartitionDateTimePattern ( _dateTimeFormat_, _x_ )</h1>

      <p>
        The PartitionDateTimePattern abstract operation is called with arguments _dateTimeFormat_ (which must be an object initialized as a DateTimeFormat) and _x_ (which must be a Number value), interprets _x_ as a time value as specified in ES2015, <emu-xref href="#sec-time-values-and-time-range"></emu-xref>, and creates the corresponding parts according to the effective locale and the formatting options of _dateTimeFormat_. The following steps are taken:
      </p>

      <emu-alg>
        1. Let _x_ be TimeClip(_x_).
        1. If _x_ is *NaN*, throw a *RangeError* exception.
        1. Let _locale_ be _dateTimeFormat_.[[Locale]].
        1. Let _nfOptions_ be ObjectCreate(*null*).
        1. Perform ! CreateDataPropertyOrThrow(_nfOptions_, `"useGrouping"`, *false*).
        1. Let _nf_ be ? Construct(%NumberFormat%, &laquo; _locale_, _nfOptions_ &raquo;).
        1. Let _nf2Options_ be ObjectCreate(*null*).
        1. Perform ! CreateDataPropertyOrThrow(_nf2Options_, `"minimumIntegerDigits"`, 2).
        1. Perform ! CreateDataPropertyOrThrow(_nf2Options_, `"useGrouping"`, *false*).
        1. Let _nf2_ be ? Construct(%NumberFormat%, &laquo; _locale_, _nf2Options_ &raquo;).
        1. Let _tm_ be ToLocalTime(_x_, _dateTimeFormat_.[[Calendar]], _dateTimeFormat_.[[TimeZone]]).
        1. Let _pattern_ be _dateTimeFormat_.[[Pattern]].
        1. Let _result_ be a new empty List.
        1. Let _beginIndex_ be Call(%StringProto_indexOf%, _pattern_, &laquo; `"{"`, 0 &raquo;).
        1. Let _endIndex_ be 0.
        1. Let _nextIndex_ be 0.
        1. Let _length_ be the number of code units in _pattern_.
        1. Repeat, while _beginIndex_ is an integer index into _pattern_
          1. Set _endIndex_ to Call(%StringProto_indexOf%, _pattern_, &laquo; `"}"`, _beginIndex_ &raquo;).
          1. Assert: _endIndex_ is greater than _beginIndex_.
          1. If _beginIndex_ is greater than _nextIndex_, then
            1. Let _literal_ be a substring of _pattern_ from position _nextIndex_, inclusive, to position _beginIndex_, exclusive.
            1. Add new part record { [[Type]]: `"literal"`, [[Value]]: _literal_ } as a new element of the list _result_.
          1. Let _p_ be the substring of _pattern_ from position _beginIndex_, exclusive, to position _endIndex_, exclusive.
          1. If _p_ matches a Property column of the row in <emu-xref href="#table-datetimeformat-components"></emu-xref>, then
            1. Let _f_ be the value of _dateTimeFormat_'s internal slot whose name is the Internal Slot column of the matching row.
            1. Let _v_ be the value of _tm_'s field whose name is the Internal Slot column of the matching row.
            1. If _p_ is `"year"` and _v_ ≤ 0, let _v_ be 1 - _v_.
            1. If _p_ is `"month"`, increase _v_ by 1.
            1. If _p_ is `"hour"` and _dateTimeFormat_.[[HourCycle]] is `"h11"` or `"h12"`, then
              1. Let _v_ be _v_ modulo 12.
              1. If _v_ is 0 and _dateTimeFormat_.[[HourCycle]] is `"h12"`, let _v_ be 12.
            1. If _p_ is `"hour"` and _dateTimeFormat_.[[HourCycle]] is `"h24"`, then
              1. If _v_ is 0, let _v_ be 24.
            1. If _f_ is `"numeric"`, then
              1. Let _fv_ be FormatNumber(_nf_, _v_).
            1. Else if _f_ is `"2-digit"`, then
              1. Let _fv_ be FormatNumber(_nf2_, _v_).
              1. If the `length` property of _fv_ is greater than 2, let _fv_ be the substring of _fv_ containing the last two characters.
            1. Else if _f_ is `"narrow"`, `"short"`, or `"long"`, then let _fv_ be a String value representing _f_ in the desired form; the String value depends upon the implementation and the effective locale and calendar of _dateTimeFormat_. If _p_ is `"month"`, then the String value may also depend on whether _dateTimeFormat_ has a [[Day]] internal slot. If _p_ is `"timeZoneName"`, then the String value may also depend on the value of the [[inDST]] field of _tm_. If _p_ is `"era"`, then the String value may also depend on whether _dateTimeFormat_ has a [[Era]] internal slot and if the implementation does not have a localized representation of _f_, then use _f_ itself.
            1. Add new part record { [[Type]]: _p_, [[Value]]: _fv_ } as a new element of the list _result_.
          1. Else if _p_ is equal to `"ampm"`, then
            1. Let _v_ be _tm_.[[hour]].
            1. If _v_ is greater than 11, then
              1. Let _fv_ be an implementation and locale dependent String value representing `"post meridiem"`.
            1. Else,
              1. Let _fv_ be an implementation and locale dependent String value representing `"ante meridiem"`.
            1. Add new part record { [[Type]]: `"dayPeriod"`, [[Value]]: _fv_ } as a new element of the list _result_.
          1. Else,
            1. Let _unknown_ be an implementation-, locale-, and numbering system-dependent String based on _x_ and _p_.
            1. Append a new Record { [[Type]]: `"unknown"`, [[Value]]: _unknown_ } as the last element of _result_.
          1. Set _nextIndex_ to _endIndex_ + 1.
          1. Set _beginIndex_ to Call(%StringProto_indexOf%, _pattern_, &laquo; `"{"`, _nextIndex_ &raquo;).
        1. If _nextIndex_ is less than _length_, then
          1. Let _literal_ be the substring of _pattern_ from position _nextIndex_, exclusive, to position _length_, exclusive.
          1. Add new part record { [[Type]]: `"literal"`, [[Value]]: _literal_ } as a new element of the list _result_.
        1. Return _result_.
      </emu-alg>

      <emu-note>
        It is recommended that implementations use the locale and calendar dependent strings provided by the Common Locale Data Repository (available at <a href="http://cldr.unicode.org">http://cldr.unicode.org</a>), and use CLDR `"abbreviated"` strings for DateTimeFormat `"short"` strings, and CLDR `"wide"` strings for DateTimeFormat `"long"` strings.
      </emu-note>

      <emu-note>
        It is recommended that implementations use the time zone information of the IANA Time Zone Database.
      </emu-note>

    </emu-clause>

    <emu-clause id="sec-formatdatetime" aoid="FormatDateTime">
      <h1>FormatDateTime( _dateTimeFormat_, _x_ )</h1>

      <p>
        The FormatDateTime abstract operation is called with arguments _dateTimeFormat_ (which must be an object initialized as a DateTimeFormat) and _x_ (which must be a Number value), and performs the following steps:
      </p>

      <emu-alg>
        1. Let _parts_ be ? PartitionDateTimePattern(_dateTimeFormat_, _x_).
        1. Let _result_ be the empty String.
        1. For each _part_ in _parts_, do
          1. Set _result_ to a String value produced by concatenating _result_ and _part_.[[Value]].
        1. Return _result_.
      </emu-alg>

    </emu-clause>

    <emu-clause id="sec-formatdatetimetoparts" aoid="FormatDateTimeToParts">
      <h1>FormatDateTimeToParts ( _dateTimeFormat_, _x_ )</h1>

      <p>
        The FormatDateTimeToParts abstract operation is called with arguments _dateTimeFormat_ (which must be an object initialized as a DateTimeFormat) and _x_ (which must be a Number value), and performs the following steps:
      </p>

      <emu-alg>
        1. Let _parts_ be ? PartitionDateTimePattern(_dateTimeFormat_, _x_).
        1. Let _result_ be ArrayCreate(0).
        1. Let _n_ be 0.
        1. For each _part_ in _parts_, do
          1. Let _O_ be ObjectCreate(%ObjectPrototype%).
          1. Perform ! CreateDataPropertyOrThrow(_O_, `"type"`, _part_.[[Type]]).
          1. Perform ! CreateDataPropertyOrThrow(_O_, `"value"`, _part_.[[Value]]).
          1. Perform ! CreateDataProperty(_result_, ! ToString(_n_), _O_).
          1. Increment _n_ by 1.
        1. Return _result_.
      </emu-alg>

    </emu-clause>

    <emu-clause id="sec-tolocaltime" aoid="ToLocalTime">
      <h1>ToLocalTime ( _date_, _calendar_, _timeZone_ )</h1>

      <p>
        When the ToLocalTime abstract operation is called with arguments _date_, _calendar_, and _timeZone_, the following steps are taken:
      </p>

      <emu-alg>
        1. Apply calendrical calculations on _date_ for the given _calendar_ and _timeZone_ to produce weekday, era, year, month, day, hour, minute, second, and inDST values. The calculations should use best available information about the specified _calendar_ and _timeZone_, including current and historical information about time zone offsets from UTC and daylight saving time rules. If the _calendar_ is `"gregory"`, then the calculations must match the algorithms specified in ES2020, <emu-xref href="#sec-overview-of-date-objects-and-definitions-of-abstract-operations"></emu-xref>.
        1. Return a Record with fields [[weekday]], [[era]], [[year]], [[month]], [[day]], [[hour]], [[minute]], [[second]], and [[inDST]], each with the corresponding calculated value.
      </emu-alg>

      <emu-note>
        It is recommended that implementations use the time zone information of the IANA Time Zone Database.
      </emu-note>
    </emu-clause>

    <emu-clause id="sec-unwrapdatetimeformat" aoid="UnwrapDateTimeFormat">
      <h1>UnwrapDateTimeFormat( _dtf_ )</h1>
      <p>
        The UnwrapDateTimeFormat abstract operation gets the underlying DateTimeFormat operation
        for various methods which implement ECMA-402 v1 semantics for supporting initializing
        existing Intl objects.
      </p>
      <emu-alg>
        1. Assert: Type(_dtf_) is Object.
      </emu-alg>
      <emu-normative-optional>
      <emu-alg>
        2. If _dtf_ does not have an [[InitializedDateTimeFormat]] internal slot and ? InstanceofOperator(_dtf_, %DateTimeFormat%) is *true*, then
          1. Let _dtf_ be ? Get(_dtf_, %Intl%.[[FallbackSymbol]]).
      </emu-alg>
      </emu-normative-optional>
      <emu-alg>
        2. If Type(_dtf_) is not Object or _dtf_ does not have an [[InitializedDateTimeFormat]] internal slot, then
          1. Throw a *TypeError* exception.
        1. Return _dtf_.
      </emu-alg>
      <emu-note>See <emu-xref href="#legacy-constructor"></emu-xref> for the motivation of the normative optional text.</emu-note>
    </emu-clause>
  </emu-clause>

  <emu-clause id="sec-intl-datetimeformat-constructor">
    <h1>The Intl.DateTimeFormat Constructor</h1>

    <p>
      The Intl.DateTimeFormat constructor is the <dfn>%DateTimeFormat%</dfn> 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 <emu-xref href="#sec-internal-slots"></emu-xref>.
    </p>

    <emu-clause id="sec-intl.datetimeformat">
      <h1>Intl.DateTimeFormat ( [ _locales_ [ , _options_ ] ] )</h1>

      <p>
        When the `Intl.DateTimeFormat` function is called with optional arguments _locales_ and _options_, the following steps are taken:
      </p>

      <emu-alg>
        1. If NewTarget is *undefined*, let _newTarget_ be the active function object, else let _newTarget_ be NewTarget.
        1. Let _dateTimeFormat_ be ? OrdinaryCreateFromConstructor(_newTarget_, `"%DateTimeFormatPrototype%"`, &laquo; [[InitializedDateTimeFormat]], [[Locale]], [[Calendar]], [[NumberingSystem]], [[TimeZone]], [[Weekday]], [[Era]], [[Year]], [[Month]], [[Day]], [[Hour]], [[Minute]], [[Second]], [[TimeZoneName]], [[HourCycle]], [[Pattern]], [[BoundFormat]] &raquo;).
        1. Perform ? InitializeDateTimeFormat(_dateTimeFormat_, _locales_, _options_).
      </emu-alg>
      <emu-normative-optional>
      <emu-alg>
        4. Let _this_ be the *this* value.
        1. If NewTarget is *undefined* and ? InstanceofOperator(_this_, %DateTimeFormat%) is *true*, then
          1. Perform ? DefinePropertyOrThrow(_this_, %Intl%.[[FallbackSymbol]], PropertyDescriptor{ [[Value]]: _dateTimeFormat_, [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *false* }).
          1. Return _this_.
      </emu-alg>
      </emu-normative-optional>
      <emu-alg>
        6. Return _dateTimeFormat_.
      </emu-alg>
      <emu-note>See <emu-xref href="#legacy-constructor"></emu-xref> for the motivation of the normative optional text.</emu-note>
    </emu-clause>
  </emu-clause>

  <emu-clause id="sec-properties-of-intl-datetimeformat-constructor">
    <h1>Properties of the Intl.DateTimeFormat Constructor</h1>

    <p>
      The Intl.DateTimeFormat constructor has the following properties:
    </p>

    <emu-clause id="sec-intl.datetimeformat.prototype">
      <h1>Intl.DateTimeFormat.prototype</h1>

      <p>
        The value of `Intl.DateTimeFormat.prototype` is %DateTimeFormatPrototype%.
      </p>
      <p>
        This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *false* }.
      </p>
    </emu-clause>

    <emu-clause id="sec-intl.datetimeformat.supportedlocalesof">
      <h1>Intl.DateTimeFormat.supportedLocalesOf ( _locales_ [ , _options_ ] )</h1>

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

      <emu-alg>
        1. Let _availableLocales_ be %DateTimeFormat%.[[AvailableLocales]].
        1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
        1. Return ? SupportedLocales(_availableLocales_, _requestedLocales_, _options_).
      </emu-alg>

      <p>
        The value of the `length` property of the *supportedLocalesOf* method is 1.
      </p>
    </emu-clause>

    <emu-clause id="sec-intl.datetimeformat-internal-slots">
      <h1>Internal slots</h1>

      <p>
        The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in <emu-xref href="#sec-internal-slots"></emu-xref>.
      </p>

      <p>
        The value of the [[RelevantExtensionKeys]] internal slot is &laquo; `"ca"`, `"nu"`, `"hc"` &raquo;.
      </p>

      <emu-note>
        Unicode Technical Standard 35 describes three locale extension keys that are relevant to date and time formatting, `"ca"` for calendar, `"tz"` for time zone, `"hc"` for hour cycle, and implicitly `"nu"` for the numbering system of the number format used for numbers within the date format. DateTimeFormat, however, requires that the time zone is specified through the timeZone property in the options objects.
      </emu-note>

      <p>
        The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in <emu-xref href="#sec-internal-slots"></emu-xref> and the following additional constraints:
      </p>

      <ul>
        <li>
          The list that is the value of the `"nu"` field of any locale field of [[LocaleData]] must not include the values `"native"`, `"traditio"`, or `"finance"`.
        </li>
        <li>
          [[LocaleData]][locale].hc must be &laquo; *null*, `"h11"`, `"h12"`, `"h23"`, `"h24"` &raquo; for all locale values.
        </li>
        <li>
          [[LocaleData]][locale] must have a HourCycle field with a String value equal to `"h11"`, `"h12"`, `"h23"`, or `"h24"` for all locale values.
        </li>
        <li>
          [[LocaleData]][locale] must have a formats field for all locale values. The value of this field must be a list of records, each of which has a subset of the fields shown in <emu-xref href="#table-datetimeformat-components"></emu-xref>, where each field must have one of the values specified for the field in <emu-xref href="#table-datetimeformat-components"></emu-xref>. Multiple records in a list may use the same subset of the fields as long as they have different values for the fields. The following subsets must be available for each locale:
          <ul>
            <li>weekday, year, month, day, hour, minute, second</li>
            <li>weekday, year, month, day</li>
            <li>year, month, day</li>
            <li>year, month</li>
            <li>month, day</li>
            <li>hour, minute, second</li>
            <li>hour, minute</li>
          </ul>
          Each of the records must also have a pattern field, whose value is a String value that contains for each of the date and time format component fields of the record a substring starting with `"{"`, followed by the name of the field, followed by `"}"`. If the record has an hour field, it must also have a pattern12 field, whose value is a String value that, in addition to the substrings of the pattern field, contains a substring `"{ampm}"`.
        </li>
      </ul>

      <p>
        EXAMPLE     An implementation might include the following record as part of its English locale data: {[[hour]]: `"numeric"`, [[minute]]: `"2-digit"`, [[second]]: `"2-digit"`, [[pattern]]: `"{hour}:{minute}:{second}"`, [[pattern12]]: `"{hour}:{minute}:{second} {ampm}"`}.
      </p>

      <emu-note>
        It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at <a href="http://cldr.unicode.org">http://cldr.unicode.org</a>).
      </emu-note>
    </emu-clause>
  </emu-clause>

  <emu-clause id="sec-properties-of-intl-datetimeformat-prototype-object">
    <h1>Properties of the Intl.DateTimeFormat Prototype Object</h1>

    <p>
      The Intl.DateTimeFormat prototype object is itself an ordinary object. <dfn>%DateTimeFormatPrototype%</dfn> is not an Intl.DateTimeFormat instance and does not have an [[InitializedDateTimeFormat]] internal slot or any of the other internal slots of Intl.DateTimeFormat instance objects.
    </p>

    <emu-clause id="sec-intl.datetimeformat.prototype.constructor">
      <h1>Intl.DateTimeFormat.prototype.constructor</h1>

      <p>
        The initial value of `Intl.DateTimeFormat.prototype.constructor` is the intrinsic object %DateTimeFormat%.
      </p>
    </emu-clause>

    <emu-clause id="sec-intl.datetimeformat.prototype-@@tostringtag">
      <h1>Intl.DateTimeFormat.prototype [ @@toStringTag ]</h1>

      <p>
        The initial value of the @@toStringTag property is the string value `"Object"`.
      </p>

      <p>
        This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.
      </p>
    </emu-clause>

    <emu-clause id="sec-intl.datetimeformat.prototype.format">
      <h1>get Intl.DateTimeFormat.prototype.format</h1>

      <p>
        Intl.DateTimeFormat.prototype.format is an accessor property whose set accessor function is *undefined*. Its get accessor function performs the following steps:
      </p>

      <emu-alg>
        1. Let _dtf_ be *this* value.
        1. If Type(_dtf_) is not Object, throw a *TypeError* exception.
        1. Let _dtf_ be ? UnwrapDateTimeFormat(_dtf_).
        1. If _dtf_.[[BoundFormat]] is *undefined*, then
          1. Let _F_ be a new built-in function object as defined in DateTime Format Functions (<emu-xref href="#sec-datetime-format-functions"></emu-xref>).
          1. Set _F_.[[DateTimeFormat]] to _dtf_.
          1. Set _dtf_.[[BoundFormat]] to _F_.
        1. Return _dtf_.[[BoundFormat]].
      </emu-alg>

      <emu-note>
        The returned function is bound to _dtf_ so that it can be passed directly to `Array.prototype.map` or other functions.
        This is considered a historical artefact, as part of a convention which is no longer followed for new features, but is preserved to maintain compatibility with existing programs.
      </emu-note>
    </emu-clause>

    <emu-clause id="sec-Intl.DateTimeFormat.prototype.formatToParts">
      <h1>Intl.DateTimeFormat.prototype.formatToParts ( _date_ )</h1>

      <p>
        When the `formatToParts` method is called with an argument _date_, the following steps are taken:
      </p>

      <emu-alg>
        1. Let _dtf_ be *this* value.
        1. If Type(_dtf_) is not Object, throw a *TypeError* exception.
        1. If _dtf_ does not have an [[InitializedDateTimeFormat]] internal slot, throw a *TypeError* exception.
        1. If _date_ is *undefined*, then
          1. Let _x_ be Call(%Date_now%, *undefined*).
        1. Else,
          1. Let _x_ be ? ToNumber(_date_).
        1. Return ? FormatDateTimeToParts(_dtf_, _x_).
      </emu-alg>
    </emu-clause>

    <emu-clause id="sec-intl.datetimeformat.prototype.resolvedoptions">
      <h1>Intl.DateTimeFormat.prototype.resolvedOptions ()</h1>

      <p>
        This function provides access to the locale and formatting options computed during initialization of the object.
      </p>

      <emu-alg>
        1. Let _dtf_ be *this* value.
        1. If Type(_dtf_) is not Object, throw a *TypeError* exception.
        1. Let _dtf_ be ? UnwrapDateTimeFormat(_dtf_).
        1. Let _options_ be ! ObjectCreate(%ObjectPrototype%).
        1. For each row of <emu-xref href="#table-datetimeformat-resolvedoptions-properties"></emu-xref>, except the header row, in table order, do
          1. Let _p_ be the Property value of the current row.
          1. If _p_ is `"hour12"`, then
            1. Let _hc_ be _dtf_.[[HourCycle]].
            1. If _hc_ is `"h11"` or `"h12"`, let _v_ be *true*.
            1. Else if, _hc_ is `"h23"` or `"h24"`, let _v_ be *false*.
            1. Else, let _v_ be *undefined*.
          1. Else,
            1. Let _v_ be the value of _dtf_'s internal slot whose name is the Internal Slot value of the current row.
          1. If _v_ is not *undefined*, then
            1. Perform ! CreateDataPropertyOrThrow(_options_, _p_, _v_).
        1. Return _options_.
      </emu-alg>

      <emu-table id="table-datetimeformat-resolvedoptions-properties">
        <emu-caption>Resolved Options of DateTimeFormat Instances</emu-caption>
        <table class="real-table">
          <thead>
            <tr>
              <th>Internal Slot</th>
              <th>Property</th>
            </tr>
          </thead>
          <tr>
            <td>[[Locale]]</td>
            <td>`"locale"`</td>
          </tr>
          <tr>
            <td>[[Calendar]]</td>
            <td>`"calendar"`</td>
          </tr>
          <tr>
            <td>[[NumberingSystem]]</td>
            <td>`"numberingSystem"`</td>
          </tr>
          <tr>
            <td>[[TimeZone]]</td>
            <td>`"timeZone"`</td>
          </tr>
          <tr>
            <td>[[HourCycle]]</td>
            <td>`"hourCycle"`</td>
          </tr>
          <tr>
            <td></td>
            <td>`"hour12"`</td>
          </tr>
          <tr>
            <td>[[Weekday]]</td>
            <td>`"weekday"`</td>
          </tr>
          <tr>
            <td>[[Era]]</td>
            <td>`"era"`</td>
          </tr>
          <tr>
            <td>[[Year]]</td>
            <td>`"year"`</td>
          </tr>
          <tr>
            <td>[[Month]]</td>
            <td>`"month"`</td>
          </tr>
          <tr>
            <td>[[Day]]</td>
            <td>`"day"`</td>
          </tr>
          <tr>
            <td>[[Hour]]</td>
            <td>`"hour"`</td>
          </tr>
          <tr>
            <td>[[Minute]]</td>
            <td>`"minute"`</td>
          </tr>
          <tr>
            <td>[[Second]]</td>
            <td>`"second"`</td>
          </tr>
          <tr>
            <td>[[TimeZoneName]]</td>
            <td>`"timeZoneName"`</td>
          </tr>
        </table>
      </emu-table>

      <p>
        For web compatibility reasons, if the property hourCycle is set, the hour12 property should be set to *true* when hourCycle is `"h11"` or `"h12"`, or to *false* when hourCycle is `"h23"` or `"h24"`.
      </p>

      <emu-note>
        In this version of the ECMAScript 2020 Internationalization API, the timeZone property will be the name of the default time zone if no timeZone property was provided in the options object provided to the Intl.DateTimeFormat constructor. The first edition left the timeZone property *undefined* in this case.
      </emu-note>

      <emu-note>
        For compatibility with versions prior to the fifth edition, the `"hour12"` property is set in addition to the `"hourCycle"` property.
      </emu-note>
    </emu-clause>
  </emu-clause>

  <emu-clause id="sec-properties-of-intl-datetimeformat-instances">
    <h1>Properties of Intl.DateTimeFormat Instances</h1>

    <p>
      Intl.DateTimeFormat instances inherit properties from %DateTimeFormatPrototype%.
    </p>

    <p>
      Intl.DateTimeFormat instances have an [[InitializedDateTimeFormat]] internal slot.
    </p>

    <p>
      Intl.DateTimeFormat instances also have several internal slots that are computed by the constructor:
    </p>

    <ul>
      <li>[[Locale]] is a String value with the language tag of the locale whose localization is used for formatting.</li>
      <li>[[Calendar]] is a String value with the `"type"` given in Unicode Technical Standard 35 for the calendar used for formatting.</li>
      <li>[[NumberingSystem]] is a String value with the `"type"` given in Unicode Technical Standard 35 for the numbering system used for formatting.</li>
      <li>[[TimeZone]] is a String value with the IANA time zone name of the time zone used for formatting.</li>
      <li>[[Weekday]], [[Era]], [[Year]], [[Month]], [[Day]], [[Hour]], [[Minute]], [[Second]], [[TimeZoneName]] are each either *undefined*, indicating that the component is not used for formatting, or one of the String values given in <emu-xref href="#table-datetimeformat-components"></emu-xref>, indicating how the component should be presented in the formatted output.</li>
      <li>[[HourCycle]] is a String value indicating whether the 12-hour format (`"h11"`, `"h12"`) or the 24-hour format (`"h23"`, `"h24"`) should be used. `"h11"` and `"h23"` start with hour 0 and go up to 11 and 23 respectively. `"h12"` and `"h24"` start with hour 1 and go up to 12 and 24. [[HourCycle]] is only used when [[Hour]] is not *undefined*.</li>
      <li>[[Pattern]] is a String value as described in <emu-xref href="#sec-intl.datetimeformat-internal-slots"></emu-xref>.</li>
    </ul>

    <p>
      Finally, Intl.DateTimeFormat instances have a [[BoundFormat]] internal slot that caches the function returned by the format accessor (<emu-xref href="#sec-intl.datetimeformat.prototype.format"></emu-xref>).
    </p>
  </emu-clause>
</emu-clause>