Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Correct the Date.p.getTimezoneOffset() doc #893

Merged
merged 5 commits into from
Mar 16, 2021
Merged

Correct the Date.p.getTimezoneOffset() doc #893

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
725d8be
Correct the Date.p.getTimezoneOffset() doc
sideshowbarker Jan 4, 2021
02b779a
More precisely describe getTimezoneOffset()
sideshowbarker Jan 7, 2021
2274649
Clarify what "local time zone" means
sideshowbarker Mar 16, 2021
093f282
Merge branch 'main' into sideshowbarker/getTimezoneOffset-corrections
sideshowbarker Mar 16, 2021
36aff18
Update code comment to clarify effect of DST
sideshowbarker Mar 16, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 43 additions & 41 deletions files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,68 +10,70 @@
---
<div>{{JSRef}}</div>

<p>The <strong><code>getTimezoneOffset()</code></strong> method returns the time zone
difference, in minutes, from current locale (host system settings) to UTC.</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="brush: js"><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, from the date based on current
host system settings to UTC.</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, from local time to UTC.</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 — that is, the time zone of the host system in which the browser is being used (if the code is run from the Web in a browser), or otherwise the host system of whatever JavaScript runtime (for example, a Node.js environment) the code is executed in.</p>

<p>Note that this means that the offset is positive if the local timezone is behind UTC,
and negative if it is ahead. 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="col">UTC-8</th>
<th scope="col">UTC</th>
<th scope="col">UTC+3</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">Return Value</th>
<td>480</td>
<td>0</td>
<td>-180</td>
</tr>
</tbody>
<thead>
<tr>
<th scope="row">Current time zone</th>
<th scope="col">UTC-8</th>
<th scope="col">UTC</th>
<th scope="col">UTC+3</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">Return Value</th>
<td>480</td>
<td>0</td>
<td>-180</td>
</tr>
</tbody>
</table>

<p>The time zone offset returned is the one that applies for the Date that it's called on.
</p>
<h3>Varied results in Daylight Saving Time (DST) time zones</h3>

<p>If the host system is configured for daylight saving, the offset will change depending
on the date and time that the Date represents and that daylight saving applies.</p>
<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>

<h2 id="Examples">Examples</h2>
<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 a given date <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>

<h3 id="Using_getTimezoneOffset">Using getTimezoneOffset()</h3>
<div class="notecard note">
Elchi3 marked this conversation as resolved.
Show resolved Hide resolved
<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>

<pre class="brush: js">// Get current timezone offset for host device
let x = new Date();
let currentTimeZoneOffsetInHours = x.getTimezoneOffset() / 60;
// 1
<h2 id="Examples">Examples</h2>

// Get timezone offset for International Labor Day (May 1) in 2016
// Be careful, the Date() constructor uses 0-indexed months, so May is
// represented with 4 (and not 5)
let laborDay = new Date(2016, 4, 1)
let laborDayOffset = laborDay.getTimezoneOffset() / 60;
<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
let laborDay2016at0324GMTminus2 = new Date('May 1, 2016 03:24:00 GMT-0200');
currentLocalDate.getTimezoneOffset() === laborDay2016at0324GMTminus2.getTimezoneOffset();
Elchi3 marked this conversation as resolved.
Show resolved Hide resolved
// true, always, in any timezone that doesn't annually shift in and out of DST
// false, sometimes, in any timezone that annually shifts in and out of DST
</pre>

<h2 id="Specifications">Specifications</h2>
Expand Down