1 DateTimeFormat Objects

1.1 The Intl.DateTimeFormat Constructor

The Intl.DateTimeFormat constructor is the %DateTimeFormat% 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 .

1.1.1 Intl.DateTimeFormat ( [ locales [ , options ] ] )

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

  1. If NewTarget is undefined, let newTarget be the active function object, else let newTarget be NewTarget.
  2. Let dateTimeFormat be ? OrdinaryCreateFromConstructor(newTarget, "%DateTimeFormat.prototype%", « [[InitializedDateTimeFormat]], [[Locale]], [[Calendar]], [[NumberingSystem]], [[TimeZone]], [[EraDisplay]], [[Weekday]], [[Era]], [[Year]], [[Month]], [[Day]], [[DayPeriod]], [[Hour]], [[Minute]], [[Second]], [[FractionalSecondDigits]], [[TimeZoneName]], [[HourCycle]], [[Pattern]], [[BoundFormat]] »).
  3. Perform ? InitializeDateTimeFormat(dateTimeFormat, locales, options).
  4. If the implementation supports the normative optional constructor mode of , then
    1. Let this be the this value.
    2. Return ? ChainDateTimeFormat(dateTimeFormat, NewTarget, this).
  5. Return dateTimeFormat.

1.1.1.1 ChainDateTimeFormat ( dateTimeFormat, newTarget, this )

  1. If newTarget is undefined and ? OrdinaryHasInstance(%DateTimeFormat%, this) is true, then
    1. Perform ? DefinePropertyOrThrow(this, %Intl%.[[FallbackSymbol]], PropertyDescriptor{ [[Value]]: dateTimeFormat, [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }).
    2. Return this.
  2. Return dateTimeFormat.

1.1.2 InitializeDateTimeFormat ( dateTimeFormat, locales, options )

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:

The following algorithm refers to the type nonterminal from UTS 35's Unicode Locale Identifier grammar.

  1. Let requestedLocales be ? CanonicalizeLocaleList(locales).
  2. Set options to ? ToDateTimeOptions(options, "any", "date").
  3. Let opt be a new Record.
  4. Let matcher be ? GetOption(options, "localeMatcher", string, « "lookup", "best fit" », "best fit").
  5. Set opt.[[localeMatcher]] to matcher.
  6. Let calendar be ? GetOption(options, "calendar", string, empty, undefined).
  7. If calendar is not undefined, then
    1. If calendar does not match the Unicode Locale Identifier type nonterminal, throw a RangeError exception.
  8. Set opt.[[ca]] to calendar.
  9. Let numberingSystem be ? GetOption(options, "numberingSystem", string, empty, undefined).
  10. If numberingSystem is not undefined, then
    1. If numberingSystem does not match the Unicode Locale Identifier type nonterminal, throw a RangeError exception.
  11. Set opt.[[nu]] to numberingSystem.
  12. Let hour12 be ? GetOption(options, "hour12", boolean, empty, undefined).
  13. Let hourCycle be ? GetOption(options, "hourCycle", string, « "h11", "h12", "h23", "h24" », undefined).
  14. If hour12 is not undefined, then
    1. Set hourCycle to null.
  15. Set opt.[[hc]] to hourCycle.
  16. Let localeData be %DateTimeFormat%.[[LocaleData]].
  17. Let r be ResolveLocale(%DateTimeFormat%.[[AvailableLocales]], requestedLocales, opt, %DateTimeFormat%.[[RelevantExtensionKeys]], localeData).
  18. Set dateTimeFormat.[[Locale]] to r.[[locale]].
  19. Let resolvedCalendar be r.[[ca]].
  20. Set dateTimeFormat.[[Calendar]] to resolvedCalendar.
  21. Set dateTimeFormat.[[NumberingSystem]] to r.[[nu]].
  22. Let dataLocale be r.[[dataLocale]].
  23. Let dataLocaleData be localeData.[[<dataLocale>]].
  24. Let hcDefault be dataLocaleData.[[hourCycle]].
  25. If hour12 is true, then
    1. If hcDefault is "h11" or "h23", let hc be "h11". Otherwise, let hc be "h12".
  26. Else if hour12 is false, then
    1. If hcDefault is "h11" or "h23", let hc be "h23". Otherwise, let hc be "h24".
  27. Else,
    1. Assert: hour12 is undefined.
    2. Let hc be r.[[hc]].
    3. If hc is null, set hc to hcDefault.
  28. Set dateTimeFormat.[[HourCycle]] to hc.
  29. Set dateTimeFormat.[[HourCycle]] to ? GetOption (options, "eraDisplay", "string", « "never", "always", "auto" », "auto").
  30. If dateTimeFormat.[[EraDisplay]] is "auto", then
    1. If dateTimeFormat.[[Year]] is undefined, then
      1. Set dateTimeFormat.[[EraDisplay]] to "never".
  31. If dateTimeFormat.[[EraDisplay]] is not "never", then
    1. If dateTimeFormat.[[Era]] is undefined, then
      1. Set dateTimeFormat.[[Era]] to "short".
  32. Let timeZone be ? Get(options, "timeZone").
  33. If timeZone is undefined, then
    1. Set timeZone to DefaultTimeZone().
  34. Else,
    1. Set timeZone to ? ToString(timeZone).
    2. If the result of ! IsValidTimeZoneName(timeZone) is false, then
      1. Throw a RangeError exception.
    3. Set timeZone to ! CanonicalizeTimeZoneName(timeZone).
  35. Set dateTimeFormat.[[TimeZone]] to timeZone.
  36. Let formatOptions be a new Record.
  37. Set formatOptions.[[hourCycle]] to hc.
  38. Let hasExplicitFormatComponents be false.
  39. For each row of Table 3, except the header row, in table order, do
    1. Let prop be the name given in the Property column of the row.
    2. If prop is "fractionalSecondDigits", then
      1. Let value be ? GetNumberOption(options, "fractionalSecondDigits", 1, 3, undefined).
    3. Else,
      1. Let values be a List whose elements are the strings given in the Values column of the row.
      2. Let value be ? GetOption(options, prop, string, values, undefined).
    4. Set formatOptions.[[<prop>]] to value.
    5. If value is not undefined, then
      1. Set hasExplicitFormatComponents to true.
  40. Let matcher be ? GetOption(options, "formatMatcher", string, « "basic", "best fit" », "best fit").
  41. Let dateStyle be ? GetOption(options, "dateStyle", string, « "full", "long", "medium", "short" », undefined).
  42. Set dateTimeFormat.[[DateStyle]] to dateStyle.
  43. Let timeStyle be ? GetOption(options, "timeStyle", string, « "full", "long", "medium", "short" », undefined).
  44. Set dateTimeFormat.[[TimeStyle]] to timeStyle.
  45. If dateStyle is not undefined or timeStyle is not undefined, then
    1. If hasExplicitFormatComponents is true, then
      1. Throw a TypeError exception.
    2. Let styles be dataLocaleData.[[styles]].[[<resolvedCalendar>]].
    3. Let bestFormat be DateTimeStyleFormat(dateStyle, timeStyle, styles).
  46. Else,
    1. Let formats be dataLocaleData.[[formats]].[[<resolvedCalendar>]].
    2. If matcher is "basic", then
      1. Let bestFormat be BasicFormatMatcher(formatOptions, formats).
    3. Else,
      1. Let bestFormat be BestFitFormatMatcher(formatOptions, formats).
  47. For each row in Table 3, except the header row, in table order, do
    1. Let prop be the name given in the Property column of the row.
    2. If bestFormat has a field [[<prop>]], then
      1. Let p be bestFormat.[[<prop>]].
      2. Set dateTimeFormat's internal slot whose name is the Internal Slot column of the row to p.
  48. If dateTimeFormat.[[Hour]] is undefined, then
    1. Set dateTimeFormat.[[HourCycle]] to undefined.
  49. If dateTimeformat.[[HourCycle]] is "h11" or "h12", then
    1. Let pattern be bestFormat.[[pattern12]].
    2. Let patternEra be bestFormat.[[pattern12Era]].
    3. Let rangePatterns be bestFormat.[[rangePatterns12]].
  50. Else,
    1. Let pattern be bestFormat.[[pattern]].
    2. Let patternEra be bestFormat.[[patternEra]].
    3. Let rangePatterns be bestFormat.[[rangePatterns]].
  51. Set dateTimeFormat.[[Pattern]] to pattern.
  52. Set dateTimeFormat.[[PatternEra]] to pattern.
  53. Set dateTimeFormat.[[RangePatterns]] to rangePatterns.
  54. Return dateTimeFormat.

1.2 Properties of the Intl.DateTimeFormat Constructor

The Intl.DateTimeFormat constructor has the following properties:

1.2.1 Intl.DateTimeFormat.prototype

The value of Intl.DateTimeFormat.prototype is %DateTimeFormat.prototype%.

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

1.2.2 Intl.DateTimeFormat.supportedLocalesOf ( locales [ , options ] )

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

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

1.2.3 Internal slots

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

The value of the [[RelevantExtensionKeys]] internal slot is « "ca", "hc", "nu" ».

Note 1
Unicode Technical Standard 35 describes four locale extension keys that are relevant to date and time formatting: "ca" for calendar, "hc" for hour cycle, "nu" for numbering system (of formatted numbers), and "tz" for time zone. DateTimeFormat, however, requires that the time zone is specified through the "timeZone" property in the options objects.

The value of the [[LocaleData]] internal slot is implementation-defined within the constraints described in and the following additional constraints, for all locale values locale:

  • [[LocaleData]].[[<locale>]].[[nu]] must be a List that does not include the values "native", "traditio", or "finance".
  • [[LocaleData]].[[<locale>]].[[hc]] must be « null, "h11", "h12", "h23", "h24" ».
  • [[LocaleData]].[[<locale>]].[[hourCycle]] must be a String value equal to "h11", "h12", "h23", or "h24".
  • [[LocaleData]].[[<locale>]] must have a [[formats]] field. This [[formats]] field must be a Record with [[<calendar>]] fields for all calendar values calendar. The value of this field must be a list of records, each of which has a subset of the fields shown in Table 3, where each field must have one of the values specified for the field in Table 3. 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:
    • weekday, year, month, day, hour, minute, second, fractionalSecondDigits
    • weekday, year, month, day, hour, minute, second
    • weekday, year, month, day
    • year, month, day
    • year, month
    • month, day
    • hour, minute, second, fractionalSecondDigits
    • hour, minute, second
    • hour, minute
    • dayPeriod, hour
    • dayPeriod, hour, minute, second
    • dayPeriod, hour, minute
    Each of the records must also have the following fields:
    1. 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 "}".
    2. 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 at least one of the substrings "{ampm}" or "{dayPeriod}".
    3. If the record has a [[year]] field, the [[pattern]] and [[pattern12]] values may contain the substrings "{yearName}" and "{relatedYear}". In addition, it must also have a [[patternEra]] field, whose value is a String that, in addition to the substrings of the [[pattern]] field, contains the substring "{Era}".
    4. If the record has a both an [[hour]] and a [[year]] field, it must also have a [[pattern12Era]] field, whose value is a String that, in addition to the substrings of the [[pattern12]] field, contains the substring "{Era}".
    5. A [[rangePatterns]] field with a Record value:
      • The [[rangePatterns]] record may have any of the fields in Table 1, where each field represents a range pattern and its value is a Record.
        • The name of the field indicates the largest calendar element that must be different between the start and end dates in order to use this range pattern. For example, if the field name is [[Month]], it contains the range pattern that should be used to format a date range where the era and year values are the same, but the month value is different.
        • The record will contain the following fields:
          • A subset of the fields shown in the Property column of Table 3, where each field must have one of the values specified for that field in the Values column of Table 3. All fields required to format a date for any of the [[PatternParts]] records must be present.
          • A [[PatternParts]] field whose value is a list of Records each representing a part of the range pattern. Each record contains a [[Pattern]] field and a [[Source]] field. The [[Pattern]] field's value is a String of the same format as the regular date pattern String. The [[Source]] field is one of the String values "shared", "startRange", or "endRange". It indicates which of the range's dates should be formatted using the value of the [[Pattern]] field.
      • The [[rangePatterns]] record must have a [[Default]] field which contains the default range pattern used when the specific range pattern is not available. Its value is a list of records with the same structure as the other fields in the [[rangePatterns]] record.
    6. If the record has an [[hour]] field, it must also have a [[rangePatterns12]] field. Its value is similar to the Record in [[rangePatterns]], but it uses a String similar to [[pattern12]] for each part of the range pattern.
    7. If the record has a [[year]] field, the [[rangePatterns]] and [[rangePatterns12]] fields may contain range patterns where the [[Pattern]] values may contain the substrings "{yearName}" and "{relatedYear}".
  • [[LocaleData]].[[<locale>]] must have a [[styles]] field. The [[styles]] field must be a Record with [[<calendar>]] fields for all calendar values calendar. The calendar records must contain [[DateFormat]], [[TimeFormat]], [[DateTimeFormat]] and [[DateTimeRangeFormat]] fields, the value of these fields are Records, where each of which has [[full]], [[long]], [[medium]] and [[short]] fields. For [[DateFormat]] and [[TimeFormat]], the value of these fields must be a record, which has a subset of the fields shown in Table 3, where each field must have one of the values specified for the field in Table 3. Each of the records must also have the following fields:
    1. 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 "}".
    2. 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 at least one of the substrings "{ampm}" or "{dayPeriod}". In addition, it must also have a [[patternEra]] field, whose value is a String that, in addition to the substrings of the [[pattern]] field, contains the substring "{Era}".
    3. If the record has a both an [[hour]] and a [[year]] field, it must also have a [[pattern12Era]] field, whose value is a String that, in addition to the substrings of the [[pattern12]] field, contains the substring "{Era}".
    4. A [[rangePatterns]] field that contains a record similar to the one described in the [[formats]] field.
    5. If the record has an [[hour]] field, it must also have a [[rangePatterns12]] field. Its value is similar to the record in [[rangePatterns]] but it uses a string similar to [[pattern12]] for each range pattern.
    For [[DateTimeFormat]], the field value must be a string pattern which contains the strings "{0}" and "{1}". For [[DateTimeRangeFormat]] the value of these fields must be a nested record which also has [[full]], [[long]], [[medium]] and [[short]] fields. The [[full]], [[long]], [[medium]] and [[short]] fields in the enclosing record refer to the date style of the range pattern, while the fields in the nested record refers to the time style of the range pattern. The value of these fields in the nested record is a record with a [[rangePatterns]] field and a [[rangePatterns12]] field which are similar to the [[rangePatterns]] and [rangePatterns12]] fields in [[DateFormat]] and [[TimeFormat]].
