Difference between setUTCminutes versus setMinutes

Question

Is there any difference between the JavaScript date methods:

setUTCminutes()

versus

setMinutes()

Will using setMinutes() revert the time zone back to something other than UTC?

I'm contemplating whether to set the UTC time with a date string:

var dUTC = new Date('March 20, 2016 20:45:00 UTC');

or set the date, then set the hour, etc with UTC methods:

var d = new Date(2016,3,20);
d.setUTCHours(20);
d.setUTCminutes(45);

But, I'm concerned that the second method might not be accurate in some situations. I don't want to end up with the wrong UTC date. My Add-on could be used all over the world.

Answer 1

Is there any difference between the JavaScript date methods:

setUTCminutes() versus

setMinutes()

Yes. Set UTCMinutes will adjust the internal timevalue (which is UTC) based on the new UTC minutes value.

setMinutes does the same thing but will allow for the internal timezone, so the change in time might be different (since many time zones are not full hours).

e.g. for a timezone of UTC+0030, if the local time is 01:00 then setting the UTC minutes to 30 does nothing (since it's currently UTC 00:30) but setting the local minutes to 30 will set the UTC minutes to 00:00

Also, if the new minutes causes the date to across a daylight saving boundary, the new time minus the old time in UTC and local might be different.

Will using setMinutes() revert the time zone back to something other than UTC?

No. Date objects do not have a timezone, host systems do. Date objects use a UTC time value, then use the timezone of the host is used in calculations, it isn't a property of the Date itself (hence the method getTimezoneOffset).

I'm contemplating whether to set the UTC time with a date string:

var dUTC = new Date('March 20, 2016 20:45:00 UTC');

NO! Do not do that. Parsing strings with the Date constructor is strongly recommenced against (just search on the number of questions here about parsing). That date format is not one supported by ECMA-262 so parsing is entirely implementation dependent. The time zone might be reconized or not, or you might get an invalid date.

or set the date, then set the hour, etc with UTC methods:

var d = new Date(2016,20,3); 
d.setUTCHours(20);
d.setUTCminutes(45);

But, I'm concerned that the second method might not be accurate in some situations.

The values passed to the Date constructor do not seem correct, the values are year, month, day. Perhaps you meant:

new Date(2016, 3, 20)  // 20 April, 2016

When creating the date in the above, the host timezone will affect the values used to create the UTC time value. Using UTC methods to then set the time may well cause unexpected results, so don't to that.

If you want something that works everywhere, always use UTC then only convert to "local" for output. So if you want to create a date and time based on UTC:

var d = new Date(Date.UTC(2016, 3, 20, 20, 45);

will create a date for 2016-04-20T20:45:00Z

Answer 2

A Date instance is always, at heart, a UTC timestamp. The non-UTC APIs, like .toString(), .getHour(), .getMinute(), etc, all apply a translation based on the time zone of the environment in which the code runs. The non-UTC setters do the same thing.

So, in any locale, when you call new Date(), you get a Date instance that acts like it's appropriate for your local time zone, but internally it's a UTC timestamp.

If you want to explicitly make a Date instance from UTC parameters, you can use Date.UTC() to create a timestamp to pass to the Date constructor:

var utc = new Date(Date.UTC(2016, 1, 29, 19, 11, 45));

That makes a Date instance that would be the same as a Date instance constructed by a computer in London (it's not BST now) with:

var london = new Date(2016, 1, 29, 19, 11, 45);

because London time (when it's not summer) is the same as UTC time.