© J R Stockton, ≥ 2012-09-30

JavaScript Date and Time Introduction.

Links within this site :-

See "About This JavaScript Site" in JavaScript Index and Introduction.

General Date/Time 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.

JavaScript on this site was originally written for systems more-or-less using
ECMAScript 3rd Edition.
ECMAScript 4th Edition will not exist.
ECMAScript 5th Edition is somewhat different.
NOTE on JScript

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.

NOTE on Strings

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.

NOTE on Documentation

Documentation often fails to say clearly :-

About these Date and Time Pages

These Date and Time Pages show some of what can be done with, and without, the power of JavaScript Date Objects.

Use 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

'File inc-cmmn.js top fault, RSVP!'

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).

UTC, GMT, and UT

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

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.

Overview of Date Objects

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.

Because the native Date Object is not entirely satisfactory, I have developed an alternative Object, DATE2.

[§] Resolutions of new Date()

The constructor new Date() reads date and time (converted to milliseconds from 1970.0 GMT) from the client clock system.

D = new Date()
Hardware Operating
Browser Updating
MacOS X Safari1.51
OS 9IE2.11
PC Linux
Win2kPro Firefox15.6251
Tick Count :  
# : My IE6, IE7, FF2, Sf3, and Op9
@ : My FF3, Op10, and Ch0.2
Set Tick Count; select Test. Times are in milliseconds
Test several times & take the lowest

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.

Your Settings

To check your system's geographical date/time settings :-

To check your system's date/time format settings :-

My JavaScript Date/Time Code

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.

Boxes With Coloured Borders

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.

Viewing Code

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.

Developing and Testing Code

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.

Sorting by Date/Time

Moved to Sorting and Order.

Some Date Examples

Date and Time Now

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' :-

The Start of Today

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? :-

External Date Links


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.

PC Timing

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.

Other JavaScript Date and Time Pages
0 - Date Object Information
1 - Date Arithmetic
2 - Demonstrations
3 - Input and Lengths
4 - Validation
5 - Date and Time Elsewhere
6 - Date and Time Choosers
7 - Working with Weeks
8 - Enhancing the Object
9 - Output Formatting
X - Troubles
Home Page
Mail: no HTML
© Dr J R Stockton, near London, UK.
All Rights Reserved.
These pages are tested mainly with Firefox and W3's Tidy.
This site, , is maintained by me.