More precisely describe getTimezoneOffset()

files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html

@@ -10,28 +10,30 @@
 ---
 <div>{{JSRef}}</div>
 
-<p>The <strong><code>getTimezoneOffset()</code></strong> method returns the time-zone difference, in minutes, between UTC time and local time.</p>
+<p>The <strong><code>getTimezoneOffset()</code></strong> method returns the difference, in minutes, between a date as evaluated in the UTC time zone, and the same date as evaluated in the local time zone.</p>
 
 <div>{{EmbedInteractiveExample("pages/js/date-gettimezoneoffset.html")}}</div>
 
 <h2 id="Syntax">Syntax</h2>
 
-<pre class="syntaxbox notranslate"><var>dateObj</var>.getTimezoneOffset()</pre>
+<pre class="syntaxbox notranslate"><var>date</var>.getTimezoneOffset()</pre>
 
 <h3 id="Return_value">Return value</h3>
 
-<p>A number representing the time-zone offset, in minutes, between UTC and local time.</p>
+<p>The difference, in minutes, between <var>date</var>, as evaluated in the UTC time zone, and as evaluated in the local time zone.</p>
 
 <h2 id="Description">Description</h2>
 
-<p>The time-zone offset is the difference, in minutes, between UTC time and local time.</p>
+<p><code><var>date</var>.getTimezoneOffset()</code> returns the difference, in minutes, between <var>date</var> as evaluated in the UTC time zone, and <var>date</var> as evaluated in the local time zone.</p>
 
-<p>Note that this means that the offset is positive if the local time zone is behind UTC, and negative if the local time zone is ahead of UTC. For example, for time zone UTC+10:00 (Australian Eastern Standard Time, Vladivostok Time, Chamorro Standard Time), <code>-600</code> will be returned.</p>
+<h3>Negative values and positive values</h3>
+
+<p>The number of minutes returned by <code>getTimezoneOffset()</code> is positive if the local time zone is behind UTC, and negative if the local time zone is ahead of UTC. For example, for UTC+10, <code>-600</code> will be returned.</li>
 
 <table class="standard-table">
  <thead>
   <tr>
-   <th scope="row">Current Locale</th>
+   <th scope="row">Current time zone</th>
    <th scope="col">UTC-8</th>
    <th scope="col">UTC</th>
    <th scope="col">UTC+3</th>
@@ -47,14 +49,24 @@ <h2 id="Description">Description</h2>
  </tbody>
 </table>
 
+<h3>Varied results in Daylight Saving Time (DST) time zones</h3>
+
+<p>In a time zone that annually shifts in and out of Daylight Saving Time (DST), the number of minutes returned by calling <code>getTimezoneOffset()</code> can vary.</p>
+<p>Consider a given local time zone and a date <var>date1</var> that are both in DST, and consider <var>minutes</var>, the number of minutes returned by calling <code><var>date1</var>.getTimezoneOffset()</code>; then:</li>
+
+<ul>
+ <li>If the local time zone is currently in DST, but a given date <var>date2</var> is <em>not</em> in DST, then the number of minutes returned by <code><var>date2</var>.getTimezoneOffset()</code> is <var>minutes</var> ± 60.</li>
+ <li>If the local time zone is <em>not</em> currently in DST, but <var>date3</var> is in DST, then the number of minutes returned by <code><var>date3</var>.getTimezoneOffset()</code> is <var>minutes</var> ± 60.</li>
+</ul>
+
+<p>In a time zone that doesn’t annually shift in and out of Daylight Saving Time (DST), the number of minutes returned by calling <code>getTimezoneOffset()</code> always returns the same number of minutes, regardless of the <var>date</var> instance it’s called from.</p>
+
 <div class="notecard note">
-<p>{{jsxref("Date")}} instances do not store a time zone — instead they just store a single value representing the number of milliseconds that have elapsed since midnight on January 1, 1970, UTC — so regardless of what {{jsxref("Date")}} instance the <code>getTimezoneOffset()</code> method is called from, the result isn’t calculated based on the value of the particular {{jsxref("Date")}} instance, but is instead always just the difference between UTC time and local time.</p>
+ <p><strong>Note:</strong> The above description is a simplification. In implementations, the {{InterWiki("wikipedia", "Daylight_saving_time#IANA_time_zone_database", "IANA time zone database")}} (tzdata) is used for precisely determining the effect of DST on the calculation of the time-zone difference.</p>
 </div>
 
 <h2 id="Examples">Examples</h2>
 
-<h3 id="Using_getTimezoneOffset">Using getTimezoneOffset()</h3>
-
 <pre class="brush: js notranslate">// Create a Date instance for the current time
 let currentLocalDate = new Date();
 // Create a Date instance for 03:24 GMT-0200 on May 1st in 2016