The arguments[] Array

The arguments[] property of a Function object refers to an array that contains the complete set of argument values passed to the function for the current invocation. JavaScript allows any number of argument values to be passed to any function, regardless of the number of argument names that appear in the function definition. If you define a function named f with a single argument named x, then within the function, the value of the argument x is the same as f.arguments[0]. If you invoke this function and pass it two arguments instead of just one, then the second argument won't have a name within the function but will be available as f.arguments[1]. Like most arrays, the arguments[] array has a length property that specifies the number of elements. Thus, for a function f, f.arguments.length specifies the number of argument values that were passed for the current invocation.

The arguments[] array is useful in a number of ways. As Example 6.3 shows, you can use it to check that a function is invoked with the correct number of arguments, since JavaScript doesn't do this for you.

function f(x, y, z)
{
    // first, check that the right # of arguments were passed.
    if (f.arguments.length != 3) {
        alert("function f called with " + f.arguments.length +
              "arguments, but it expects 3 arguments.");
        return null;
    }
    // now do the actual function...
}

The arguments[] array also opens up an important possibility for JavaScript functions: they can be written so that they work with any number of arguments. Example 6.4 shows how you can write a max() function that accepts any number of arguments and returns the value of the largest argument it is passed.

function max() 
{
    var m = -Number.MAX_VALUE; // Navigator 3.0 only. In 2.0 use -1.79E+308
    // loop through all the arguments, looking for, and
    // remembering, the biggest.
    for(var i = 0; i < max.arguments.length; i++)
        if (max.arguments[i] > m) m = max.arguments[i];
    // return the biggest.
    return m;
}
var largest = max(1, 10, 100, 2, 3, 1000, 4, 5, 10000, 6);

You can also write functions that have some named arguments, followed by some unnamed arguments. Example 6.5 shows such a function; it is a constructor function that creates an array, initializes a size property as specified by a named argument len, and then initializes an arbitrary number of elements, starting with element 1, of the array to the values of any additional arguments. (JavaScript programs in Navigator 2.0 often use a function like this, as seen in Chapter 8, Arrays.)

function InitializedArray(len)
{
    this.size = len;  // In 2.0, this sets array element 0.
    for (var i = 1; i < InitializedArray.arguments.length; i++) 
        this[i] = InitializedArray.arguments[i];
}

A final note about the arguments[] array: the arguments property of a Function object actually holds a copy of the Function object itself. In other words, if f is a function, and F is the corresponding Function object, then each of the following lines of code refers to the same thing:

f.arguments
F.arguments
F
F.arguments.arguments.arguments

The caller Property

The other property of the Function object is caller. This property is a reference to the function (the function value itself, not the Function object wrapper) that invoked the current one. If the function was invoked from the top level of the script, rather than from a function, then this property will be null. Because caller is a reference to a function value, you can do anything with it that you can do with any other function reference. You can call it, or pass it to other functions, causing a kind of recursion.

Unfortunately, since the caller property refers to a function that is not the currently executing function, you cannot inspect the arguments or caller property of the function referred to by the caller property. That is, the following JavaScript expressions evaluate to null:

f.caller.caller          // doesn't work
f.caller.arguments[1]    // doesn't work

The Function() Constructor

We said in Chapter 4, Expressions and Operators that the new operator is used to create new objects; this operator is used with a special "constructor function" that specifies the type of object to create. Many JavaScript object types define constructor functions that can be used to create objects of that type. The Function object type is no exception--it provides the Function() constructor which allows us to create new Function objects. This constructor works in Navigator 3.0, but not in Internet Explorer 3.0. It will be implemented in a future version of IE.

The Function() constructor provides a technique for defining functions without using the function keyword. You can create a new Function object with the Function() constructor like this:

var f = new Function("x", "y", "return x*y;");

function f(x, y) { return x*y; }

The Function() constructor expects any number of string arguments. The last argument in the list becomes the body of the function--it can contain arbitrary JavaScript statements, separated from each other with semicolons. All other arguments to the Function() constructor are strings that specify the names of the arguments to the function being defined. If you are defining a function that takes no arguments, then you simply pass a single string--the function body--to the constructor.

There are a couple of reasons you might want to use the Function() constructor. Recall that the function keyword defines a variable, just like the var does. So the first reason to use the Function() constructor is to avoid having to give your function a temporary variable name when you are just going to immediately assign it to an object property (making a method of that object, as we'll see in Chapter 7, Objects). For example, consider the following two lines of code:

function tmp_area() { return Math.PI * this.radius * this.radius; }
Circle.area = tmp_area

Circle.area = new Function("return Math.PI * this.radius * this.radius;");

Another reason you might want to use the Function() constructor is to define temporary or "anonymous" functions that are never given a name. Recall the Array.sort() method mentioned earlier in this chapter: it takes a function as an argument, and that function defines how the elements of the array are sorted. Strings and numbers already have a well-defined sort order, but suppose we were trying to sort an array of objects each of which represented a complex number. To do this, we might use the magnitude of the number, or its overall "distance" from the origin as the value which we would compare to do the sort. It is simple enough to write an appropriate function to perform this comparison, but if we only plan to sort this array of complex number objects once, we might not want to bother defining the function with the function keyword and giving it a permanent name. Instead, we might simply use code like the following to dynamically create a Function object and pass it to the sort() method without ever giving it a name. (Recall that just as JavaScript automatically converts primitive types to their corresponding wrapper objects, so too does it convert in the other direction. So the Function object created in the example will be automatically converted to a function value appropriate for the sort() method.

complex_nums.sort(
       new Function("a", "b",
                    "Math.sqrt(a.x*a.x+a.y*a.y)-Math.sqrt(b.x*b.x+b.y*b.y);"));

The only difference between functions defined with the function keyword and those defined with the Function() constructor has to do with how they are printed. (Try it! Use document.write() or alert().) When a function is printed (or otherwise converted to a string) the function name, arguments, and body are displayed, along with the function keyword. The result of converting a function to a string is a string that contains a legal JavaScript function definition. When a function is defined with function, it is given a name as part of the function definition syntax, and this name appears when the function is printed. Functions defined with Function(), however, do not have a name, and so are printed with the name "anonymous". For this reason, functions defined in this way are sometimes referred to as "anonymous functions".

Function Properties

There are several interesting facts about functions that you should be aware of. You can combine these facts into a useful programming technique.

function f() { alert('hello world!'); }
f.i = 3;

var i = f.i + 2;

n = 1;       // A number
n.i = 2;     // Convert it to a Number object and give that object a property
typeof n.i   // This tells us n.i is undefined; the property is transient.

function f(x)
{
   var y = 3;         // a local variable
   return f.x + f.y;  // refer to the argument and variable as properties    
}

result = f(2);        // returns 5

typeof f.x      // yields "undefined"
typeof f.y      // yields "undefined"

function count()
{
    // counter is a static variable, defined below.
    // Note that we use it just like a local variable.
    alert("You've called me " + counter + " time(s).");
    // Increment the static variable. This incremented value
    // will be retained and will be used the next time we are called.
    counter++;
}
// To define the static variable, just set it as a property of the function:
// Note that the only shortcoming of this technique is that static
// variables can only be defined after they are used in the function.
count.counter = 1;