FunctionNN 2   IE J1   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.

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

In Navigator 4, 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[; ...statement2"])
obj.MethodName = function([param1[, param2[,...paramN]]]) {
    statement(s)
}
argumentsNN 3   IE J2   ECMA 1
 Read-only
 

Returns an array of values passed as arguments to the function. The content of the 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.

 
Example
function myFunc()
    for (var i = 0; i < myFunc.arguments.length; i++) {
        ...
    }
}
 
Value
Array of values of any JavaScript data type.
arityNN 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.

 
Example
var paramCount = myFunction.arity
 
Value
Integer.
callerNN 3   IE J2   ECMA n/a
 Read-only
 

Returns a reference to a function object that contained the statement invoking the current function.

 
Example
function myFunc()
    if (myFunc.caller == someFuncZ) {
        process for this function being called by someFuncZ
    }
}
 
Value
Function object.
lengthNN 4   IE J3   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. Navigator always returns a value of zero (see the arity property).

 
Example
var paramCount = myFunction.length
 
Value
Integer.
prototypeNN 3   IE J2   ECMA 1
 Read/Write
 

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.
toString()NN 4   IE J3   ECMA 1

Returns the object's value (script statement listing and function wrapper) as a string data type. You don't need this method in practice because the browsers automatically convert values to strings when they are needed for display in alert dialogs or in-document rendering.

 
Returned Value
String.
 
Parameters
None.
valueOf()NN 4   IE J3   ECMA 1

Returns the object's value.

 
Returned Value
A function object reference.
 
Parameters
None.