JavaScript Date Object Methods

Methods of the JavaScript Date Object

This is the second half of a two part discussion of the javascript date object. The first half discusses creating, formatting, extending and converting the date object. This section focuses solely on the methods of the javascript Date oject. In the prior section we created a working and accurate date object. There is a great deal written on the methods of the Date object, but there were very few examples. As this is an entry about JavaScript, you will need to have javascript enabled to learn from this tutorial. There are examples. of all the methods: see below:

dt {font-family:”Courier New”, Courier, mono; font-weight:bold;padding-top: 8px; padding-left:8px;}

I will be using three sample dates for the following examples:

  • var auntsBirthday = new Date(“September 4, 1902”);
  • var currTime = new Date() // your computer’s time
  • var myTime = new Date(2003,8,21); // September 21, 2003

When we get to the setMethods, the dates will be changed as we set different values.

prototype
The prototype property is used to assign new properties and methods to instances of the Date object
See Date.prototype.customFormat(datestring) in javascript date object tutorial.
constructor
A reference to the function that created the instance of a Date object. Can be used to test if a variable is a Date.
if (myTime.constructor == Date) {}
parse(string)
The millisecond equivalent of the date specified in the correctly formatted string parameter.

UTC(year, month [, date, hours, minutes, seconds, ms])
Returns an integer — the UTC millisecond value of the date specified as parameters. The parameter values for the UTC() method must be in UTC time for the returned value to be accurate. This method does not generate a Date object. The Year and Month are required. The other parameters are optional. I have no clue why anyone would use this. Please let me know via comments. The difference between UTC and getTime(); may be the offset from GMT. I need to look more into this.
toString()
Returns a string value of the date. Different browsers return different strings, and usually the string value is returned in a format that is not suitable to return raw to the user.
toDateString()
Returns the date portion of an instance of a Date object as a string. The format is under the control of the browser, so I prefer the customFormat method.
toTimeString()
Returns the time portion of the instance of a Date object as a String. The format depends on the browser and language so I prefer the customFormat method.

toLocaleString()
Returns the local time zone value of both the date and time. The format may be localized, so this may be useful for internationalization. I prefer, again, to rely on an internationalized version of the customFormat, but I probably shouldn’t.
toLocaleDateString()
Returns the date portion of an instance of a Date object as a String. The format is based on the browser and language and differs between some browsers, so I prefer the customFormat method.

toLocaleTimeString()
Returns the time as a String, with the format controlled by the browser and language.
valueOf()
Returns the value of the instance of the date object as an integer in millisenconds from Jan. 1, 1970.
getTime()
Returns an integer — the number of milliseconds since January 1, 1970, to the date specified by the instance of the Date object. I do not know how this differs from valueOf()
getFullYear()
Returns an integer representing the actual year for the date. Use this instead of getYear()
getUTCFullYear()
Returns the year for the date of the instance of the Date object in the UTC time stored internally by the browser. My guess is that this only differs from getFullYear when it comes to December 31 and January 1.
getMonth()
Returns the integer corresponding to the month value for the date specified by the instance of the Date object. Avoid logic errors: remember that arrays start with zero, so this returns an integer 0 – 11. January is 0 and December is 11.
getUTCMonth()
Returns the integer corresponding to the month value for the date specified by the instance of the Date object. Avoid logic errors: remember that arrays start with zero, so this returns an integer 0 – 11. January is 0 and December is 11. The difference between getMonth() and getUTCMonth is that the UTC time stored internally by the browser.
getDate()
Returns the day of the month, 1 – 31, specified by the instance of the Date object.
getUTCDate()
Similar to getDate(), for the UTC time stored internally by the browser.
getDay()
Returns an integer between 0 to 6, corresponding to the day value for the date specified by the instance of the Date object. Avoid logic errors: remember that arrays start with zero: Sunday is 0, Saturday is 6.
getUTCDay()
Returns an integer between 0 to 6, corresponding to the day value for the date specified by the instance of the Date object for the UTC time stored internally by the browser. Avoid logic errors: remember that arrays start with zero: Sunday is 0, Saturday is 6.
getHours()
Returns the integer, 0 – 23, for the hour of the day specified by the instance of the Date object, using the 24-hour time system.
getUTCHours()
Returns the integer, 0 – 23, for the hour of the day specified by the instance of the Date object, using the 24-hour time system.(the UTC time stored internally by the browser).
getMinutes()
getUTCMinutes()
Returns an integer, 0 – 59, representing the minute value for the hour specified by the instance of the Date object.

