logo To Foot
© J R Stockton, ≥ 2009-11-23

JavaScript Date and Time 8 :
Enhancing the Object

No-Frame * Framed Index * Frame This
Links within this site :-

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

See "General Date/Time Introduction" in JavaScript Date and Time Introduction.

All of this code was written presuming that new Date(Y,M,D) would always set 0h local of the date. For Opera, see Opera Summer Time. Fixed between 9.61 & 9.64

Addition of Methods

As for any other type of Object, Methods can be added to the Date Object; it is convenient to do so in order to provide additional output formats, such as for ISO 8601.

See below, and in inc-date.js, as shown at Include Files.

Altering an Object's Value

There may be no general means of changing the contents of an arbitrary Object using a Method of that Object; for example, Str.toUpperCase() returns a new string, but there is no Method to change Str itself. But the Date Object has various setXxxx() Methods, and Methods can be added that call these.

File inc-date.js contains read-only Date Methods used in my pages; see Include Files; the following demonstrates changing a Date Object's value by a new Method.

Self-Randomising a Date Object

This should display a date/time chosen at random in the range from 1970-01-01 00:00:00 GMT to now; the Methods seem of no actual use, but serve to test what can be done; in particular, that the existing methods can be used in new Methods to alter a value held in an Object.

S = D.getRandomDate()	// D not changed
D.setRandomEarlier()	// D is changed

ISO-Compatible String Input

These are methods for setting an existing Object from a string with numeric date-time fields in logical ISO 8601 order. However, there is generally no need to fully set an existing Object; see 3: Input and Lengths and 4: Validation. For output in ISO 8601 format, look in 9: Output Formatting and Include Files.

All of the methods below, as written, require a 4-digit year. In at least IE6, all require valid h m s values (disregarding the Missing Hour?). All signify unacceptable input by setting NaN.

The first two use new Date("YYYY/MM/DD hh:mm:ss"); ECMA does not specify string formats, but that seems always to work.


This accepts anything with Y M D h m s and no other digits.

D.setISOcompat(S)	// sets ISO-Compatible String Y M D h m s


This is strict on format, but does no explicit field-value tests. The character at T can be a space.

D.setISOstrict(S)	// sets ISO-Strict String YYYY-MM-DDThh:mm:ss


This will also verify all fields are in combination numerically valid, using only defined behaviour.

D.setISOvalid(S)	// sets ISO-valid String YYYY-MM-DDThh:mm:ss

I'm not sure whether all five value tests are necessary.

Day of Year

See also in 0 - Date Object Information .

N = D.getDoY()		// gets Day of Year
D.setDoY(N)		// sets Day of Year, changing Month and Day

ISO Week Number

See also in 7 : Working with Weeks.

A = D.getYWDarray()		// gives Y W D as array [Y,W,D]
S = D.getYWDstr()		// gives Y-W-D as string "yyyy-Www-d"
D.setYWDarray([Y,W,D])		// loads a Y W D array, unvalidated
D.readYWDstr("\d+\D+\d+\D+\d+")	// loads a Y*W*D string, unvalidated
D.validYWDstr("yyyy-Www-d")	// loads a Y-W-D string, validated
D.setWNDay(dn)			// sets ISO 8601 Day-of-Week
D.setWNWeek(wn)			// sets ISO 8601 Week Number
D.setWNyear(yn)			// Sets ISO 8601 Year Number

Like new Date(Y,M,D), the set methods allow out-of-range arguments.

Julian Calendar Date Routines

The difference between the Gregorian and Julian Calendar Dates of a given actual day is zero for most of the Third Century A.D., and increments whenever the Gregorian Calendar misses a Leap Day (in years X00 where X&3!=0 ). For calendar repeat intervals, see in Date Miscellany II.

Be aware that, when the Julian Calendar was used, it was common to change the year-number in mid-March; no account is taken of that here.

Julian Calendar Date Methods

D.getJulCal()		// returns Julian Y M D in an array [Y,W,D]
D.setJulCal()		// loads a Julian Y M D array, unvalidated

Here, methods setJulCal and getJulCal (shown below) are added to the Date Object. In them, the Julian Calendar is mapped through a 4-year range of the Gregorian Calendar. The Julian Calendar Date is represented as an array [Y, M, D]. Input fields may exceed their natural range. The array elements are output as numeric, but can also be input as strings. The year range should exceed ±270000, but it may not quite reach the full range of a Date Object.

Negative years are in Astronomical notation; years run ... -2 -1 0 1 2 ... .

The methods are independent of Zeller's work; follow the link for Easter code

The Julian and Gregorian Calendar Dates are here both local. On the other hand, it may be preferable to use UTC functions throughout.

In alternative function JCDtoDate the Gregorian-Julian Difference is subtracted from the Date value before conversion to a Date Object. The alternative function DateToJCD does the opposite; it is not intrinsically reliable, because of possible special cases, but it tends to confirm the other routines.

Here, Gregorian Calendar Dates are shown as Y-M-D and Julian Calendar Dates as Y/M/D. The yyyy/mm/dd field can be edited and tested by the ? button, or cycle-tested by the O button. The other buttons will blank the page for a bit while calculating; use the Back button to return.

Manual Tests


Auto Tests


5462 tests; in which :
• IE & FF report no errors
• Opera 9.27, 9.50 report 34 errors; see OST
• Safari 3.1 reports 4 high-year errors, off-range, OK

21 tests, in which
• IE, FF, Opera report no errors,
  but they give all NaN for days after 275760-09-13 (Day 1E8)
• Safari gives only part NaN after then, so claiming 11 errors, OK

21 tests, likewise

For Safari, see Automated Date Tests; there's no problem with the Julian Date code.

Julian Calendar Date Validation

Suggested approaches :-

Julian Calendar Date Validator Tests

Julian/Gregorian Calendar Date Conversion

The direct (Zeller-type) algorithm for converting a (Julian or Gregorian) Calendar Date to a Chronological Day Count (CMJD) is much faster than new Date(y, m', d) so it may be better to use that instead of using a Date Object.

Julian/Gregorian Calendar Conversion

    CMJD = CJDN - 2400001       Day-of-Week
Press a button to use the adjacent input. Input is not validated.
Years before A.D.1 must be in Astronomical Notation.

The range of the conversions between CMJD and Julian YMD is governed by the arithmetic limits in the above "zu" functions. The range of the conversions between CMJD and Gregorian YMD is here limited by the use of Date Objects in the imported "to" functions.

For conversion between hh:mm:ss and day fraction, see Time Conversion. For conversion of localised Gregorian date/time to float daycounts, see TLE, JD, MJD, CJD & CMJD.

Note that X|0 is faster than Math.floor(X) but is only equivalent for arguments in the range 0 to 2147483647.

JavaScript Date and Time Index
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, http://www.merlyn.demon.co.uk/, is maintained by me.