See "About This JavaScript Site" in JavaScript Index and Introduction.
This set of pages is not a JScript or JavaScript Date FAQ (Frequently Asked/Answered Questions list) as such, since it attempts to answer or to pre-empt - directly, indirectly, or by implication - all relevant questions.
Readers are expected, however, to have referred to standard JavaScript documentation, especially the Date Object parts.
Parts of my Pascal and Delphi pages can be applied in other languages, such as JavaScript.
General JavaScript date functions are coded in inc-date.js; that and inc-cmmn.js are used in this page. They are shown at Include Files.
JScript is Microsoft's version of JavaScript. Extra features are available when using JScript - but, for the Web, some may better be described as bugs.
For IE-only intranets, and for execution under WSH, JScript coding can be used.
JScript coding should not be used for the World-Wide Web, where only that which complies with ECMA-262 and ISO/IEC 16262 is safe.
For example, some JScript (and MS IE 6) date formatting changes nature outside AD 1601-9999.
Given American quaintnesses, avoidance of standards and addition of features, and noting the prevalence of use of IE for Web access, it's probably wise in particular to limit the use of browsers' Date Object Methods for conversion to/from String, especially for wide-ranging dates. Instead, use explicit code to convert dates to/from numbers and numbers to/from strings.
On the Web, dates should be displayed unambiguously. The only suitable numeric formats are those compatible with ISO 8601, with the Y M & D fields in that order.
Eschew both FFF and the 12-hour clock.
Documentation often fails to say clearly :-
These Date and Time Pages show some of what can be done with, and without, the power of JavaScript Date Objects.
In these pages, reference to the JavaScript date functions could be removed entirely (except for determining "Now" and "Today", and the client's GMT offsets), by replacing them with more predictable and controllable code derived from my dateprox.pas; however, whether or not used correctly, the JavaScript Date object is powerful.
On the other hand, some parts use (for compatibility with previous Pascal work) Chronological MJD for the day count (mainly Calendars and Clocks); and, if used in isolation, could be converted to rely more on Date objects.
General functions are coded in inc-cmmn.js, and general date functions in inc-date.js. Without these, pages will fail; there is a test at the head of each affected page for the complete presence of these files. Thus, after seeing an alert such as
one should expect further errors. The include files need to be in the same directory as the page file proper.
Several routines on these pages use or have used internal array literal constants, in various forms, e.g. for month-lengths. For some browsers, including MS IE4, it is appreciably more efficient to use a global variable for that.
Where, in these pages, a function is used to set such a global variable, the purpose of using a function is to enable displaying by ShoDoo (in a red border).
The term UTC properly refers to time using SI seconds, including Leap Seconds which computers generally do not implement. GMT is a well-known term for ordinary British winter time; BST is used for British Summer Time. Technically, GMT is now deprecated in favour of the term UT (Universal Time); but it remains the basis of British legal time.
In practice, JavaScript treats GMT and UTC as synonymous; but only UTC should be used in the names of Date Object methods.
The term UT is not commonly known, and might be taken as a typo meaning UTC.
Therefore, I tend to use the term GMT in the text of these JavaScript pages, rather than UTC. This has the advantage that a search for UTC finds mainly code, and one for GMT finds mainly text, strings, and comment.
JavaScript should not see Leap Seconds, according to ECMA-262, 3rd Edn, Sec 15.9.1.1.
As might be expected, the UTC routines are generally faster than the Local Civil Time (LCT) ones. Also, they correspond in behaviour to the common notion of LCT, disregarding clock offset changes. They should be used wherever true time is not needed.
JavaScript is Object-based; in particular, it can generate and display Date Objects.
An ECMA-262 Date Object holds a date/time, internally kept as milliseconds from Thursday 1970-01-01 00:00:00 GMT of the Gregorian Calendar; leap seconds should be ignored (GMT & UTC are taken as equivalent); the supported range is ±1E8 days.
Its value can be set, adjusted, and output in many ways, with methods for both GMT/UTC and local time (which often has steps in Spring and Autumn). For the difference between GMT and local time, it relies on system settings. Simple examples :-
D = new Date() // D is a new DOb at current time [§]
D = new Date(1234567890*1000) // " at that in ms GMT
D = new Date(2000, 1, 29) // " 29 FEB 2000 0h local
D = new Date("29 Feb 1900 UTC") // " 01 MAR 1900 0h GMT
D.setHours(D.getHours()+9) // D to 9 hours later, absolute time
D.setDate(D.getDate()+33) // D to 33 days later, local time
S = D.toString() // String S is local d/t of D somehow
S = new Date().toUTCString() // String S is present GMT d/t somehow
X = D.getTimezoneOffset() // D (GMT-local), minutes: UK: 0 / -60
T = +D // T now milliseconds from 1970.0 GMT
Two-digit years are read as being in 1900-1999; months are 0..11 as Numbers, but are 1..12 in Strings; getTime() returns milliseconds from 1970.0 GMT; formats may be foreign; there are many pitfalls, including browser-dependence.
The constructor new Date() reads date and time (converted to milliseconds from 1970.0 GMT) from the client clock system.
IMPORTANT - see links at PC Links Reference - PC Timing.
Update interval and numeric resolution are system-dependent, often 10 ms, 15.625 ms (1/64 s) or 54.925 ms (24 h / 0x1800B0). The update resolution presumably applies to other timing; see in JavaScript Date and Time 0 : Date Object Information.
Results for your system, measured by the code above, will appear, on yellow, in the table. Note that the Interval measurement may be interrupted by other processes, so should be repeated.
Thanks to RobG et al for table entries. Further input would be added, if convincing.
I think I've read evidence for 1 ms in IE6/Win2K. And a hint of 15.625 ms in dual-processor Windows. Mac systems give under 10 ms.
To check your system's geographical date/time settings :-
To check your system's date/time format settings :-
I have generally tried to find optimal or near-optimal approaches; but, where essentially the same operation is needed more than once, I may have used more than one way. That could be useful if parts of the code are not compatible with all browsers. Repeated function evaluations are not necessarily minimised. Script optimisation may well be capable of improvement; the algorithms should be more useful than the actual code.
Most of this site was written in Win98 1st Edn IE4, but sometimes checked in later browsers. I now mainly use WinXP sp3 and Firefox 3.0.
Code here should be valid for all years of the Gregorian Calendar within the JavaScript range, except as noted; but be careful with two-digit years and dates before AD 100. For the Julian Calendar, try in 8 : Enhancing the Object.
These pages themselves are copyright, including the Tables; but the JavaScript functions and algorithms may be freely reused.
See "Code Display on This Site" in Index and Introduction. For convenience of display, most code is written in functions.
In MSIE, the boxes show the code as written, with layout and comment; other browsers vary.
To see the actual code : in MSIE, use "View, Source" or "File, Save As"; similarly in other browsers ...
For routines not in the code of the current page, see Include Files, and the code of Calendars and Clocks, inc-cmmn.js, inc-date.js, etc. For Leading Zeroes, see also in JavaScript Maths.
The JavaScript in these pages was partly developed with MSIE 4 in Win 98. I have heard that an earlier version worked with Lynx Viewer.
I lost MSIE 4 on 2006-10-14, and started with Windows XP and MSIE 6 here on 2006-10-19. Now I have MSIE 8, Firefox 18.0.1, Opera 12.12, Safari 5.1.7, and Chrome 24.0, in XP sp3 (all: or later). I also have a less-used 64-bit Windows 7 system, with MSIE 9, and with a 32-bit XP subsystem.
Server-dependent aspects will have been tested by me only locally and on the Demon Homepages Web server. In cases such as lastModified it could be useful to hear of results obtained when using the same code with other servers.
Please let me know of any JavaScript browsers in which this code is not correct (indicating the exact nature of the error, and any ideas for its solution).
I largely rely for some things on reports from others - any effects of other browsers, of different Time Zone, of different Summer Time, etc.; I cannot readily test some things to the full, because GMT and my local (UK) Winter Time are the same.
In script, "////" may indicate debugging code.
Moved to Sorting and Order.
Displaying the local date and time in an ordinary form is generally pointless, except as a pedagogical exercise, since (a) the user may already know it, (b) the user may not want to know it, (c) most computers can display it in enough ways already. Some of these use inc-date.js.
Provided that your clock, browser, and settings are correct, calling :-
This may be simplest (but the format may be long or confusing) :-
This is unsafe, possibly giving such as 'Nov 5' or 'Jun 2007' (a browser might follow OS settings) :-
This should safely give such as 'Nov 05' :-
These are for local time, and create a Date Object :-
The changes to the above for GMT should be obvious. The last method assumes 24-h time format.
Is the Date Object D not before the Start of Today? :-
Netscape's JavaScript reference : Contents; the Date object. Very useful. Check for later versions. Perhaps via the Wayback Machine.
Java Date und Calendar - Interesting, but note the languages.
Also see the links in JavaScript Index & Introduction.
Read :-
See, of course, Claus Tøndering's Calendar FAQ and the news:sci.astro FAQ : [sci.astro] Time (Astronomy Frequently Asked Questions) (3/9); note also my general date and time pages, linked above.
For Net-specific information, see RFC 2518, 2616 at least.