Function Arguments: The Arguments Object (JavaScript: The Definitive Guide, 4th Edition)

7.4. Function Arguments: The Arguments Object

Within the body of a function, the identifier arguments always has special meaning. arguments is a special property of the call object that refers to an object known as the Arguments object. The Arguments object is like an array that allows the argument values passed to the function to be retrieved by number, but it is not actually an Array object. The Arguments object also defines an additional callee property, described later.

Although a JavaScript function is defined with a fixed number of named arguments, it can be passed any number of arguments when it is invoked. The arguments[] array allows full access to these argument values, even when some are unnamed. Suppose you define a function f that expects to be passed one argument, x. If you invoke this function with two arguments, the first argument is accessible within the function by the parameter name x or as arguments[0]. The second argument is accessible only as arguments[1]. Furthermore, like all arrays, arguments has a length property that specifies the number of elements it contains. Thus, within the body of our function f, invoked with two arguments, arguments.length has the value 2.

The arguments[] array is useful in a number of ways. The following example shows how 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 number of arguments were passed
    if (arguments.length != 3) {
        throw new Error("function f called with " + arguments.length +
                        "arguments, but it expects 3 arguments.");
    }
    // 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. Here's an example that shows how you can write a simple max( ) function that accepts any number of arguments and returns the value of the largest argument it is passed (see also the built-in function Math.max( ), which in ECMAScript v3 also accepts any number of arguments):

function max( )
{
    var m = Number.NEGATIVE_INFINITY;

    // Loop through all the arguments, looking for, and
    // remembering, the biggest
    for(var i = 0; i < arguments.length; i++)
        if (arguments[i] > m) m = arguments[i];
    // Return the biggest
    return m;
}

var largest = max(1, 10, 100, 2, 3, 1000, 4, 5, 10000, 6);

You can also use the arguments[] array to write functions that expect a fixed number of named arguments followed by an arbitrary number of unnamed arguments.

Throughout this section we've been referring to the "arguments array." Keep in mind, however, that arguments is not really an array; it is an Arguments object. Each Arguments object defines numbered array elements and a length property, but it is not technically an array -- it is better to think of it as an object that happens to have some numbered properties. The ECMAScript specification does not require the Arguments object to implement any of the special behavior that arrays do. Although you can assign a value to the arguments.length property, for example, ECMAScript does not require you to do so to actually alter the number of array elements defined in the object. (See Chapter 9 for an explanation of the special behavior of the length property of true Array objects.)

The Arguments object has one very unusual feature. When a function has named arguments, the array elements of the Arguments object are synonyms for the local variables that hold the function arguments. The arguments[] array and the argument named arguments are two different ways of referring to the same variable. Changing the value of an argument with an argument name changes the value that is retrieved through the arguments[] array. Changing the value of an argument through the arguments[] array changes the value that is retrieved by the argument name. For example:

function f(x) {
    alert(x);             // Displays the initial value of the argument
    arguments[0] = null;  // Changing the array element also changes x
    alert(x);             // Now displays "null"
}

7.4.1. The callee Property

In addition to its array elements, the Arguments object defines a callee property that refers to the function that is currently being executed. This is useful, for example, to allow unnamed functions to invoke themselves recursively. For instance, here is an unnamed function literal that computes factorials:

function(x) {
    if (x <= 1) return 1;
    return x * arguments.callee(x-1);
}

The callee property is defined by ECMAScript v1 and implemented in JavaScript 1.2.