From 725d8bea117f2efb0d8ae82e4222bfbcd0c2cc7d Mon Sep 17 00:00:00 2001 From: "Michael[tm] Smith" Date: Mon, 4 Jan 2021 13:04:49 +0900 Subject: [PATCH 1/4] Correct the Date.p.getTimezoneOffset() doc Fixes https://github.com/mdn/content/issues/665 --- .../date/gettimezoneoffset/index.html | 30 ++++++++----------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html b/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html index 2cec46a1e88983e..14e5f43e3387f4c 100644 --- a/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html +++ b/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html @@ -10,7 +10,7 @@ ---
{{JSRef}}
-

The getTimezoneOffset() method returns the time zone difference, in minutes, from current locale (host system settings) to UTC.

+

The getTimezoneOffset() method returns the time-zone difference, in minutes, between UTC time and local time.

{{EmbedInteractiveExample("pages/js/date-gettimezoneoffset.html")}}
@@ -20,13 +20,13 @@

Syntax

Return value

-

A number representing the time-zone offset, in minutes, from the date based on current host system settings to UTC.

+

A number representing the time-zone offset, in minutes, between UTC and local time.

Description

-

The time-zone offset is the difference, in minutes, from local time to UTC.

+

The time-zone offset is the difference, in minutes, between UTC time and local time.

-

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), -600 will be returned.

+

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), -600 will be returned.

@@ -47,24 +47,20 @@

Description

-

The time zone offset returned is the one that applies for the Date that it's called on.

- -

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.

+
+

{{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 getTimezoneOffset() 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.

+

Examples

Using getTimezoneOffset()

-
// Get current timezone offset for host device
-let x = new Date();
-let currentTimeZoneOffsetInHours = x.getTimezoneOffset() / 60;
-// 1
-
-// Get timezone offset for International Labour Day (May 1) in 2016
-// Be careful, the Date() constructor uses 0-indexed months, so May is
-// represented with 4 (and not 5)
-let labourDay = new Date(2016, 4, 1)
-let labourDayOffset = labourDay.getTimezoneOffset() / 60;
+
// 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();
+// true, always — regardless of the values of the Date instances
 

 
 
Specifications


From 02b779a1956f04a54d35e5dd41809b2069e7b470 Mon Sep 17 00:00:00 2001
From: "Michael[tm] Smith" 
Date: Thu, 7 Jan 2021 23:02:03 +0900
Subject: [PATCH 2/4] More precisely describe getTimezoneOffset()

---
 .../date/gettimezoneoffset/index.html         | 30 +++++++++++++------
 1 file changed, 21 insertions(+), 9 deletions(-)

diff --git a/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html b/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html
index 14e5f43e3387f4c..ec7f204ce6e899c 100644
--- a/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html
@@ -10,28 +10,30 @@
 ---
 
{{JSRef}}

 
-
The getTimezoneOffset() method returns the time-zone difference, in minutes, between UTC time and local time.

+
The getTimezoneOffset() 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.

 
 
{{EmbedInteractiveExample("pages/js/date-gettimezoneoffset.html")}}

 
 
Syntax

 
-
dateObj.getTimezoneOffset()

+
date.getTimezoneOffset()

 
 
Return value

 
-
A number representing the time-zone offset, in minutes, between UTC and local time.

+
The difference, in minutes, between date, as evaluated in the UTC time zone, and as evaluated in the local time zone.

 
 
Description

 
-
The time-zone offset is the difference, in minutes, between UTC time and local time.

+
date.getTimezoneOffset() returns the difference, in minutes, between date as evaluated in the UTC time zone, and date as evaluated in the local time zone.

 
-
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), -600 will be returned.

+
Negative values and positive values

+
+
The number of minutes returned by getTimezoneOffset() 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, -600 will be returned.
 
 
-   
+   
@@ -47,14 +49,24 @@ 
Description

  
   
Current LocaleCurrent time zone
    UTC-8
    UTC
    UTC+3
  
 

 
+
Varied results in Daylight Saving Time (DST) time zones

+
+
In a time zone that annually shifts in and out of Daylight Saving Time (DST), the number of minutes returned by calling getTimezoneOffset() can vary.

+
Consider a given local time zone and a date date1 that are both in DST, and consider minutes, the number of minutes returned by calling date1.getTimezoneOffset(); then:
+
+
    
+ 
  • If the local time zone is currently in DST, but a given date date2 is not in DST, then the number of minutes returned by date2.getTimezoneOffset() is minutes ± 60.
    • 
+ 
  • If the local time zone is not currently in DST, but a given date date3 is in DST, then the number of minutes returned by date3.getTimezoneOffset() is minutes ± 60.
    • 
+

+
+
In a time zone that doesn’t annually shift in and out of Daylight Saving Time (DST), the number of minutes returned by calling getTimezoneOffset() always returns the same number of minutes, regardless of the date instance it’s called from.

+
 

-
{{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 getTimezoneOffset() 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.

+ 
Note: 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.

 

 
 
Examples

 
-
Using getTimezoneOffset()

-
 
// 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

From 22746499829682429269dbeb2c96c1b55e04c6c0 Mon Sep 17 00:00:00 2001
From: "Michael[tm] Smith" 
Date: Tue, 16 Mar 2021 16:28:10 +0900
Subject: [PATCH 3/4] Clarify what "local time zone" means

---
 .../reference/global_objects/date/gettimezoneoffset/index.html  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html b/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html
index ec7f204ce6e899c..245375f487f97fa 100644
--- a/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html
@@ -24,7 +24,7 @@ 
Return value

 
 
Description

 
-
date.getTimezoneOffset() returns the difference, in minutes, between date as evaluated in the UTC time zone, and date as evaluated in the local time zone.

+
date.getTimezoneOffset() returns the difference, in minutes, between date as evaluated in the UTC time zone, and date 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.

 
 
Negative values and positive values

 

From 36aff18946e261a5966bcad75d26fa98ab3e58b5 Mon Sep 17 00:00:00 2001
From: "Michael[tm] Smith" 
Date: Tue, 16 Mar 2021 16:42:59 +0900
Subject: [PATCH 4/4] Update code comment to clarify effect of DST

---
 .../reference/global_objects/date/gettimezoneoffset/index.html | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html b/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html
index c17a2bbbbcbbf04..a1aefe68ccae273 100644
--- a/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html
@@ -72,7 +72,8 @@ 
Examples

 // 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();
-// true, always — regardless of the values of the Date instances
+// 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
 

 
 
Specifications