Page 1 of 2
First some Date basics.
More than the age of the universe
The key idea in using a Date object is to know that it stores the date and time as the number of milliseconds from the fixed date:
Thursday Jan 1st 00:00:00 UTC 1970.
Why this exact date in 1970?
However the Date object doesn't allow you to use this full range. It restricts the number of millisecond ticks to be in the range plus or minus:
which gives you a date range of plus or minus
To put this another way you can work with dates that span more than 23 billion (109) years before and after 1970. This should be enough for most, as the age of the universe is estimated to be around 13 billion years.
Notice that positive values are used to indicate dates after 1970 and negative values are before the fixed date.
The most useful of the static methods is now, which simply returns the number of milliseconds from the fixed date to the current moment. That is:
stores the current time and date in t.
Notice that t isn't a Date object. just a numerical value. If you use:
then you will see a large number not a date.
The other two slightly less useful static methods are:
which returns the number of milliseconds since the fixed date for the specified date and time (all of the time parameters are optional) and
which parses the date in the string and returns the number of milliseconds.
Notice that all of these static functions return simple numeric values and not a date object.
The date instance
The next level of sophistication is to create a Date instance. The Date function object is the constructor for any instances of the Date object you care to create. There are four variations on the way the constructor can be called:
returns a Date object with the current date and time
returns a Date object with number of milliseconds from the fixed date
returns a Date object set to the specified date and time as specified by the date string
returns a Date object set to the specified date and time.
The only complication is that you need to remember that in the constructor the first month of the year is month zero not month one. So
isn't the first of January but of February.
Notice that you really do need to think about the Date object as storing the number of milliseconds from the fixed date rather than as storing a date and a time in some other format.
- a Date object stores a number corresponding to the number of milliseconds since the fixed date and you can think of this as its value.
You can always discover the number of milliseconds stored in the Date object using the getTime method and you can set it using the setTime method.
UTC and local time
There are lots of methods that will use the value of a Date object to return other information in other data formats.
The most basic are the UTC functions which return the date and time as stored in the Date object.
- get/setUTCDate the day (date) of the month (1-31)
- get/setUTCDay the day of the week (0-6)
- get/settUTCFullYear the year (4 digits for 4-digit years)
- get/setUTCHours the hours (0-23)
- get/setUTCMilliseconds the milliseconds (0-999)
- get/setUTCMinutes the minutes (0-59)
- get/setUTCSeconds the seconds (0-59)
Of course not everyone wants to work with UTC and there are local time equivalents of each of the above methods - just leave out the UTC part of the name. Local time is offset from UTC by a number of minutes. If you use one of these local time methods to set a Date object then the time is first converted to UTC and then the number of UTC millisecond ticks is computed and stored in the Date object. Similarly when you get a local time the UTC time is converted to local time.
The rule is that the Date object always stores the UTC time and conversions to and from local time are performed unless you use the UTC methods.
You can discover the local time offset using the getTimezoneOffset which returns the time-zone offset in minutes for the current locale.