Note 2
For example, an implementation might include the following record as part of its English locale data:
  • [[hour]]: "numeric"
  • [[minute]]: "numeric"
  • [[pattern]]: "{hour}:{minute}"
  • [[pattern12]]: "{hour}:{minute} {ampm}"
  • [[rangePatterns]]:
    • [[Hour]]:
      • [[hour]]: "numeric"
      • [[minute]]: "numeric"
      • [[PatternParts]]:
        • {[[Source]]: "startRange", [[Pattern]]: "{hour}:{minute}"}
        • {[[Source]]: "shared", [[Pattern]]: " – "}
        • {[[Source]]: "endRange", [[Pattern]]: "{hour}:{minute}"}
    • [[Minute]]:
      • [[hour]]: "numeric"
      • [[minute]]: "numeric"
      • [[PatternParts]]:
        • {[[Source]]: "startRange", [[Pattern]]: "{hour}:{minute}"}
        • {[[Source]]: "shared", [[Pattern]]: " – "}
        • {[[Source]]: "endRange", [[Pattern]]: "{hour}:{minute}"}
    • [[Default]]:
      • [[year]]: "2-digit"
      • [[month]]: "numeric"
      • [[day]]: "numeric"
      • [[hour]]: "numeric"
      • [[minute]]: "numeric"
      • [[PatternParts]]:
        • {[[Source]]: "startRange", [[Pattern]]: "{day}/{month}/{year}, {hour}:{minute}"}
        • {[[Source]]: "shared", [[Pattern]]: " – "}
        • {[[Source]]: "endRange", [[Pattern]]: "{day}/{month}/{year}, {hour}:{minute}"}
  • [[rangePatterns12]]:
    • [[Hour]]:
      • [[hour]]: "numeric"
      • [[minute]]: "numeric"
      • [[PatternParts]]:
        • {[[Source]]: "startRange", [[Pattern]]: "{hour}:{minute}"}
        • {[[Source]]: "shared", [[Pattern]]: " – "}
        • {[[Source]]: "endRange", [[Pattern]]: "{hour}:{minute}"}
        • {[[Source]]: "shared", [[Pattern]]: " {ampm}"}
    • [[Minute]]:
      • [[hour]]: "numeric"
      • [[minute]]: "numeric"
      • [[PatternParts]]:
        • {[[Source]]: "startRange", [[Pattern]]: "{hour}:{minute}"}
        • {[[Source]]: "shared", [[Pattern]]: " – "}
        • {[[Source]]: "endRange", [[Pattern]]: "{hour}:{minute}"}
        • {[[Source]]: "shared", [[Pattern]]: " {ampm}"}
    • [[Default]]:
      • [[year]]: "2-digit"
      • [[month]]: "numeric"
      • [[day]]: "numeric"
      • [[hour]]: "numeric"
      • [[minute]]: "numeric"
      • [[PatternParts]]:
        • {[[Source]]: "startRange", [[Pattern]]: "{day}/{month}/{year}, {hour}:{minute} {ampm}"}
        • {[[Source]]: "shared", [[Pattern]]: " – "}
        • {[[Source]]: "endRange", [[Pattern]]: "{day}/{month}/{year}, {hour}:{minute} {ampm}"}
 Note 3
