Revision 375191 of Intl.DateTimeFormat

<h2 id="Summary">Summary</h2>
<p>The <code>Intl.DateTimeFormat</code> object is a constructor for objects that enable language sensitive date and time formatting.</p>
<table class="standard-table">
  <thead>
    <tr>
      <th class="header" colspan="2">Property of <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Intl" title="JavaScript/Reference/Global_Objects/Intl"><code>Intl</code></a></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>ECMAScript Edition</td>
      <td>ECMAScript Internationalization API Specification, 1<sup>st</sup> Edition</td>
    </tr>
  </tbody>
</table>
<h2 id="Syntax">Syntax</h2>
<pre class="syntaxbox">
new Intl.DateTimeFormat([<em>locales</em> [, <em>options</em>]])

Intl.DateTimeFormat.call(<em>this</em> [, <em>locales</em> [, <em>options</em>]])</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
  <dt>
    <code>locales</code></dt>
  <dd>
    <p>A string with a BCP 47 language tag, or an array of such strings. For the general form and interpretation of the <code>locales</code> argument, see the <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Intl#Functionality_common_to_internationalization_constructors" title="/Intl#Functionality_common_to_internationalization_constructors">Intl page</a>. The following Unicode extension keys are allowed:</p>
    <dl>
      <dt>
        nu</dt>
      <dd>
        Numbering system. Possible values include: "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".</dd>
      <dt>
        ca</dt>
      <dd>
        Calendar. Possible values include: "buddhist", "chinese", "coptic", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamicc", "iso8601", "japanese", "persian", "roc".</dd>
    </dl>
  </dd>
  <dt>
    <code>options</code></dt>
  <dd>
    <p>An object with some or all of the following properties:</p>
    <dl>
      <dt>
        <code>localeMatcher</code></dt>
      <dd>
        The locale matching algorithm to use. Possible values are "lookup" and "best fit"; the default is "best fit". For information about this option, see the <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation" title="/en-US/docs/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation">Intl page</a>.</dd>
      <dt>
        <code>timeZone</code></dt>
      <dd>
        The time zone to use. The only value implementations must recognize is "UTC"; the default is the runtime's default time zone. Implementations may also recognize the time zone names of the <a href="https://www.iana.org/time-zones" title="https://www.iana.org/time-zones">IANA time zone database</a>, such as "Asia/Shanghai", "Asia/Kolkata", "America/New_York".</dd>
      <dt>
        <code>hour12</code></dt>
      <dd>
        Whether to use 12-hour time (as opposed to 24-hour time). Possible values are <code>true</code> and <code>false</code>; the default is locale dependent.</dd>
      <dt>
        <code>formatMatcher</code></dt>
      <dd>
        The format matching algorithm to use. Possible values are "basic" and "best fit"; the default is "best fit". See the following paragraphs for information about the use of this property.</dd>
    </dl>
    <p>The following properties describe the date-time components to use in formatted output, and their desired representations.&nbsp; Implementations are required to support at least the following subsets:</p>
    <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>
    <p>Implementations may support other subsets, and requests will be negotiated against all available subset-representation combinations to find the best match. Two algorithms are available for this negotiation and selected by the <code>formatMatcher</code> property: A <a href="https://www.ecma-international.org/ecma-402/1.0/#BasicFormatMatcher" title="https://www.ecma-international.org/ecma-402/1.0/#BasicFormatMatcher">fully specified "basic" algorithm</a> and an implementation dependent "best fit" algorithm.</p>
    <dl>
      <dt>
        <code>weekday</code></dt>
      <dd>
        The representation of the weekday. Possible values are "narrow", "short", "long".</dd>
      <dt>
        <code>era</code></dt>
      <dd>
        The representation of the era. Possible values are "narrow", "short", "long".</dd>
      <dt>
        <code>year</code></dt>
      <dd>
        The representation of the year. Possible values are "numeric", "2-digit".</dd>
      <dt>
        <code>month</code></dt>
      <dd>
        The representation of the month. Possible values are "numeric", "2-digit", "narrow", "short", "long".</dd>
      <dt>
        <code>day</code></dt>
      <dd>
        The representation of the day. Possible values are "numeric", "2-digit".</dd>
      <dt>
        <code>hour</code></dt>
      <dd>
        The representation of the hour. Possible values are "numeric", "2-digit".</dd>
      <dt>
        <code>minute</code></dt>
      <dd>
        The representation of the minute. Possible values are "numeric", "2-digit".</dd>
      <dt>
        <code>second</code></dt>
      <dd>
        The representation of the second. Possible values are "numeric", "2-digit".</dd>
      <dt>
        <code>timeZoneName</code></dt>
      <dd>
        The representation of the time zone name. Possible values are "short", "long".</dd>
    </dl>
    <p class="noinclude">The default value for each date-time component property is <code>undefined</code>, but if all component properties are <code>undefined</code>, then <code>year</code>, <code>month</code>, and <code>day</code> are assumed to be "numeric".</p>
  </dd>
</dl>
<h2 id="Description" name="Description">Description</h2>
<h3 id="Properties" name="Properties">Properties</h3>
<p>{{Js_see_prototype("DateTimeFormat", "Properties")}}</p>
<dl>
  <dt>
    <a href="/en-US/docs/JavaScript/Reference/Global_Objects/DateTimeFormat/prototype" title="JavaScript/Reference/Global_Objects/DateTimeFormat/prototype">prototype</a></dt>
  <dd>
    Allows the addition of properties to all objects.</dd>
</dl>
<p>{{jsOverrides("Function", "Properties", "prototype")}}</p>
<h3 id="Methods">Methods</h3>
<p>{{Js_see_prototype("DateTimeFormat", "Methods")}}</p>
<dl>
  <dt>
    <a href="/en-US/docs/JavaScript/Reference/Global_Objects/DateTimeFormat/supportedLocalesOf" title="JavaScript/Reference/Global_Objects/DateTimeFormat/supportedLocalesOf">supportedLocalesOf</a></dt>
  <dd>
    Returns an array containing those of the provided locales that are supported without having to fall back to the runtime's default locale.</dd>
</dl>
<p>{{jsOverrides("Function", "Methods")}}</p>
<h2 id="DateTimeFormat_instances"><code>DateTimeFormat</code> instances</h2>
<h3 id="Properties">Properties</h3>
<p><code>DateTimeFormat</code> instances inherit the following properties from their prototype:</p>
<div>
  {{page('en-US/docs/JavaScript/Reference/Global_Objects/DateTimeFormat/prototype','Properties')}}</div>
<h3 id="Methods">Methods</h3>
<div>
  <p><code>DateTimeFormat</code> instances inherit the following methods from their prototype:</p>
  {{page('en-US/docs/JavaScript/Reference/Global_Objects/DateTimeFormat/prototype','Methods')}}</div>
<h2 id="Examples">Examples</h2>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<div>
  {{page('en-US/docs/JavaScript/Reference/Global_Objects/Intl','Browser_Compatibility')}}</div>