See "About This JavaScript Site" in JavaScript Index and Introduction.
See "General Date/Time Introduction" in JavaScript Date and Time Introduction.
Any purely client-side code purporting to show time should be accompanied by a caveat about the displaying system's settings needing to be correct.
JavaScript directly provides date/time both as GMT/UTC and as local to the browser, by using information from the operating system. For reliable display of current time anywhere, the system must be set correctly for its location, for which the Time Rules held must be correct and current, and the machine must be set so that the civil date/time functions display the current local date/time sufficiently accurately.
Only on an intranet can an author safely assume anything about the executing browser's locality - on the World-Wide Web, it may be anywhere, and it may be set for any location.
I know of no way, in JavaScript, to access the Rules kept by the operating system for the offset from GMT for a remote location.
The user's local time offset, if required, should be handled separately, which is trivial.
The code must allow for the Standard Offset of the remote location, which is nominally -4 minutes per degree of East longitude of the heart of the region, and for the state and offset of its Summer Time, if any.
It is generally better to change the value of a Date object, rather than to adjust individual date/time fields and so need to consider fractions and carries. The Object is set such that the fields of its GMT can be shown as the remote civil date and time, to avoid problems with local time.
To obtain the local date/time at a given remote location, allowing for its Time Zone and Summer Time, various cases apply, dependent on the Summer Time Rules of the remote location :-
Reverse the argument. In general, set the remote time into an Object as if it were GMT, apply the correction to real GMT, and display as usual. The reverses of the above cases, or many of them, are provided below.
The getTimezoneOffset method of a Date Object returns (GMT-local time) in minutes, for that date and time at the locality set in the Operating System. But the method is not applicable in this page, which deals with Date and Time Elsewhere, and the information has to be supplied by other means.
The Standard (Winter) Offset is the more positive of the values for January 1st and July 1st, and the Summer Offset is the more negative. So, for a place which uses Summer Time, one can tell the hemisphere and the season from the two Offsets. For code, see OS Time Offset Settings.
Locations with Summer Time will change offset within Jan 1st to Jun 30th, and again within Jul 1st to Dec 31st. So, if the month is known as a number, one can determine whether it is in Jan-Jul or in Jul-Dec and then calculate the single change date within the range. I may change some of my code accordingly.
A general algorithm using a TZ-string or similar data may be chosen, or one specific to the location may be used. In the latter case, ten times out of twelve the month number is sufficient, and in the other months the date suffices about 75% of the time. For example, in the EU the month must be March or October and the date after the 24th for further work to be needed.
In a Web page, it is often appropriate to describe an event in local time (or GMT), for example 2013/05/07 19:00 BST or 05/07/14 19:15 EDT or 2015/06/08 21:00 +0530 or 2010/12/29 10:24 GMT-0330 or 1970-01-01 00:00 GMT, but helpful to be able to show the time as GMT and/or reader's Local Civil Time.
The code, provided in inc-modt.js, can be modified for display of alternative text - masses in lb/kg for example.
"At <span class=CBS>2013/01/21 12:00 EST</span> an event occurs."
"At 2013/01/21 12:00 EST, an event occurs."
Mouse-over the date to see event-local date/time, GMT date/time,
and your Local Civil date/Time for the event.
Each date/time is put in a span element which is given a particular class. A routine called by onload finds all elements of that class, colours them to suggest new behaviour, and sets their onmouseover onmouseout properties to functions. Those functions show and remove the corresponding local and GMT date/times.
The given date/time must be unambiguously readable as a string by JavaScript new Date(), in all browsers, except that BST is also supported and the usual ISO 8601 date separator (-) is accepted. Numeric month must (alas) precede day, unless code is added . MM/DD/YY is changed to MM/DD/20YY. Authors may choose to support their own local notation similarly.
The complete date/time must be present but need not now all be shown : 2012-06-0712:00 GMT and 2013-07-0819:00 BST. Here, the time or date part is in an internal, non-displayed, element.
The actual output display could be more ornate.
Fields shown are :-
• SRC : as stored in the page - event-local is best
• GMT : the true date/time of the event
• LCT : browser's Local Civil Time of the event
• TTG : Time To Go (days/hours/minutes, assumed positive?)
• AGO : replaces TTG, after the event
This shows another 2013/02/01 MST way.
The code for thse can probably be adapted for any specific place. They are not equally optimised, and may show different approaches. Code for a general choice of location is below.
The following should be directly effective for EU transition times, and was adaptable for NA :-
Firefox 2 & 3.0 show code new Date() in an unexpected manner.
Month = 10 - 7*SummerStarting // a boolean
For the NA 1987-2006 change : add the time zone shift in ms; and add 7*864e5+36e5 ms for Spring - I think. For the 2007- NA change, rewrite.
Users of Windows in the British Isles should normally select the "Dublin, Edinburgh, Lisbon, London" time zone setting, not the "Casablanca, Monrovia" one; those need no Summer Time.
For elsewhere in the EU, just include the standard offset.
All of China uses GMT+8.
Most of North America uses the same rules (at least for 1987-2006 and 2007-), based on local time; part of Canada changes at a different time, parts of NA do not change.
Function USTime(D, USZ) sets D to the GMT having the same numbers as clocks in most of US Time Zone USZ then show, and TestUST shows it for New York (USZ=-5) with utcDYMDHMSstr(), after showing intermediates as a check.
This is similar to the case for China, which in effect has permanent Winter.
For the user's local standard time, use GMT corrected by the offset for a Winter date, remembering that Winter can include July in lieu of January. To determine the local standard (Winter) offset, see 2 : Demonstrations.
Reverse the argument. In general, set the remote time into an Object as if it were GMT, apply the correction to real GMT using the given remote rules, and display as usual.
Once the GMT is known, getting the local version is standard.
That needs testing (slightly) away from London Time.
To adapt to accept other Remote Times, alter variable SO and use the change rules for Remote.
For any location implementing the included US DST rules (locally optional but immutable; may change federally), insert the Winter Offset from GMT, in hours ; Examples :- Miami -5, Chicago -6, Denver -7, Seattle -8, Anchorage -9.
That needs US testing. Parts of Canada may have different change times.
To read a Remote Standard Date/Time String, use new Date(Str+" UTC") then remove the fixed Winter offset.
The Time Zone and Summer Time rules for a general (remote) location can be defined by a UNIX-style TZ String (h, t), and used for conversion in either direction between a Date Object and the Remote Civil Date/Time.
The local TZ string can be in part determined by code; see Generate a User TZ String.
Given a Date Object and a Remote TZ string, the corresponding Remote Civil Date/Time can be derived, without any ambiguity.
Given a Remote Civil Date/Time and an appropriate TZ string, the corresponding Date Object can be derived. There will be an ambiguous hour in Autumn, unless the Time Desigation, e.g. BST, is used.
That date/time should be supplied as a string, preferably in YMD hms order.
The code uses functions from inc-cmmn.js and inc-date.js - see Include Files.
The code is moderately tested and partly polished.
Major functions (parameters are not modified) :-
The input Remote Civil Date/Time String for RStoUT(DTstr, TZObj) has no Time Designator. The string must, with ' UTC' appended, be readable by new Date() after possible - to / substitution.
The input Remote Civil Date/Time String for RTtoUT(DTstr, TZstr) has a Time Designator. The string must, with the Designator replaced by ' UTC', be readable by new Date() after possible - to / substitution. Only the first part of the string TZstr is needed, to interpret the Designator.
Parts of the functions DOtoRT, RStoUT can be omitted if the Details are not needed; or the functions can be encapsulated - see function Encap(Cvtr, Inp, TZ) below.
The code used here can be driven from a seconds-locked timer. To optimise that case, the TZ string is only re-parsed on change, though the transition moments will need to be calculated at least for each year. (Those moments are not yet cached; they would be needed in both GMT and local, differently.)
At present, for test, the Run button causes the date/time to repeatedly use Set_Now() and Convert() but it could go directly into DOtoRT() as for the Now button.
In the TZ string, only a subset of the "M" format is allowed; and seconds fields are not supported. Years before 1970 may not be supported. There is no default location. Parsing is slightly liberal.
Ignore spaces :-
UNIX TZ syntax is: std offset[dst[offset][,start[/time],end[/time]]]
here implemented: std offset[dst[offset] ,start /time ,end /time ]
with no default change times. The times are 24-hour
h:m and the offsets are [±]h[:m]
(- is East, + is West, of Greenwich).
Caveat : On contrasting two man pages, I have seen excusable uncertainty as to whether the second, optional, Summer Time offset is from GMT or from Winter Time. The code used below correctly implements the former.
The default change, one hour, is however indisputably correct. Use that, as in the "eur" selection below, if possible. I recall no places where the change is by other than one hour, apart from Lord Howe Island.
The possibilities of a clock change on New Year's Eve/Day, and of two changes in one month, have been scorned in writing the code.
TZ selector entries are for test only; they may not represent actual current rules. Please report applicable corrections. Clock Change Dates and Rules for most* locations can be found on the Web; my Summer Time Links may help.
"TZ string" and some other text fields can be edited, for use lower down. That by "Set Now" must use numeric Y M D h m s order, 24-h, arbitrary separators. That by "Remote Time", read by "GMT", is free-format, without a Designator, which goes in the next field.
Where there is no Summer Time, some fields show "undefined".
* Israel prefers chaos. Lord Howe Island OK.
The "ny06" entry, if present, uses 1987-2006 DST rules. The "ny07" entry uses 2007+ DST rules.
I now have a Delphi version of the above, in ZIP.
Main conversion code : Common, To Remote, From Remote 1 & 2 :-
The test date/times are for UK, 2003, current rules; but similar results are expected for other locations.
The second column is derived from the first. The third and fourth columns are derived from the second, respectively with and without use of its Designator field; they are checked against the first.
N.B. : Inevitably, there is an error, marked X, in the fourth column of the lline starting '2003-10-26 01:30:00', for one instance of the duplicated Civil Date/Time.
For specific locations, using the three general functions that drive the above Form :-
That shows conversions both from and to a normal Date Object.
The Seattle entry currently uses 2007+ DST rules.
The data box is editable; there is no specific protection against error. The demonstration TZ strings are not guaranteed to be correct. Line contents are name, whitespace, TZ string (# space ... for comment line). The Vancouver entry uses 2007+ US DST rules. Moscow changed in mid-2011.
The current civil date and time, if your computer clock is correct, are :-
?
That shows only conversions from a normal Date Object to Remote Civil Time. The 300 ms delay allows page loading to complete. For seconds timing, see in 0 : Date Object Information.
This sets the UTC of a copy of the Object to the corresponding local date/time of a zone selected by abbreviation or offset; the UTC methods can then be used to display that date/time. It does not otherwise consider Summer Time.
The process can readily be reversed.
Set both TZ strings, by direct entry or by using the select and arrow buttons, set a TZ 1 local civil time in LCT 1, and press Transfer. To empty a TZ field, select "?".
There is no specific provision for handling the ambiguous Autumn period. Within it, Summer Time is assumed.
Button Add TZ appends an option to the drop-down lists, and button Sub TZ removes the last option.