It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at https://cldr.unicode.org/).
Table 1: Range pattern fields
Range Pattern Field Pattern String Field
[[Era]] "era"
[[Year]] "year"
[[Month]] "month"
[[Day]] "day"
[[AmPm]] "ampm"
[[DayPeriod]] "dayPeriod"
[[Hour]] "hour"
[[Minute]] "minute"
[[Second]] "second"
[[FractionalSecondDigits]] "fractionalSecondDigits"

1.3 Properties of the Intl.DateTimeFormat Prototype Object

The Intl.DateTimeFormat prototype object is itself an ordinary object. %DateTimeFormat.prototype% 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.

1.3.1 Intl.DateTimeFormat.prototype.constructor

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

1.3.2 Intl.DateTimeFormat.prototype [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "Intl.DateTimeFormat".

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

1.3.3 get Intl.DateTimeFormat.prototype.format

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

  1. Let dtf be the this value.
  2. If the implementation supports the normative optional constructor mode of , then
    1. Set dtf to ? UnwrapDateTimeFormat(dtf).
  3. Perform ? RequireInternalSlot(dtf, [[InitializedDateTimeFormat]]).
  4. If dtf.[[BoundFormat]] is undefined, then
    1. Let F be a new built-in function object as defined in DateTime Format Functions (1.5.5).
    2. Set F.[[DateTimeFormat]] to dtf.
    3. Set dtf.[[BoundFormat]] to F.
  5. Return dtf.[[BoundFormat]].
 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.

1.3.4 Intl.DateTimeFormat.prototype.formatToParts ( date )

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

  1. Let dtf be the this value.
  2. Perform ? RequireInternalSlot(dtf, [[InitializedDateTimeFormat]]).
  3. If date is undefined, then
    1. Let x be ! Call(%Date.now%, undefined).
  4. Else,
    1. Let x be ? ToNumber(date).
  5. Return ? FormatDateTimeToParts(dtf, x).

1.3.5 Intl.DateTimeFormat.prototype.formatRange ( startDate, endDate )

When the formatRange method is called with arguments startDate and endDate, the following steps are taken:

  1. Let dtf be this value.
  2. Perform ? RequireInternalSlot(dtf, [[InitializedDateTimeFormat]]).
  3. If startDate is undefined or endDate is undefined, throw a TypeError exception.
  4. Let x be ? ToNumber(startDate).
  5. Let y be ? ToNumber(endDate).
  6. Return ? FormatDateTimeRange(dtf, x, y).

1.3.6 Intl.DateTimeFormat.prototype.formatRangeToParts ( startDate, endDate )

When the formatRangeToParts method is called with arguments startDate and endDate, the following steps are taken:

  1. Let dtf be this value.
  2. Perform ? RequireInternalSlot(dtf, [[InitializedDateTimeFormat]]).
  3. If startDate is undefined or endDate is undefined, throw a TypeError exception.
  4. Let x be ? ToNumber(startDate).
  5. Let y be ? ToNumber(endDate).
  6. Return ? FormatDateTimeRangeToParts(dtf, x, y).

1.3.7 Intl.DateTimeFormat.prototype.resolvedOptions ( )

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

  1. Let dtf be the this value.
  2. If the implementation supports the normative optional constructor mode of , then
    1. Set dtf to ? UnwrapDateTimeFormat(dtf).
  3. Perform ? RequireInternalSlot(dtf, [[InitializedDateTimeFormat]]).
  4. Let options be OrdinaryObjectCreate(%Object.prototype%).
  5. For each row of Table 2, except the header row, in table order, do
    1. Let p be the Property value of the current row.
    2. If p is "hour12", then
      1. Let hc be dtf.[[HourCycle]].
      2. If hc is "h11" or "h12", let v be true.
      3. Else if, hc is "h23" or "h24", let v be false.
      4. Else, let v be undefined.
    3. Else,
      1. Let v be the value of dtf's internal slot whose name is the Internal Slot value of the current row.
    4. If the Internal Slot value of the current row is an Internal Slot value in Table 3, then
      1. If dtf.[[DateStyle]] is not undefined or dtf.[[TimeStyle]] is not undefined, then
        1. Let v be undefined.
    5. If v is not undefined, then
      1. Perform ! CreateDataPropertyOrThrow(options, p, v).
  6. Return options.
Table 2: Resolved Options of DateTimeFormat Instances
Internal Slot Property
[[Locale]] "locale"
[[Calendar]] "calendar"
[[NumberingSystem]] "numberingSystem"
[[TimeZone]] "timeZone"
[[HourCycle]] "hourCycle"
"hour12"
[[Weekday]] "weekday"
[[EraDisplay]] "eraDisplay"
[[Era]] "era"
[[Year]] "year"
[[Month]] "month"
[[Day]] "day"
[[DayPeriod]] "dayPeriod"
[[Hour]] "hour"
[[Minute]] "minute"
[[Second]] "second"
[[FractionalSecondDigits]] "fractionalSecondDigits"
[[TimeZoneName]] "timeZoneName"
[[DateStyle]] "dateStyle"
[[TimeStyle]] "timeStyle"

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".

Note 1
In this version of the ECMAScript 2023 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.
Note 2
For compatibility with versions prior to the fifth edition, the "hour12" property is set in addition to the "hourCycle" property.

1.4 Properties of Intl.DateTimeFormat Instances

Intl.DateTimeFormat instances are ordinary objects that inherit properties from %DateTimeFormat.prototype%.

Intl.DateTimeFormat instances have an [[InitializedDateTimeFormat]] internal slot.

Intl.DateTimeFormat 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 for formatting.
  • [[Calendar]] is a String value with the "type" given in Unicode Technical Standard 35 for the calendar used for formatting.
  • [[NumberingSystem]] is a String value with the "type" given in Unicode Technical Standard 35 for the numbering system used for formatting.
  • [[TimeZone]] is a String value with the IANA time zone name of the time zone used for formatting.
  • [[Weekday]], [[Era]], [[Year]], [[Month]], [[Day]], [[DayPeriod]], [[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 Table 3, indicating how the component should be presented in the formatted output.
  • [[FractionalSecondDigits]] is either undefined or a positive, non-zero integer Number value indicating the fraction digits to be used for fractional seconds. Numbers will be rounded or padded with trailing zeroes if necessary.
  • [[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.
  • [[EraDisplay]] is a String value indicating if a test on the x Number passed to the PartitionDateTimePattern abstract operation should be done in order to possibly skip the [[Era]] component.
  • [[DateStyle]], [[TimeStyle]] are each either undefined, or a String value with values "full", "long", "medium", or "short".
  • [[Pattern]] is a String value as described in 1.2.3.
  • [[PatternEra]] is a Record as described in 1.2.3.
  • [[RangePatterns]] is a Record as described in 1.2.3.

Finally, Intl.DateTimeFormat instances have a [[BoundFormat]] internal slot that caches the function returned by the format accessor (1.3.3).

1.5 Abstract Operations for DateTimeFormat Objects

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:

Table 3: Components of date and time formats
Internal Slot Property Values
[[Weekday]] "weekday" "narrow", "short", "long"
[[Era]] "era" "narrow", "short", "long"
[[Year]] "year" "2-digit", "numeric"
[[Month]] "month" "2-digit", "numeric", "narrow", "short", "long"
[[Day]] "day" "2-digit", "numeric"
[[DayPeriod]] "dayPeriod" "narrow", "short", "long"
[[Hour]] "hour" "2-digit", "numeric"
[[Minute]] "minute" "2-digit", "numeric"
[[Second]] "second" "2-digit", "numeric"
[[FractionalSecondDigits]] "fractionalSecondDigits" 1𝔽, 2𝔽, 3𝔽
[[TimeZoneName]] "timeZoneName" "short", "long", "shortOffset", "longOffset", "shortGeneric", "longGeneric"

1.5.1 ToDateTimeOptions ( options, required, defaults )

When the ToDateTimeOptions abstract operation is called with arguments options, required, and defaults, the following steps are taken:

  1. If options is undefined, let options be null; otherwise let options be ? ToObject(options).
  2. Let options be OrdinaryObjectCreate(options).
  3. Let needDefaults be true.
  4. If required is "date" or "any", then
    1. For each property name prop of « "weekday", "year", "month", "day" », do
      1. Let value be ? Get(options, prop).
      2. If value is not undefined, let needDefaults be false.
  5. If required is "time" or "any", then
    1. For each property name prop of « "dayPeriod", "hour", "minute", "second", "fractionalSecondDigits" », do
      1. Let value be ? Get(options, prop).
      2. If value is not undefined, let needDefaults be false.
  6. Let dateStyle be ? Get(options, "dateStyle").
  7. Let timeStyle be ? Get(options, "timeStyle").
  8. If dateStyle is not undefined or timeStyle is not undefined, let needDefaults be false.
  9. If required is "date" and timeStyle is not undefined, then
    1. Throw a TypeError exception.
  10. If required is "time" and dateStyle is not undefined, then
    1. Throw a TypeError exception.
  11. If needDefaults is true and defaults is either "date" or "all", then
    1. For each property name prop of « "year", "month", "day" », do
      1. Perform ? CreateDataPropertyOrThrow(options, prop, "numeric").
  12. If needDefaults is true and defaults is either "time" or "all", then
    1. For each property name prop of « "hour", "minute", "second" », do
      1. Perform ? CreateDataPropertyOrThrow(options, prop, "numeric").
  13. Return options.

1.5.2 DateTimeStyleFormat ( dateStyle, timeStyle, styles )

The DateTimeStyleFormat abstract operation accepts arguments dateStyle and timeStyle, which are each either undefined, "full", "long", "medium", or "short", at least one of which is not undefined, and styles, which is a record from %DateTimeFormat%.[[LocaleData]].[[<locale>]].[[styles]].[[<calendar>]] for some locale locale and calendar calendar. It returns the appropriate format record for date time formatting based on the parameters.

  1. If timeStyle is not undefined, then
    1. Assert: timeStyle is one of "full", "long", "medium", or "short".
    2. Let timeFormat be styles.[[TimeFormat]].[[<timeStyle>]].
  2. If dateStyle is not undefined, then
    1. Assert: dateStyle is one of "full", "long", "medium", or "short".
    2. Let dateFormat be styles.[[DateFormat]].[[<dateStyle>]].
  3. If dateStyle is not undefined and timeStyle is not undefined, then
    1. Let format be a new Record.
    2. Add to format all fields from dateFormat except [[pattern]], [[patternEra]], and [[rangePatterns]].
    3. Add to format all fields from timeFormat except [[pattern]], [[patternEra]],, [[rangePatterns]], [[pattern12]], and [[rangePatterns12]], if present.
    4. Let connector be styles.[[DateTimeFormat]].[[<dateStyle>]].
    5. Let pattern be the string connector with the substring "{0}" replaced with timeFormat.[[pattern]] and the substring "{1}" replaced with dateFormat.[[pattern]].
    6. Set format.[[pattern]] to pattern.
    7. If timeFormat has a [[pattern12]] field, then
      1. Let pattern12 be the string connector with the substring "{0}" replaced with timeFormat.[[pattern12]] and the substring "{1}" replaced with dateFormat.[[pattern]].
      2. Set format.[[pattern12]] to pattern12.
    8. If dateFormat has a [[patternEra]] field, then
      1. Let patternEra be the string connector with the substring "{0}" replaced with timeFormat.[[pattern]] and the substring "{1}" replaced with dateFormat.[[patternEra]].
      2. Set format.[[patternEra]] to patternEra.
    9. If dateFormat has a [[patternEra]] field and timeFormat has a [[pattern12]] field, then
      1. Let pattern12Era be the string connector with the substring "{0}" replaced with timeFormat.[[pattern12]] and the substring "{1}" replaced with dateFormat.[[patternEra]].
      2. Set format.[[pattern12Era]] to pattern12Era.
    10. Let dateTimeRangeFormat be styles.[[DateTimeRangeFormat]].[[<dateStyle>]].[[<timeStyle>]].
    11. Set format.[[rangePatterns]] to dateTimeRangeFormat.[[rangePatterns]].
    12. If dateTimeRangeFormat has a [[rangePatterns12]] field, then
      1. Set format.[[rangePatterns12]] to dateTimeRangeFormat.[[rangePatterns12]].
    13. Return format.
  4. If timeStyle is not undefined, then
    1. Return timeFormat.
  5. Assert: dateStyle is not undefined.
  6. Return dateFormat.

1.5.3 BasicFormatMatcher ( options, formats )

When the BasicFormatMatcher abstract operation is called with two arguments options and formats, the following steps are taken:

  1. Let removalPenalty be 120.
  2. Let additionPenalty be 20.
  3. Let longLessPenalty be 8.
  4. Let longMorePenalty be 6.
  5. Let shortLessPenalty be 6.
  6. Let shortMorePenalty be 3.
  7. Let offsetPenalty be 1.
  8. Let bestScore be -Infinity.
  9. Let bestFormat be undefined.
  10. Assert: Type(formats) is List.
  11. For each element format of formats, do
    1. Let score be 0.
    2. For each property name property shown in Table 3, do
      1. If options has a field [[<property>]], let optionsProp be options.[[<property>]]; else let optionsProp be undefined.
      2. If format has a field [[<property>]], let formatProp be format.[[<property>]]; else let formatProp be undefined.
      3. If optionsProp is undefined and formatProp is not undefined, decrease score by additionPenalty.
      4. Else if optionsProp is not undefined and formatProp is undefined, decrease score by removalPenalty.
      5. Else if property is "timeZoneName", then
        1. If optionsProp is "short" or "shortGeneric", then
          1. If formatProp is "shortOffset", decrease score by offsetPenalty.
          2. Else if formatProp is "longOffset", decrease score by (offsetPenalty + shortMorePenalty).
          3. Else if optionsProp is "short" and formatProp is "long", decrease score by shortMorePenalty.
          4. Else if optionsProp is "shortGeneric" and formatProp is "longGeneric", decrease score by shortMorePenalty.
          5. Else if optionsProp ≠ formatProp, decrease score by removalPenalty.
        2. Else if optionsProp is "shortOffset" and formatProp is "longOffset", decrease score by shortMorePenalty.
        3. Else if optionsProp is "long" or "longGeneric", then
          1. If formatProp is "longOffset", decrease score by offsetPenalty.
          2. Else if formatProp is "shortOffset", decrease score by (offsetPenalty + longLessPenalty).
          3. Else if optionsProp is "long" and formatProp is "short", decrease score by longLessPenalty.
          4. Else if optionsProp is "longGeneric" and formatProp is "shortGeneric", decrease score by longLessPenalty.
          5. Else if optionsProp ≠ formatProp, decrease score by removalPenalty.
        4. Else if optionsProp is "longOffset" and formatProp is "shortOffset", decrease score by longLessPenalty.
        5. Else if optionsProp ≠ formatProp, decrease score by removalPenalty.
      6. Else if optionsProp ≠ formatProp, then
        1. If property is "fractionalSecondDigits", then
          1. Let values be « 1𝔽, 2𝔽, 3𝔽 ».
        2. Else,
          1. Let values be « "2-digit", "numeric", "narrow", "short", "long" ».
        3. Let optionsPropIndex be the index of optionsProp within values.
        4. Let formatPropIndex be the index of formatProp within values.
        5. Let delta be max(min(formatPropIndex - optionsPropIndex, 2), -2).
        6. If delta = 2, decrease score by longMorePenalty.
        7. Else if delta = 1, decrease score by shortMorePenalty.
        8. Else if delta = -1, decrease score by shortLessPenalty.
        9. Else if delta = -2, decrease score by longLessPenalty.
    3. If score > bestScore, then
      1. Let bestScore be score.
      2. Let bestFormat be format.
  12. Return bestFormat.

1.5.4 BestFitFormatMatcher ( options, formats )

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.

1.5.5 DateTime Format Functions

A DateTime format function is an anonymous built-in function that has a [[DateTimeFormat]] internal slot.

When a DateTime format function F is called with optional argument date, the following steps are taken:

  1. Let dtf be F.[[DateTimeFormat]].
  2. Assert: Type(dtf) is Object and dtf has an [[InitializedDateTimeFormat]] internal slot.
  3. If date is not provided or is undefined, then
    1. Let x be ! Call(%Date.now%, undefined).
  4. Else,
    1. Let x be ? ToNumber(date).
  5. Return ? FormatDateTime(dtf, x).

The "length" property of a DateTime format function is 1.

1.5.6 FormatDateTimePattern ( dateTimeFormat, patternParts, x, rangeFormatOptions )

The FormatDateTimePattern abstract operation is called with arguments dateTimeFormat (which must be an object initialized as a DateTimeFormat), patternParts (which is a list of Records as returned by PartitionPattern), x (which must be a Number value), and rangeFormatOptions (which is a range pattern Record as used in [[rangePattern]] or undefined), interprets x as a time value as specified in es2023, 20.4.1.1, and creates the corresponding parts according pattern and to the effective locale and the formatting options of dateTimeFormat and rangeFormatOptions. The following steps are taken:

  1. Let x be TimeClip(x).
  2. If x is NaN, throw a RangeError exception.
  3. Let locale be dateTimeFormat.[[Locale]].
  4. Let nfOptions be OrdinaryObjectCreate(null).
  5. Perform ! CreateDataPropertyOrThrow(nfOptions, "useGrouping", false).
  6. Let nf be ? Construct(%NumberFormat%, « locale, nfOptions »).
  7. Let nf2Options be OrdinaryObjectCreate(null).
  8. Perform ! CreateDataPropertyOrThrow(nf2Options, "minimumIntegerDigits", 2).
  9. Perform ! CreateDataPropertyOrThrow(nf2Options, "useGrouping", false).
  10. Let nf2 be ? Construct(%NumberFormat%, « locale, nf2Options »).
  11. Let fractionalSecondDigits be dateTimeFormat.[[FractionalSecondDigits]].
  12. If fractionalSecondDigits is not undefined, then
    1. Let nf3Options be OrdinaryObjectCreate(null).
    2. Perform ! CreateDataPropertyOrThrow(nf3Options, "minimumIntegerDigits", fractionalSecondDigits).
    3. Perform ! CreateDataPropertyOrThrow(nf3Options, "useGrouping", false).
    4. Let nf3 be ? Construct(%NumberFormat%, « locale, nf3Options »).
  13. Let tm be ToLocalTime(ℤ(ℝ(x) × 106), dateTimeFormat.[[Calendar]], dateTimeFormat.[[TimeZone]]).
  14. Let result be a new empty List.
  15. For each Record { [[Type]], [[Value]] } patternPart in patternParts, do
    1. Let p be patternPart.[[Type]].
    2. If p is "literal", then
      1. Append a new Record { [[Type]]: "literal", [[Value]]: patternPart.[[Value]] } as the last element of the list result.
    3. Else if p is equal to "fractionalSecondDigits", then
      1. Let v be tm.[[Millisecond]].
      2. Let v be floor(v × 10( fractionalSecondDigits - 3 )).
      3. Let fv be FormatNumeric(nf3, v).
      4. Append a new Record { [[Type]]: "fractionalSecond", [[Value]]: fv } as the last element of result.
    4. Else if p is equal to "dayPeriod", then
      1. Let f be the value of dateTimeFormat's internal slot whose name is the Internal Slot column of the matching row.
      2. Let fv be a String value representing the day period of tm in the form given by f; the String value depends upon the implementation and the effective locale of dateTimeFormat.
      3. Append a new Record { [[Type]]: p, [[Value]]: fv } as the last element of the list result.
    5. Else if p is equal to "timeZoneName", then
      1. Let f be dateTimeFormat.[[TimeZoneName]].
      2. Let v be dateTimeFormat.[[TimeZone]].
      3. Let fv be a String value representing v in the form given by f; the String value depends upon the implementation and the effective locale of dateTimeFormat. The String value may also depend on the value of the [[InDST]] field of tm if f is "short", "long", "shortOffset", or "longOffset". If the implementation does not have a localized representation of f, then use the String value of v itself.
      4. Append a new Record { [[Type]]: p, [[Value]]: fv } as the last element of the list result.
    6. Else if p matches a Property column of the row in Table 3, then
      1. If rangeFormatOptions is not undefined, let f be the value of rangeFormatOptions's field whose name matches p.
      2. Else, let f be the value of dateTimeFormat's internal slot whose name is the Internal Slot column of the matching row.
      3. Let v be the value of tm's field whose name is the Internal Slot column of the matching row.
      4. If p is "year" and v ≤ 0, let v be 1 - v.
      5. If p is "month", increase v by 1.
      6. If p is "hour" and dateTimeFormat.[[HourCycle]] is "h11" or "h12", then
        1. Let v be v modulo 12.
        2. If v is 0 and dateTimeFormat.[[HourCycle]] is "h12", let v be 12.
      7. If p is "hour" and dateTimeFormat.[[HourCycle]] is "h24", then
        1. If v is 0, let v be 24.
      8. If f is "numeric", then
        1. Let fv be FormatNumeric(nf, v).
      9. Else if f is "2-digit", then
        1. Let fv be FormatNumeric(nf2, v).
        2. If the "length" property of fv is greater than 2, let fv be the substring of fv containing the last two characters.
      10. Else if f is "narrow", "short", or "long", then let fv be a String value representing v in the form given by f; the String value depends upon the implementation and the effective locale and calendar of dateTimeFormat. If p is "month" and rangeFormatOptions is undefined, then the String value may also depend on whether dateTimeFormat.[[Day]] is undefined. If p is "month" and rangeFormatOptions is not undefined, then the String value may also depend on whether rangeFormatOptions.[[day]] is undefined. If p is "era" and rangeFormatOptions is undefined, then the String value may also depend on whether dateTimeFormat.[[Era]] is undefined. If p is "era" and rangeFormatOptions is not undefined, then the String value may also depend on whether rangeFormatOptions.[[era]] is undefined. If the implementation does not have a localized representation of f, then use the String value of v itself.
      11. Append a new Record { [[Type]]: p, [[Value]]: fv } as the last element of the list result.
    7. Else if p is equal to "ampm", then
      1. Let v be tm.[[Hour]].
      2. If v is greater than 11, then
        1. Let fv be an implementation and locale dependent String value representing "post meridiem".
      3. Else,
        1. Let fv be an implementation and locale dependent String value representing "ante meridiem".
      4. Append a new Record { [[Type]]: "dayPeriod", [[Value]]: fv } as the last element of the list result.
    8. Else if p is equal to "relatedYear", then
      1. Let v be tm.[[RelatedYear]].
      2. Let fv be FormatNumeric(nf, v).
      3. Append a new Record { [[Type]]: "relatedYear", [[Value]]: fv } as the last element of the list result.
    9. Else if p is equal to "yearName", then
      1. Let v be tm.[[YearName]].
      2. Let fv be an implementation and locale dependent String value representing v.
      3. Append a new Record { [[Type]]: "yearName", [[Value]]: fv } as the last element of the list result.
    10. Else,
      1. Let unknown be an implementation-, locale-, and numbering system-dependent String based on x and p.
      2. Append a new Record { [[Type]]: "unknown", [[Value]]: unknown } as the last element of result.
  16. Return result.
 Note 1
It is recommended that implementations use the locale and calendar dependent strings provided by the Common Locale Data Repository (available at https://cldr.unicode.org/), and use CLDR "abbreviated" strings for DateTimeFormat "short" strings, and CLDR "wide" strings for DateTimeFormat "long" strings.
Note 2
It is recommended that implementations use the time zone information of the IANA Time Zone Database.

1.5.7 PartitionDateTimePattern ( dateTimeFormat, x )

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 es2023, 20.4.1.1, and creates the corresponding parts according to the effective locale and the formatting options of dateTimeFormat. The following steps are taken:

  1. If dateTimeFormat.[[EraDisplay]] is "never", then
    1. Let pattern be dateTimeFormat.[[Pattern]].
  2. If dateTimeFormat.[[EraDisplay]] is "always", then
    1. Let pattern be dateTimeFormat.[[PatternEra]].
  3. If dateTimeFormat.[[EraDisplay]] is "auto", then
    1. Let F be a DateTime format function of dateTimeFormat.
    2. If F().[[Era]] ≠ F(x).[[Era]], let pattern be dateTimeFormat.[[PatternEra]].
    3. Else, let pattern be dateTimeFormat.[[Pattern]].
  4. Let patternParts be PartitionPattern(dateTimeFormat.[[Pattern]] pattern).
  5. Let result be ? FormatDateTimePattern(dateTimeFormat, patternParts, x, undefined).
  6. Return result.

1.5.8 FormatDateTime ( dateTimeFormat, x )

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:

  1. Let parts be ? PartitionDateTimePattern(dateTimeFormat, x).
  2. Let result be the empty String.
  3. For each Record { [[Type]], [[Value]] } part in parts, do
    1. Set result to the string-concatenation of result and part.[[Value]].
  4. Return result.

1.5.9 FormatDateTimeToParts ( dateTimeFormat, x )

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:

  1. Let parts be ? PartitionDateTimePattern(dateTimeFormat, x).
  2. Let result be ! ArrayCreate(0).
  3. Let n be 0.
  4. For each Record { [[Type]], [[Value]] } part in parts, do
    1. Let O be OrdinaryObjectCreate(%Object.prototype%).
    2. Perform ! CreateDataPropertyOrThrow(O, "type", part.[[Type]]).
    3. Perform ! CreateDataPropertyOrThrow(O, "value", part.[[Value]]).
    4. Perform ! CreateDataProperty(result, ! ToString(n), O).
    5. Increment n by 1.
  5. Return result.

1.5.10 PartitionDateTimeRangePattern ( dateTimeFormat, x, y )

The PartitionDateTimeRangePattern abstract operation is called with arguments dateTimeFormat (which must be an object initialized as a DateTimeFormat), x (which must be a Number value) and y (which must be a Number value), interprets x and y as time values as specified in es2023, 20.4.1.1, and creates the corresponding parts according to the effective locale and the formatting options of dateTimeFormat. The following steps are taken:

  1. Let x be TimeClip(x).
  2. If x is NaN, throw a RangeError exception.
  3. Let y be TimeClip(y).
  4. If y is NaN, throw a RangeError exception.
  5. Let tm1 be ToLocalTime(ℤ(ℝ(x) × 106), dateTimeFormat.[[Calendar]], dateTimeFormat.[[TimeZone]]).
  6. Let tm2 be ToLocalTime(ℤ(ℝ(y) × 106), dateTimeFormat.[[Calendar]], dateTimeFormat.[[TimeZone]]).
  7. Let rangePatterns be dateTimeFormat.[[RangePatterns]].
  8. Let rangePattern be undefined.
  9. Let dateFieldsPracticallyEqual be true.
  10. Let patternContainsLargerDateField be false.
  11. While dateFieldsPracticallyEqual is true and patternContainsLargerDateField is false, repeat for each row of Table 1 in order, except the header row:
    1. Let fieldName be the name given in the Range Pattern Field column of the row.
    2. If rangePatterns has a field [[<fieldName>]], let rp be rangePatterns.[[<fieldName>]]; else let rp be undefined.
    3. If rangePattern is not undefined and rp is undefined, then
      1. Set patternContainsLargerDateField to true.
    4. Else,
      1. Let rangePattern be rp.
      2. If fieldName is equal to [[AmPm]], then
        1. Let v1 be tm1.[[Hour]].
        2. Let v2 be tm2.[[Hour]].
        3. If v1 is greater than 11 and v2 less or equal than 11, or v1 is less or equal than 11 and v2 is greater than 11, then
          1. Set dateFieldsPracticallyEqual to false.
      3. Else if fieldName is equal to [[DayPeriod]], then
        1. Let v1 be a String value representing the day period of tm1; the String value depends upon the implementation and the effective locale of dateTimeFormat.
        2. Let v2 be a String value representing the day period of tm2; the String value depends upon the implementation and the effective locale of dateTimeFormat.
        3. If v1 is not equal to v2, then
          1. Set dateFieldsPracticallyEqual to false.
      4. Else if fieldName is equal to [[FractionalSecondDigits]], then
        1. Let fractionalSecondDigits be dateTimeFormat.[[FractionalSecondDigits]].
        2. If fractionalSecondDigits is undefined, then
          1. Set fractionalSecondDigits to 3.
        3. Let v1 be tm1.[[Millisecond]].
        4. Let v2 be tm2.[[Millisecond]].
        5. Let v1 be floor(v1 × 10( fractionalSecondDigits - 3 )).
        6. Let v2 be floor(v2 × 10( fractionalSecondDigits - 3 )).
        7. If v1 is not equal to v2, then
          1. Set dateFieldsPracticallyEqual to false.
      5. Else,
        1. Let v1 be tm1.[[<fieldName>]].
        2. Let v2 be tm2.[[<fieldName>]].
        3. If v1 is not equal to v2, then
          1. Set dateFieldsPracticallyEqual to false.
  12. If dateFieldsPracticallyEqual is true, then
    1. Let pattern be dateTimeFormat.[[Pattern]].
    2. Let patternParts be PartitionPattern(pattern).
    3. Let result be ? FormatDateTimePattern(dateTimeFormat, patternParts, x, undefined).
    4. For each Record { [[Type]], [[Value]] } r in result, do
      1. Set r.[[Source]] to "shared".
    5. Return result.
  13. Let result be a new empty List.
  14. If rangePattern is undefined, then
    1. Let rangePattern be rangePatterns.[[Default]].
  15. For each Record { [[Pattern]], [[Source]] } rangePatternPart in rangePattern.[[PatternParts]], do
    1. Let pattern be rangePatternPart.[[Pattern]].
    2. Let source be rangePatternPart.[[Source]].
    3. If source is "startRange" or "shared", then
      1. Let z be x.
    4. Else,
      1. Let z be y.
    5. Let patternParts be PartitionPattern(pattern).
    6. Let partResult be ? FormatDateTimePattern(dateTimeFormat, patternParts, z, rangePattern).
    7. For each Record { [[Type]], [[Value]] } r in partResult, do
      1. Set r.[[Source]] to source.
    8. Add all elements in partResult to result in order.
  16. Return result.

1.5.11 FormatDateTimeRange ( dateTimeFormat, x, y )

The FormatDateTimeRange abstract operation is called with arguments dateTimeFormat (which must be an object initialized as a DateTimeFormat), x (which must be a Number value) and y (which must be a Number value), and performs the following steps:

  1. Let parts be ? PartitionDateTimeRangePattern(dateTimeFormat, x, y).
  2. Let result be the empty String.
  3. For each Record { [[Type]], [[Value]], [[Source]] } part in parts, do
    1. Set result to the string-concatenation of result and part.[[Value]].
  4. Return result.

1.5.12 FormatDateTimeRangeToParts ( dateTimeFormat, x, y )

The FormatDateTimeRangeToParts abstract operation is called with arguments dateTimeFormat (which must be an object initialized as a DateTimeFormat), x (which must be a Number value) and y (which must be a Number value), and performs the following steps:

  1. Let parts be ? PartitionDateTimeRangePattern(dateTimeFormat, x, y).
  2. Let result be ! ArrayCreate(0).
  3. Let n be 0.
  4. For each Record { [[Type]], [[Value]], [[Source]] } part in parts, do
    1. Let O be OrdinaryObjectCreate(%Object.prototype%).
    2. Perform ! CreateDataPropertyOrThrow(O, "type", part.[[Type]]).
    3. Perform ! CreateDataPropertyOrThrow(O, "value", part.[[Value]]).
    4. Perform ! CreateDataPropertyOrThrow(O, "source", part.[[Source]]).
    5. Perform ! CreateDataProperty(result, ! ToString(n), O).
    6. Increment n by 1.
  5. Return result.

1.5.13 ToLocalTime ( epochNs: a BigInt, calendar: a String, timeZone: a String, )

description
  1. Let offsetNs be GetNamedTimeZoneOffsetNanoseconds(timeZone, epochNs).
  2. Let tz be ℝ(epochNs) + offsetNs.
  3. If calendar is "gregory", then
    1. Return a record with fields calculated from tz according to Table 4.
  4. Else,
    1. Return a record with the fields of Column 1 of Table 4 calculated from tz for the given calendar. The calculations should use best available information about the specified calendar.
Table 4: Record returned by ToLocalTime
Field Value Calculation for Gregorian Calendar
[[Weekday]] WeekDay(𝔽(floor(tz / 106)))
[[Era]] Let year be YearFromTime(𝔽(floor(tz / 106))). If year < -0𝔽, return "BC", else return "AD".
[[Year]] YearFromTime(𝔽(floor(tz / 106)))
[[RelatedYear]] undefined
[[YearName]] undefined
[[Month]] MonthFromTime(𝔽(floor(tz / 106)))
[[Day]] DateFromTime(𝔽(floor(tz / 106)))
[[Hour]] HourFromTime(𝔽(floor(tz / 106)))
[[Minute]] MinFromTime(𝔽(floor(tz / 106)))
[[Second]] SecFromTime(𝔽(floor(tz / 106)))
[[Millisecond]] msFromTime(𝔽(floor(tz / 106)))
[[InDST]] Calculate true or false using the 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.
Note
It is recommended that implementations use the time zone information of the IANA Time Zone Database.

1.5.14 UnwrapDateTimeFormat ( dtf )

The UnwrapDateTimeFormat abstract operation returns the DateTimeFormat instance of its input object, which is either the value itself or a value associated with it by %DateTimeFormat% according to the normative optional constructor mode of .

  1. If Type(dtf) is not Object, throw a TypeError exception.
  2. If dtf does not have an [[InitializedDateTimeFormat]] internal slot and ? OrdinaryHasInstance(%DateTimeFormat%, dtf) is true, then
    1. Return ? Get(dtf, %Intl%.[[FallbackSymbol]]).
  3. Return dtf.