getSeconds()
getUTCSeconds()
Returns an integer, 0 – 59, the seconds past the last full minute as specified by the instance of the Date object.
getMilliseconds()
Returns an integer, 0 – 999, the milliseconds past the last full second as specified by the instance of the Date object.
getUTCMilliseconds()
Same as above, for the UTC time stored internally by the browser.
getTimezoneOffset()
Returns an integer betweeing -720 and 720 corresponging to minutes between your the site visitor’s computer and GMT. If your visitor is west of GMT, getTimezoneOffset() will return a positive values; negative values for east of GMT. Note: this returns the value in minutes — beware of logic errors!.
setTime(time)
Takes as a parameter an integer of milliseconds. Sets the date instance to the number of milliseconds from January 1, 1970. A negative integer will be before 1/1/70, a positive integer will return a date later than 1/1/70. Returns the milliseconds from 1/1/1970

setMilliseconds(ms)
setUTCMilliseconds(ms)
Takes as a parameter an integer of milliseconds. Sets the milliseconds of the date instance to the number of milliseconds from the current second. If the number is greater than 999, or less than 0, the rest of the time stamp will be effected: not just the millisecond count. It returns the milliseconds not of the parameter passed, but rather the milliseconds since 1/1/1970, midnight, GMT. The first example removes one year worth of milliseconds from the millenium date instance. The second example adds 1500 milliseconds, or 1.5 seconds. Do take a look at setUTCMilliseconds for an interesting tidbit… the “from the current second” above is quoted for a reason. You’ll note from the getMilliseconds() that this is indeed “from the last second”, and not simply an addition of milliseconds. In the test value for setMilliseconds(), the last four digits of the return value is 1500 – the milliseconds that were added. In the example for setUTCMilliseconds(), the number of milliseconds subtracted is subtracted from the seconds set above, not the milliseconds, as would seem logical

setSeconds(sec [, ms])
setUTCSeconds(sec [, ms])
Takes a required seconds as integer parameter and an optional milliseconds as integer parameter. If a float is passed as a parameter, a parseInt is automatically performed prior to setting the time. Returns the number of milliseconds from 1/1/70 GMT

setMinutes(minute [, sec, ms])
setUTCMinutes(minute [, sec, ms])
Takes a required parameter of seconds as an integer (performs the equivalent of Math.floor if the parameter is a float), and optional integer parameters of seconds and milliseconds. If you are going to define milliseconds, you must pass a seconds parameter. Returns the number of milliseconds from 1/1/70 GMT.

setHours(hour [, minute, sec, ms])
setUTCHours(hour [, minute, sec, ms])
Takes a required parameter of minutes as an integer (performs the equivalent of Math.floor() if the parameter is a float.), and optional integer parameters of minutes, seconds and milliseconds. If you are going to define milliseconds, you must pass minutes and seconds parameters. Returns the number of milliseconds from 1/1/70 GMT. The third example shows what happends when your integers are logic errors. The fourth example demonstrates that if a parameter is NaN, the function sets the date to NaN, and returns NaN

setDate(dateInt)
setUTCDate(date)
Sets the date of the month. The dateInt parameter should be in the form of an integer. If there is a logic error, such as 31 for June, the Date object calculates it and will return July 1. This sets the date, so your date object is changed. It also returns the new date in milliseconds. Note that in the third example, depending on your time zone, you may get the last day of last month.

setMonth(month [, date])
setUTCMonth(month [, date])
Sets the month, and, optionally, the day in the month. The month parameter should be in the form of an integer. Remember that the month array starts at O, so currTime.setMonth(2) will set the month to the third month, which is March. If there is a logic error, and your month int is not between 0 and 11, then the year will be set too.

setFullYear(year [, month, date])
setUTCFullYear(year [, month, date])
Sets the year, and, optionally, the month and the day in the month. The year parameter should be in the form of an integer. See quirks about the month in the setMonth() explanation. Note that the method reads “setFullYear(),” which is different then the setYear method. Since the difference is important to remember, I’ll compare the two in the examples. The setYear() adds 1900 years for any year between 0 and 100, whereas setFullYear() sets the year to whatever integer is passed.

toUTCString()
Taking no parameters, this method does not alter the date object: it simply returns the UTC value of the Date instance in standard string format: the day of the week abbreviated … well, look at the example. You’ll notice currTime has not been altered, and the return value is the same value, but presented in the UTC time zone rather than the user time zone. This method is for newer browsers than the toGMTString();, so it is recommended that you use this method over the GMT method below.

toGMTString()
Taking no parameters, this method does not alter the date object: it simply returns the value of the Date instance in standard string format. I saw no difference between the toUTCString() and toGMTString() methods.


getYear()
You don’t want to use this. Instead, use getFullYear(). Why? for years between 1900 and 1999, the getYear() method will return an integer between 0 and 99. This method does not alter the date instance. It takes no parameters. It returns an integer. Don’t use this method.

setYear(year)
Sets the year. The year parameter should be in the form of an integer. If (0<=year && year<100), setYear() adds 1900 to the year passed as the parameter. It is recommended to not use setYear(). Instead, opt for the setFullYear() method. Returns the new date instance value in milliseconds since 1/1/1970.

Notes:

  • getFullYear() and getYear() are NOT the same. getFullYear() is the actual year. getYear() is years since 1900.
This entry was posted in JavaScript, Web Development. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *