Core Objects (Dynamic HTML: The Definitive Reference, 2nd Edition)

ActiveXObject NN n/a IE 4(Win) ECMA n/a

Internet Explorer for Windows provides a direct portal between a web page and an ActiveX control (an automation object in Windows jargon) already registered with the Windows system. By creating an instance of the ActiveXObject, you supply your scripts with a reference to that control; use that reference to access the control's properties or invoke its methods. Uncovering the methods and properties of an automation object may require a bit of exploration through the Microsoft Developer Network web site (http://msdn.microsoft.com). A Microsoft utility, called OLE/COM Object Viewer, can also open doors for the persistent. A good place to start your exploration is http://msdn.microsoft.com/scripting/jscript/doc/jsobjActiveXObject.htm. See also the GetObject( ) global function for a way to obtain a reference to an automation object via its local pathname.

Creating an ActiveXObject

var myObj = new ActiveXObject(appName.className[, remoteServerName])

Properties

None.

Methods

None.

arguments NN 3 IE 4 ECMA 1

Every function—while it is executing—has an arguments object, which is accessible as a property of the function. The object is created automatically, and cannot be created outside of the function context that owns it. For example, consider a typical function definition:

function myFunc( ) {
     // function statements
}

A statement inside the function can access the arguments object by the following reference:

arguments

This object always contains the callee property, which is a reference to the very same function (explained in the callee property discussion). But you can also use the arguments object to access each parameter variable value through array notation. In the above example, a statement inside the myFunc( ) function can access the passed parameter value with the following reference:

arguments[0]

See the arguments property discussion of the Function object later in this chapter for practical applications.

Properties

callee

length

Methods

None.

callee NN 6 IE 5(Mac)/5.5(Win) ECMA 1
Read-only
Provides a reference to the function that created the arguments object. This property provides the essential reference to the current function, which an anonymous function would require for it to be called in a recursive construction.

Example

myObj.doThis = function(input) { // function statements that act on parameter value if (!someCondition) { arguments.callee(input); } }

Value

Function object reference.

length NN 3 IE 4 ECMA 1
Read-only
Returns the number of arguments passed to the function in its current invocation. The number is not influenced by the number of parameter variables defined for the function.

Example

function myFunc( ) for (var i = 0; i < arguments.length; i++) { ... } }

Value

Integer.

Array NN 3 IE 4 ECMA 1

An array is an ordered collection of one or more pieces of data. JavaScript array entries may be of any data type, and you can mix different data types in the same array. Each entry in an array has an index assigned to it. The default behavior is for the index to be a zero-based integer (the first entry has an index of zero). An index value may also be a string, but the string index acts like a property name of an array object, and does not influence the numeric indices (which is why string-indexed entries cannot be iterated via the array's length property, but can be iterated via a for-in loop). Separate sets of integer- and string-indexed items can coexist within the same array object.

Accessing an entry in an array requires the name of the array and the index in square brackets:

cars[0]
cars["Ford"]

You may also create an array of arrays to simulate multidimensional arrays. A reference to an item in a two-dimensional array uses syntax as follows:

myArray[x][y]

The number of entries in a JavaScript array (its length) can vary over time. Therefore, you do not have to initialize an empty array to a specific size (nor is there any particular advantage to doing so). To add a new entry to an array of indeterminant length, assign the value to the next higher array index value:

cars[cars.length] = "Bentley";

A shortcut array creation technique is available starting in IE 4 and Navigator 4, using square brackets to contain values in literal notation.

Creating an Array

var myArray = new Array( );
var myArray = new Array(sizeInteger);
var myArray = new Array(element0, element1, ..., elementN);
var myArray = [element0, element1, ..., elementN];

Properties

constructor

length

prototype

Methods

`concat( )`	`join( )`	`pop( )`
`push( )`	`reverse( )`	`shift( )`
`slice( )`	`sort( )`	`splice( )`
`toLocaleString( )`	`toString( )`	`unshift( )`

constructor NN 4 IE 4 ECMA 1
Read/Write
This is a reference to the function that created the instance of an Array object—the native Array( ) constructor function in browsers.

Example

if (myVar.constructor == Array) { // process native string }

Value

Function object reference.

length NN 3 IE 4 ECMA 1
Read/Write
Provides a count of the number of numerically-indexed entries stored in the array. If the constructor function used to create the array specified a preliminary length, the length property reflects that amount, even if data does not occupy every slot.

Example

for (var i = 0; i < myArray.length; i++) { ... }

Value

Integer.

prototype NN 3 IE 4 ECMA 1
Read/Write
This is a property of the static Array object. Use the prototype property to assign new properties and methods to future instances of arrays created in the current document. For example, the following function creates a return-delimited list of elements in an array in reverse order:
function formatAsList( ) { var output = ""; for (var i = this.length - 1; i >= 0; i--) { output += this[i] + "\n"; } alert(output); }
To give an array that power, assign this function reference to a prototype property whose name you want to use as the method to invoke this function:
Array.prototype.showReverseList = formatAsList;
If a script creates an array at this point:
var stooges = new Array("Moe", "Larry", "Curly", "Shemp");
the new array has the showReverseList( ) method available to it. To invoke the method, the call is:
stooges.showReverseList( );
You can add properties the same way. These allow you to attach information about the array (its creation time, for example) without disturbing the ordered sequence of array data. When a new document loads into the window or frame, the static Array object starts fresh again.

Example

Array.prototype.created = "";

Value

Any data, including function references.

concat( ) NN 4 IE 4 ECMA 3
concat(item1[, item2[, ...itemN]])
Returns an array that combines the current array object with one or more array objects (or other values) specified as the method parameter(s):
var combinedArray = myArray1.concat(myArray2, someValue);
Neither of the original arrays is altered in the process.

Returned Value

An Array object.

Parameters

item1...itemN

Any JavaScript value, including another array.

join( ) NN 3 IE 4 ECMA 1
join(["delimiterString"])
Returns a string consisting of a list of items (as strings) contained by an array. The delimiter character(s) between items is set by the parameter to the method. Note that an array's items are only those items that are accessible via an integer index. Items referenced via string index values are treated as properties of the array object, and are thus independent of integer indexed values (the two sets can coexist in a single array without conflict). The join( ) method works only with the integer-indexed items.

Returned Value

String.

Parameters

delimiterString

Any string of characters. Nonalphanumeric characters must use URL-encoded equivalents (%0D for carriage return). The default delimiter string is a comma character.

pop( ) NN 4 IE 5.5(Win) ECMA 2
Returns the value of the last item in an array and removes it from the array. The length of the array decreases by one.

Returned Value

Any JavaScript value.

Parameters

None.

push( ) NN 4 IE 5.5(Win) ECMA 2
push(item1[, item2[, ...itemN]])
Appends one or more items to the end of an array. The length of the array increases by one.

Returned Value

The value pushed into the array.

Parameters

item1...itemN

Comma-delimited list of one or more JavaScript values, including object references.

reverse( ) NN 3 IE 4 ECMA 1
Reverses the order of items in the array and returns a copy of the array in the new order. Not only does the reverse( ) method rearrange the values in the array, but it also returns a copy of the reversed array.

Returned Value

An Array object.

Parameters

None.

shift( ) NN 4 IE 5.5(Win) ECMA 2
Returns the value of the first item in an array and removes it from the array. The length of the array decreases by one.

Returned Value

Any JavaScript value.

Parameters

None.

slice( ) NN 4 IE 4 ECMA 2
slice(startIndex[, endIndex])
Returns an array that is a subset of contiguous items from the main array. Parameters determine where the selection begins and ends.

Returned Value

An Array object.

Parameters

startIndex

A zero-based integer of the first item of the subset from the current array.

endIndex

An optional zero-based integer of the last item of the subset from the current array. If omitted, the selection is made from the startIndex position to the end of the array.

sort( ) NN 3 IE 4 ECMA 1
sort([compareFunction])
Sorts the values of the array either by the ASCII value of string versions of each array entry or according to a comparison function of your own design. The sort( ) method repeatedly invokes the comparison function, passing two values from the array. The comparison function should return an integer value, which is interpreted by the sort( ) function as follows.

Value

Meaning

<0
The second passed value should sort later than the first value.

0
The sort order of the two values should not change.

>0
The first passed value should sort later than the second.

The following comparison function sorts values of an array in numerical (instead of ASCII) order:
function doCompare(a, b) { return a - b; }
To sort an array by this function, the statement is:
myArray.sort(doCompare);
By the time the sort( ) method has completed its job, it has sent all values to the doCompare( ) function two values at a time and sorted the values on whether the first value is larger than the second (in the manner of a bubble sort).
Not only does the sort( ) method rearrange the values in the array, but it also returns a copy of the sorted array.

Returned Value

An Array object, sorted according to sorting criteria.

Parameters

compareFunction

A reference to a function that receives two parameters and returns an integer result.

Value	Meaning
`<0`	The second passed value should sort later than the first value.
`0`	The sort order of the two values should not change.
`>0`	The first passed value should sort later than the second.

splice( ) NN 4 IE 5.5(Win) ECMA 2
splice(startIndex, deleteCount[, item1[, item2[, ...itemN]]])
Removes one or more contiguous items from within an array and, optionally, inserts new items in their places. The length of the array adjusts itself accordingly.

Returned Value

An Array object containing removed items.

Parameters

startIndex

A zero-based integer of the first item of the subset from the current array.

deleteCount

An integer denoting how many items from the startIndex position are to be removed from the array.

item1...itemN

Comma-delimited list of JavaScript values to be inserted into the array in place of removed items. The number of items does not have to equal deleteCount.

toLocaleString( ) NN 6 IE 5.5(Win) ECMA 2
Returns a comma-delimited string of values, theoretically in a format tailored to the language and customs of the browser's default language. Implementation details vary with browser and data type. IE 5.5 and later converts numbers of all kinds to strings with two digits to the right of the decimal, but triggers an error for object references. Netscape 6 leaves integers in their original format and displays object references as [object objectType]. The ECMA standard leaves such interpretations up to the browser maker.

Returned Value

Comma-delimited string.

Parameters

None.

toString( ) NN 3 IE 4 ECMA 1
Returns a comma-delimited string of values, identical to using the Array.join( ) method with a comma parameter. All values are converted to some string equivalent, including objects ([object] in IE/Windows; [object objectType] in IE 5/Macintosh and Netscape 6).

Returned Value

Comma-delimited string.

Parameters

None.

unshift( ) NN 4 IE 5.5(Win) ECMA 2
unshift(item1[, item2[, ...itemN]])
Inserts one or more items at the beginning of an array. The length of the array increases by the number of items added, and the method returns the new length of the array.

Returned Value

Integer.

Parameters

item1...itemN

Comma-delimited list of one or more JavaScript values.

Boolean NN 3 IE 4 ECMA 1

A Boolean object represents any value that evaluates to true or false. By and large, you don't have to worry about the Boolean object because the browsers automatically create such objects for you when you assign a true or false value to a variable. Quoted versions of these values are treated only as string.

Creating a Boolean Object

var myValue = new Boolean( );
var myValue = new Boolean(BooleanValue);
var myValue = BooleanValue;

Properties

constructor

prototype

Methods

toString( )

valueOf( )

constructor NN 4 IE 4 ECMA 1
Read/Write
This is a reference to the function that created the instance of a Boolean object—the native Boolean( ) constructor function in browsers.

Example

if (myVar.constructor == Boolean) { // process native string }

Value

Function object reference.

prototype NN 3 IE 4 ECMA 1
Read/Write
This is a property of the static Boolean object. Use the prototype property to assign new properties and methods to future instances of a Boolean value created in the current document. See the Array.prototype property description for examples. There is little need to create new prototype properties or methods for the Boolean object.

Example

Boolean.prototype.author = "DG";

Value

Any data, including function references.

toString( ) NN 4 IE 4 ECMA 1
Returns the object's value as a string data type. You don't need this method in practice, because the browsers automatically convert Boolean values to strings when they are needed for display in alert dialogs or in-document rendering.

Returned Value

"true" | "false"

Parameters

None.

valueOf( ) NN 4 IE 4 ECMA 1
Returns the object's value as a Boolean data type. You don't need this method when you create Boolean objects by simple value assignment.

Returned Value

Boolean value: true | false.

Parameters

None.

Date NN 2 IE 3 ECMA 1

The Date object is a static object that generates instances by way of several constructor functions. Each instance of a Date object is a snapshot of the date and time, measured in milliseconds relative to zero hours on January 1, 1970. Negative millisecond values represent time before that date; positive values represent time since that date.

The typical way to work with dates is to generate a new instance of the Date object, either for now or for a specific date and time (past or future, using the client local time). Then use the myriad of available date methods to get or set components of that time (e.g., minutes, hours, date, month). Browsers internally store a date as the millisecond value at Coordinated Universal Time (UTC, which is essentially the same as Greenwich Mean Time, or GMT). When you ask a browser for a component of that time, it automatically converts the value to the local time zone of the browser based on the client computer's control panel setting for the clock and time zone. If the control panel is set incorrectly, time and date calculations may go awry.

Early versions of scriptable browsers had numerous bugs when working with the Date object. One resource that explains the fundamental operations within the Date object (and bugs) can be found at http://developer.netscape.com/viewsource/goodman_dateobject.html.

Creating a Date Object

var now = new Date( );
var myDate = new Date("month dd, yyyy hh:mm:ss");
var myDate = new Date("month dd, yyyy");
var myDate = new Date(yy, mm, dd, hh, mm, ss);
var myDate = new Date(yy, mm, dd);
var myDate = new Date(milliseconds);

Properties

constructor

prototype

Methods

`getDate( )`	`getDay( )`	`getFullYear( )`
`getHours( )`	`getMilliseconds( )`	`getMinutes( )`
`getMonth( )`	`getSeconds( )`	`getTime( )`
`getTimezoneOffset( )`	`getUTCDate( )`	`getUTCDay( )`
`getUTCFullYear( )`	`getUTCHours( )`	`getUTCMilliseconds( )`
`getUTCMinutes( )`	`getUTCMonth( )`	`getUTCSeconds( )`
`getVarDate( )`	`getYear( )`	`parse( )`
`setDate( )`	`setFullYear( )`	`setHours( )`
`setMilliseconds( )`	`setMinutes( )`	`setMonth( )`
`setSeconds( )`	`setTime( )`	`setUTCDate( )`
`setUTCFullYear( )`	`setUTCHours( )`	`setUTCMilliseconds( )`
`setUTCMinutes( )`	`setUTCMonth( )`	`setUTCSeconds( )`
`setYear( )`	`toDateString( )`	`toGMTString( )`
`toLocaleDateString( )`	`toLocaleString( )`	`toLocaleTimeString( )`
`toString( )`	`toTimeString( )`	`toUTCString( )`
`UTC( )`	`valueOf( )`

constructor NN 4 IE 4 ECMA 1
Read/Write
This is a reference to the function that created the instance of a Date object—the native Date( ) constructor function in browsers.

Example

if (myVar.constructor == Date) { // process native string }

Value

Function object reference.

prototype NN 3 IE 4 ECMA 1
Read/Write
This is a property of the static Date object. Use the prototype property to assign new properties and methods to future instances of a Date value created in the current document. See the Array.prototype property description for examples.

Example

Date.prototype.author = "DG";

Value

Any data, including function references.

getDate( ) NN 2 IE 3 ECMA 1
Returns the calendar date within the month specified by an instance of the Date object.

Returned Value

Integer between 1 and 31.

Parameters

None.

getDay( ) NN 2 IE 3 ECMA 1
Returns an integer corresponding to a day of the week for the date specified by an instance of the Date object.

Returned Value

Integer between 0 and 6. Sunday is 0, Monday is 1, and Saturday is 6.

Parameters

None.

getFullYear( ) NN 4 IE 4 ECMA 1
Returns all digits of the year for the date specified by an instance of the Date object.

Returned Value

Integer. Navigator 4 goes no lower than zero. Internet Explorer and Netscape 6 return negative year values.

Parameters

None.

getHours( ) NN 2 IE 3 ECMA 1
Returns a zero-based integer corresponding to the hours of the day for the date specified by an instance of the Date object. The 24-hour time system is used.

Returned Value

Integer between 0 and 23.

Parameters

None.

getMilliseconds( ) NN 4 IE 4 ECMA 1
Returns a zero-based integer corresponding to the number of milliseconds past the seconds value of the date specified by an instance of the Date object.

Returned Value

Integer between 0 and 999.

Parameters

None.

getMinutes( ) NN 2 IE 3 ECMA 1
Returns a zero-based integer corresponding to the minute value for the hour and date specified by an instance of the Date object.

Returned Value

Integer between 0 and 59.

Parameters

None.

getMonth( ) NN 2 IE 3 ECMA 1
Returns a zero-based integer corresponding to the month value for the date specified by an instance of the Date object. That this method's values are zero-based frequently confuses scripters at first.

Returned Value

Integer between 0 and 11. January is 0, February is 1, and December is 11.

Parameters

None.

getSeconds( ) NN 2 IE 3 ECMA 1
Returns a zero-based integer corresponding to the seconds past the nearest full minute for the date specified by an instance of the Date object.

Returned Value

Integer between 0 and 59.

Parameters

None.

getTime( ) NN 2 IE 3 ECMA 1
Returns a zero-based integer corresponding to the number of milliseconds since January 1, 1970, to the date specified by an instance of the Date object.

Returned Value

Integer.

Parameters

None.

getTimezoneOffset( ) NN 2 IE 3 ECMA 1
Returns a zero-based integer corresponding to the number of minutes difference between GMT and the client computer's clock for an instance of the Date object. Time zones to the west of GMT are positive values; time zones to the east are negative values. Numerous bugs plagued this method in early browsers, especially Macintosh versions.

Returned Value

Integer between -720 and 720.

Parameters

None.

getUTCDate( ) NN 4 IE 4 ECMA 1
Returns the calendar date within the month specified by an instance of the Date object but in the UTC time stored internally by the browser.

Returned Value

Integer between 1 and 31.

Parameters

None.

getUTCDay( ) NN 4 IE 4 ECMA 1
Returns an integer corresponding to a day of the week for the date specified by an instance of the Date object but in the UTC time stored internally by the browser.

Returned Value

Integer between 0 and 6. Sunday is 0, Monday is 1, and Saturday is 6.

Parameters

None.

getUTCFullYear( ) NN 4 IE 4 ECMA 1
Returns all digits of the year for the date specified by an instance of the Date object but in the UTC time stored internally by the browser.

Returned Value

Integer. Navigator 4 goes no lower than zero. Internet Explorer and Netscape 6 return negative year values.

Parameters

None.

getUTCHours( ) NN 4 IE 4 ECMA 1
Returns a zero-based integer corresponding to the hours of the day for the date specified by an instance of the Date object but in the UTC time stored internally by the browser. The 24-hour time system is used.

Returned Value

Integer between 0 and 23.

Parameters

None.

getUTCMilliseconds( ) NN 4 IE 4 ECMA 1
Returns a zero-based integer corresponding to the number of milliseconds past the seconds value of the date specified by an instance of the Date object but in the UTC time stored internally by the browser.

Returned Value

Integer between 0 and 999.

Parameters

None.

getUTCMinutes( ) NN 4 IE 4 ECMA 1
Returns a zero-based integer corresponding to the minute value for the hour and date specified by an instance of the Date object but in the UTC time stored internally by the browser.

Returned Value

Integer between 0 and 59.

Parameters

None.

getUTCMonth( ) NN 4 IE 4 ECMA 1
Returns a zero-based integer corresponding to the month value for the date specified by an instance of the Date object but in the UTC time stored internally by the browser. That this method's values are zero-based frequently confuses scripters at first.

Returned Value

Integer between 0 and 11. January is 0, February is 1, and December is 11.

Parameters

None.

getUTCSeconds( ) NN 4 IE 4 ECMA 1
Returns a zero-based integer corresponding to the seconds value past the nearest full minute of the date specified by an instance of the Date object but in the UTC time stored internally by the browser.

Returned Value

Integer between 0 and 59.

Parameters

None.

getVarDate( ) NN n/a IE 4 ECMA n/a
Returns a date value in a format (called VT_DATE) suitable for a variety of Windows-oriented applications, such as ActiveX controls and VBScript. Not for use with JavaScript date calculations.

Returned Value

VT_DATE format value (not for JavaScript use).

Parameters

None.

getYear( ) NN 2 IE 3 ECMA n/a
Returns a number corresponding to the year of an instance of the Date object, but exhibits irregular behavior. In theory, the method should return the number of years the date object represents since 1900. This would produce a one- or two-digit value for all years between 1900 and 1999. However, when you reach 2000, the pattern fails. Instead of producing values starting with 100, the getYear( ) method, some browsers return the same four-digit value as getFullYear( ). For this reason, it is best to use getFullYear( ) whenever possible (but observe the browser compatibility for that method). Note that this method is not an ECMA-supported method, whereas getFullYear( ) is.

Returned Value

Integer between 0 and 99 for the years 1900 to 1999; four-digit integer starting with 2000 for some browsers, or a continuation (100+) for others.

Parameters

None.

parse( ) NN 2 IE 3 ECMA 1
parse("dateString")
Static Date object method that returns the millisecond equivalent of the date specified as a string in the parameter.

Returned Value

Date in milliseconds.

Parameters

dateString

Any valid string format equivalent to that derived from a Date object. See toString( ), toGMTString( ), and toLocaleString( ) methods for sample formats.

setDate( ) NN 2 IE 3 ECMA 1
setDate(dateInt)
Sets the date within the month for an instance of the Date object. If you specify a date beyond the end of the object's current month, the object recalculates the date in the succeeding month. For example, if a Date object is set to December 25, 2002, you can find out the calendar date ten days later with the following construction:
myDate.setDate(myDate.getDate( ) + 10);
After this calculation, the value of myDate is the equivalent of January 4, 2003.

Returned Value

New date in milliseconds.

Parameters

dateInt

Date integer.

setFullYear( ) NN 4 IE 4 ECMA 1
setFullYear(yearInt)
Assigns the year for an instance of the Date object.

Returned Value

New date in milliseconds.

Parameters

yearInt

Integer. Navigator 4 allows digits no lower than zero. Internet Explorer and NN 6 allow negative year values.

setHours( ) NN 2 IE 3 ECMA 1
setHours(hourInt)
Sets the hours of the day for an instance of the Date object. The 24-hour time system is used. If you specify an hour beyond the end of the object's current day, the object recalculates the time in the succeeding day(s).

Returned Value

New date in milliseconds.

Parameters

hourInt

Zero-based integer.

setMilliseconds( ) NN 4 IE 4 ECMA 1
setMilliseconds(msInt)
Sets the number of milliseconds past the seconds value for an instance of the Date object.

Returned Value

New date in milliseconds.

Parameters

msInt

Zero-based integer of milliseconds.

setMinutes( ) NN 2 IE 3 ECMA 1
setMinutes(minuteInt)
Sets the minute value for the hour and date of an instance of the Date object.

Returned Value

New date in milliseconds.

Parameters

minuteInt

Zero-based integer.

setMonth( ) NN 2 IE 3 ECMA 1
setMonth(monthInt)
Sets the month value for the date of an instance of the Date object. That this method's values are zero-based frequently confuses scripters at first.

Returned Value

New date in milliseconds.

Parameters

monthInt

Zero-based integer. January is 0, February is 1, and December is 11. Assigning higher values increases the object to the succeeding year.

setSeconds( ) NN 2 IE 3 ECMA 1
setSeconds(secInt)
Sets the seconds value past the nearest full minute for an instance of the Date object.

Returned Value

New date in milliseconds.

Parameters

secInt

Zero-based integer.

setTime( ) NN 2 IE 3 ECMA 1
setTime(msInt)
Sets an instance of the Date object to the number of milliseconds since January 1, 1970.

Returned Value

New date in milliseconds.

Parameters

msInt

Integer of milliseconds.

setUTCDate( ) NN 4 IE 4 ECMA 1
setUTCDate(dateInt)
Sets the date within the month of an instance of the Date object but in the UTC time stored internally by the browser. If you specify a date beyond the end of the object's current month, the object recalculates the date in the succeeding month.

Returned Value

New UTC date in milliseconds.

Parameters

dateInt

Integer.

setUTCFullYear( ) NN 4 IE 4 ECMA 1
setUTCFullYear(yearInt)
Sets all digits of the year for an instance of the Date object but in the UTC time stored internally by the browser.

Returned Value

New UTC date in milliseconds.

Parameters

yearInt

Integer. Navigator 4 allows values no lower than zero. Internet Explorer and NN 6 allow negative year values.

setUTCHours( ) NN 4 IE 4 ECMA 1
setUTCHours(hourInt)
Sets the hours of the day for an instance of the Date object but in the UTC time stored internally by the browser. The 24-hour time system is used.

Returned Value

New UTC date in milliseconds.

Parameters

hourInt

Zero-based integer.

setUTCMilliseconds( ) NN 4 IE 4 ECMA 1
setUTCMilliseconds(msInt)
Sets the number of milliseconds past the seconds value of an instance of the Date object but in the UTC time stored internally by the browser.

Returned Value

New UTC date in milliseconds.

Parameters

msInt

Zero-based integer.

setUTCMinutes( ) NN 4 IE 4 ECMA 1
setUTCMinutes(minuteInt)
Sets the minute value for the hour and date of an instance of the Date object but in the UTC time stored internally by the browser.

Returned Value

New UTC date in milliseconds.

Parameters

minuteInt

Zero-based integer.

setUTCMonth( ) NN 4 IE 4 ECMA 1
setUTCMonth(monthInt)
Sets the month value for an instance of the Date object but in the UTC time stored internally by the browser. That this method's values are zero-based frequently confuses scripters at first.

Returned Value

New UTC date in milliseconds.

Parameters

monthInt

Zero-based integer. January is 0, February is 1, and December is 11. Assigning higher values increases the object to the succeeding year.

setUTCSeconds( ) NN 4 IE 4 ECMA 1
setUTCSeconds(secInt)
Sets the seconds value past the nearest full for an instance of the Date object but in the UTC time stored internally by the browser.

Returned Value

New UTC date in milliseconds.

Parameters

secInt

Zero-based integer.

setYear( ) NN 2 IE 3 ECMA n/a
setYear(yearInt)
Sets the year of an instance of a Date object. Use setFullYear( ) if the browser versions you support allow it. Note that this method is not an ECMA-supported method, whereas setFullYear( ) is.

Returned Value

New date in milliseconds.

Parameters

yearInt

Four-digit (and sometimes two-digit) integers representing a year.

toDateString( ) NN 6 IE 5.5(Win) ECMA 3
Returns a string consisting only of the date portion of an instance of a Date object. The precise format is under the control of the browser and language, but U.S. English versions of both IE 6 for Windows and Netscape 6 return values in the format Ddd Mmm dd yyyy.

Returned Value

String.

Parameters

None.

toGMTString( ) NN 2 IE 3 ECMA 1
Returns a string version of the GMT value of a Date object instance in a standardized format. This method does not alter the original Date object. For use in newer browsers, the toUTCString( ) method is recommended in favor of toGMTString( ).

Returned Value

String in the following format: dayAbbrev, dd mmm yyyy hh:mm:ss GMT. For example:

Mon 05 Aug 2002 02:33:22 GMT

Parameters

None.

toLocaleDateString( ) NN 6 IE 5.5(Win) ECMA 3
Returns a string consisting only of the date portion of an instance of a Date object. The precise format is under the control of the browser and language. IE 6 for Windows returns a value in the format fullDay, fullMonth dd, yyyy; Netscape 6 returns fullDay fullMonth dd yyyy.

Returned Value

String.

Parameters

None.

toLocaleString( ) NN 2 IE 3 ECMA 1
Returns a string version of the local time zone value of both the date and time from a Date object instance. The format may be localized for a particular country or an operating system's convention.

Returned Value

String in a variety of possible formats. Examples of U.S. versions of browsers include the following.

Platform

String value

Internet Explorer 6/Win32
Tuesday, April 01, 2003 7:30:00 AM

Internet Explorer 5.1/Mac
Tuesday, 01 April, 2003 07:30:00 AM

Navigator 6/Win32
Tuesday, April 01, 2003 07:30:00

Navigator 6/Mac
Tuesday April 01 07:30:00 2003

Parameters

None.

toLocaleTimeString( ) NN 6 IE 5.5(Win) ECMA 3
Returns a string consisting only of the time portion of an instance of a Date object. The precise format is under the control of the browser and language. IE 6 for Windows returns a value in the format [h]h:mm:ss xM; Netscape 6 returns hh:mm:ss.

Returned Value

String.

Parameters

None.

toString( ) NN 2 IE 4 ECMA 1
This is a method used mostly by the browser itself to obtain a string version of an instance of a Date object when needed for display in dialog boxes or on-screen rendering.

Returned Value

String in a variety of possible formats. Here are examples for U.S. versions of browsers.

Platform

String Value

Internet Explorer 6/Win32
Tue Apr 1 07:30:00 PST 2003

Internet Explorer 5.1/Mac
Tue Apr 1 07:30:00 PST 2003

Navigator 6/Win32
Tue Apr 01 07:30:00 GMT-0800 (Pacific Standard Time) 2003

Navigator 6/Mac
Tue Apr 01 2003 07:30:00 GMT-0800

Parameters

None.

toTimeString( ) NN 6 IE 5.5(Win) ECMA 3
Returns a string consisting only of the time portion of an instance of a Date object. The precise format is under the control of the browser and language.

Returned Value

String.

Parameters

None.

toUTCString( ) NN 4 IE 4 ECMA 1
Returns a string version of the UTC value of a Date object instance in a standardized format. This method does not alter the original Date object. For use in newer browsers, the toUTCString( ) method is recommended in favor of toGMTString( ).

Returned Value

String in the following format: dayAbbrev dd mmm yyyy hh:mm:ss GMT. For example:

Mon 05 Aug 2002 02:33:22 GMT

Parameters

None.

UTC( ) NN 2 IE 3 ECMA 1
UTC(yyyy, mm, dd[, hh[, mm[, ss[, msecs]]]])
This is a static method of the Date object that returns a numeric version of the date as stored internally by the browser for a Date object. Unlike parameters to the Date object constructor, 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, as the Date object constructor does.

Returned Value

Integer of the UTC millisecond value of the date specified as parameters.

Parameters

yyyy

Four-digit year value.

mm

Two-digit month number (0-11).

dd

Two-digit date number (1-31).

hh

Optional two-digit hour number in 24-hour time (0-23).

mm

Optional two-digit minute number (0-59).

ss

Optional two-digit second number (0-59).

msec

Optional milliseconds past the last whole second (0-999).

valueOf( ) NN 4 IE 4 ECMA 1
Returns the object's value.

Returned Value

Integer millisecond count.

Parameters

None.

Enumerator NN n/a IE 4(Win) ECMA n/a

If an ActiveX control property or method returns a collection of values, the usual JavaScript approach to collections (treating them as arrays) does not work for such values. The Enumerator object gives JavaScript a way to reference items in such collections by controlling a pointer to the list of items. For additional details, visit http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/js56jsobjenumerator.asp.

Creating an Enumerator

var myEnumObj = new Enumerator(externalCollection);

Properties

None.

Methods

atEnd( )

item( )

moveFirst( )

moveNext( )

atEnd( ) NN n/a IE 4(Win) ECMA n/a
Returns Boolean true if the Enumerator is pointing at the last item in the collection.

Returned Value

Boolean value: true | false.

Parameters

None.

item( ) NN n/a IE 4(Win) ECMA n/a
Returns a value from the collection at the pointer's current position.

Returned Value

Number, string, or other value from the collection.

Parameters

None.

moveFirst(), moveNext( ) NN n/a IE 4(Win) ECMA n/a
Adjust the location of the pointer within the collection, jumping to the first item in the collection, or ahead by one item.

Returned Value

None.

Parameters

None.

Error NN 6 IE 5(Win) ECMA 3

Browsers that implement try/catch exception handling automatically create an instance of the Error object whenever an error occurs during script processing. You can also create an Error object instance that you explicitly throw. The catch portion of the try/catch construction receives the Error object instance as a parameter, which scripts can examine to learn the details of the error, as exposed by the object's properties.

Creating an Error Object

var myError = new Error("errorMessage");

Properties

`constructor`	`description`	`fileName`	`lineNumber`
`message`	`name`	`number`	`prototype`

Methods

toString( )

constructor NN 6 IE 5(Win) ECMA 3
Read/Write
Provides a reference to the function that created the instance of an Error object—the native Error( ) constructor function in browsers.

Example

if (myVar.constructor == Error) { // process native string }

Value

Function object reference.

description NN n/a IE 5(Win) ECMA n/a
Read/Write
Provides a plain-language description of the error, frequently the same as appears in the IE script error dialog. Use the newer message property if possible.

Example

if (myError.description.indexOf("Object expected") != -1) { // handle "object expected" error }

Value

String.

fileName NN 6 IE n/a ECMA n/a
Read/Write
Specifies the URL of the page in which the script error occurred. This information appears in the JavaScript Console window for each reported error.

Example

var sourceFile = myError.fileName;

Value

URL string.

lineNumber NN 6 IE n/a ECMA n/a
Read/Write
Specifies the number of the line in the source code where the current script error occurred. This information appears in the JavaScript Console window for each reported error.

Example

var errorLine = myError.lineNumber;

Value

Number in string format.

message NN 6 IE 5.5(Win) ECMA 3
Read/Write
Provides a plain-language description of the error. There is no standard for the format or content of such messages.

Example

if (myError.description.indexOf("defined") != -1) { // handle error for something being undefined }

Value

String.

name NN 6 IE 5.5(Win) ECMA 3
Read/Write
This is a string that sometimes indicates the type of the current error. The default value of this property is Error. But the browser may also report types EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError, and, if supported by the browser, a specific W3C DOM error type.

Example

if (myError.name == "SyntaxError") { // handle syntax error }

Value

String.

number NN n/a IE 5(Win) ECMA n/a
Read/Write
Provides a number corresponding to an IE error. You must apply binary arithmetic to the value to derive a meaningful number. Use:
var errNum = ErrObj.number & x0FFFF;
Then compare the result against Microsoft's numbered listing at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/js56jsmscRunTimeErrors.asp.

Example
var errNo = myError.number;
Value

Number.

prototype NN 6 IE 5(Win) ECMA 3
Read/Write
This is a property of the static Error object. Use the prototype property to assign new properties and methods to future instances of a Error object created in the current document. See the Array.prototype property description for examples.

Example

Error.prototype.custom = true;

Value

Any data, including function references.

toString( ) NN 6 IE 5(Win) ECMA 3
Returns a string representation of the object, but the values differ between browser families. IE returns [object Error], while Netscape 6 returns a concatenation of the name and message properties.

Returned Value

String.

Parameters

None.

Function NN 2 IE 3 ECMA 1

A function is a group of one or more script statements that can be invoked at any time during or after the loading of a page. Invoking a function requires nothing more than including the function name with a trailing set of parentheses inside another script statement or as a value assigned to an event handler attribute in an HTML tag.

Since the first scriptable browsers, a function is created by the act of defining it inside a script element:

function funcName( ) {...}

More recent browsers also allow the use of a constructor function, but this syntax is usually more complex than defining a function.

Functions may be built to receive zero or more parameters. Parameters are assigned to comma-delimited parameter variables defined in the parentheses pair following the function name:

function doSomething(param1, param2, ... paramN) {...}

A parameter value may be any JavaScript data type, including object references and arrays. There is no penalty for not supplying the same number of parameters to the function as are defined for the function. The function object receives all parameters into an array (called arguments), which script statements inside the function may examine to extract parameter data.

A function returns execution to the calling statement when the function's last statement has executed. A value may be returned to the calling statement via the return statement. Also, a return statement anywhere else in the function's statements aborts function statement execution at that point and returns control to the calling statement (optionally with a returned value). If one branch of a conditional construction in a function returns a value, each branch, including the main branch, must also return a value, even if that value is null (IE tends to be more forgiving if you don't balance return statements, but it's good programming practice just the same).

Functions have ready access to all global variables that are defined outside of functions anywhere in the document. But variables defined inside a function (the var keyword is required) are accessible only to statements inside the function.

To reference a function object that is defined elsewhere in the document, use the function name without its parentheses. For example, to assign a function to an event handler property, the syntax is:

objReference.eventHandlerProperty = functionName;

Starting with Version 4 browsers, you may nest functions inside one another:

function myFuncA( ) {
    statements
    function myFuncB( ) {
        statements
    }
}

Nested functions (such as myFuncB) can be invoked only by statements in its next outermost function.

All functions belong to the window in which the function is defined. Therefore, if a script must access a function located in a sibling frame, the reference must include the frame and the function name:

parent.otherFrame.someFunction( )

Creating a Function

function myFunction([param1[, param2[,...paramN]]]) {
    statement(s)
}
var myFunction = new Function([param1[,...paramN], "statement1[; ...statementN;"])
objectRef.methodName = function([param1[, param2[,...paramN]]]) {
    statement(s)
}

Properties

arguments

arity

caller

constructor

length

prototype

Methods

apply( ) toString( ) call( ) valueOf( )

arguments NN 3 IE 4 ECMA 1
Read-only
Returns an arguments object that contains values passed as arguments to the function. Script statements inside the function can access the values through array syntax, which has numeric index values that correspond to incoming parameter values in the order in which they were passed. The content of the arguments array is independent of the parameter variables defined for the function. Therefore, if the function defines two parameter variables but the calling statement passes 10 parameters, the arguments array captures all 10 values in the order in which they were passed. Statements inside the function may then examine the length of the arguments array and extract values as needed. This allows one function to handle an indeterminate number of parameters if the need arises.
For most browsers, you can simply begin the reference to the object with the name of the property (e.g., arguments[2]). But some older browsers require the name of the enclosing function object, as well. All browsers recognize the longer version.

Example

function myFunc( ) for (var i = 0; i < myFunc.arguments.length; i++) { ... } }

Value

An arguments object.

arity NN 4 IE n/a ECMA n/a
Read-only
Returns an integer representing the number of parameters that are defined for the function. This property may be examined in a statement outside of the function, perhaps in preparation of parameters to be passed to the function. Returns the same value as the length property.

Example

var paramCount = myFunction.arity;

Value

Integer.

caller NN 3 IE 4 ECMA n/a
Read-only
Returns a reference to a function object that contained the statement invoking the current function. This property is readable only by script statements running in function whose caller you wish to reference. Omitted in Netscape 6.0, but back in subsequent versions.

Example

function myFunc( ) if (myFunc.caller == someFuncZ) { // process when this function is called by someFuncZ } }

Value

Function object.

constructor NN 4 IE 4 ECMA 1
Read/Write
This is a reference to the function that created the instance of a Function object—the native Function( ) constructor function in browsers.

Example

if (myVar.constructor == Function) { // process native function }

Value

Function object reference.

length NN 4 IE 4 ECMA 1
Read-only
Returns an integer representing the number of parameters that are defined for the function. This property may be examined in a statement outside of the function, perhaps in preparation of parameters to be passed to the function.

Example

var paramCount = myFunction.length;

Value

Integer.

prototype NN 3 IE 4 ECMA 1
Read/Write
This is a property of the static Function object. Use the prototype property to assign new properties and methods to future instances of functions created in the current document. See the Array.prototype property description for examples.

Example

Function.prototype.author = "DG";

Value

Any data, including function references.

apply( ) NN 6 IE 5.5(Win) ECMA 3
apply([thisObjectRef[, argumentsArray]])
Invokes the current function, optionally specifying an object to be used as the context for which any this references in the function applies. Parameters to the function (if any) are contained in array that is passed as the second parameter of the apply( ) method. The method can be used with anonymous or named functions. Usage of this method is rare, but provides flexibility that is helpful if your script should encounter a reference to a function and needs to invoke that function, particularly within an object's context.
Consider a script function that is assigned as a method of a custom object:
// function definition function myFunc(parm1, parm2, parm3) { // statements } // custom object constructor function customObj(arg1, arg2) { this.property1 = arg1; this.property2 = arg2; this.method1 = myFunc; } var myObjA = new CustomObj(val1, val2); var myObjB = new CustomObj(val3, val4);
The most common way to execute the myFunc( ) function is as a method of one of the objects:
myObjA.method1(parmValue);
But you can invoke the function from a reference to the function, and make the function believe it is being invoked through one of the objects:
myFunc.apply(myObjB, [parmVal1, parmVal2, parmVal3]);
If the function (myFunc in this example) has a statement with the this keyword in it, that term becomes a reference to the object context passed as the first parameter to the apply( ) method (myObjB in this example).

Returned Value

None.

Parameters

thisObjectRef

Reference to an object that is to act as the context for the function.

argumentsArray

An array with items that are values to be passed to the function. Array entries are passed to the function in the same order as they are organized in the array.

call( )

Platform	String value
Internet Explorer 6/Win32	`Tuesday, April 01, 2003 7:30:00 AM`
Internet Explorer 5.1/Mac	`Tuesday, 01 April, 2003 07:30:00 AM`
Navigator 6/Win32	`Tuesday, April 01, 2003 07:30:00`
Navigator 6/Mac	`Tuesday April 01 07:30:00 2003`

Platform	String Value
Internet Explorer 6/Win32	`Tue Apr 1 07:30:00 PST 2003`
Internet Explorer 5.1/Mac	`Tue Apr 1 07:30:00 PST 2003`
Navigator 6/Win32	`Tue Apr 01 07:30:00 GMT-0800 (Pacific Standard Time) 2003`
Navigator 6/Mac	`Tue Apr 01 2003 07:30:00 GMT-0800`

12.5. Core Objects

Creating an ActiveXObject

Properties

Methods

Properties

Methods

Example

Value

Example

Value

Creating an Array

Properties

Methods

Example

Value

Example

Value

Example

Value

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Creating a Boolean Object

Properties

Methods

Example

Value

Example

Value

Returned Value

Parameters

Returned Value

Parameters

Creating a Date Object

Properties

Methods

Example

Value

Example

Value

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value

Parameters

Returned Value