Defining Functions

A function definition (also called function declaration) consists of the function keyword, followed by

• The name of the function.
• A list of arguments to the function, enclosed in parentheses and separated by commas.
• The JavaScript statements that define the function, enclosed in curly braces, { }.

For example, the following code defines a simple function named square:

function square(number) {
  return number * number;
}

The function square takes one argument, called number. The function consists of one statement that indicates to return the argument of the function multiplied by itself. The return statement specifies the value returned by the function.

return number * number;

Primitive parameters are passed to functions by value; the value is passed to the function, but if the function changes the value of the parameter, this change is not reflected globally or in the calling function.

If you pass an object (i.e. a non-primitive value, such as Array or a user-defined object) as a parameter, and the function changes the object's properties, that change is visible outside the function, as shown in the following example:

function myFunc(theObject) {
  theObject.make = "Toyota";
}
var mycar = {make: "Honda", model: "Accord", year: 1998};
var x = mycar.make;     // returns Honda
myFunc(mycar);
var y = mycar.make;     // returns Toyota (prop was changed by the function)

Note that assigning a new object to the parameter will not have any effect outside the function:

function myFunc(theObject) {
  theObject = {make: "Ford", model: "Focus", year: 2006};
}
var mycar = {make: "Honda", model: "Accord", year: 1998};
var x = mycar.make;     // returns Honda
myFunc(mycar);
var y = mycar.make;     // still returns Honda

In the first case, the object mycar was passed to the function myFunc, which altered it.  In the second case, the function did not alter the object that was passed. The function creates a local variable (object) with the same name as the global (passed) so there is no effect as an outside result.

In JavaScript, a function can be defined based on a condition. For example, the following function definition defines myFunc only if num equals 0:

if (num == 0){
  function myFunc(theObject) {
    theObject.make = "Toyota"
  }
}

If num does not equal 0, the function is not defined, and any attempt to execute it will fail.

Note that ECMAScript does not allow functions to appear in such contexts such as this, only directly inside other functions or at the top level of a program, so this example is invalid as ECMAScript.

Browser implementations handle this non-standard construct differently, so it is best avoided when writing portable code.

In addition to defining functions as described here, you can also use the Function constructor to create functions from a string at runtime, much like eval.

A method is a function that is a property of an object. Read more about objects and methods in Working with Objects.

While the function declarations above are all syntactically statements, functions can also be created by a function expression. Such a function can be anonymous; it does not have to have a name. For example, the function square could have been defined as:

var square = function(number) {return number * number};

However, a name can be provided with a function expression, and can be used inside the function to refer to itself, or in a debugger to identify the function in stack traces:

var factorial = function fac(n) {return n<3 ? n : n*fac(n-1)};
print(factorial(3));

Function expressions are convenient when passing a function as an argument to another function. The following example shows the map function being defined and then called with an anonymous function as its first parameter:

function map(f,a) {
  var result = new Array;
  for (var i = 0; i != a.length; i++)
    result[i] = f(a[i]);
  return result;
}

The call

map(function(x) {return x * x * x}, [0, 1, 2, 5, 10]);

returns [0, 1, 8, 125, 1000].

Calling Functions

Defining a function does not execute it. Defining the function simply names the function and specifies what to do when the function is called. Calling the function actually performs the specified actions with the indicated parameters. For example, if you define the function square, you could call it as follows.

square(5);

The preceding statement calls the function with an argument of five. The function executes its statements and returns the value twenty-five.

Functions must be in scope when they are called, but the function declaration can be below the call, as in this example:

print(square(5));

/* ... */

function square(n){return n*n} 

The scope of a function is the function in which it is declared, or the entire program if it is declared at the top level.

The arguments of a function are not limited to strings and numbers. You can pass whole objects to a function, too. The show_props function (defined in Working with Objects) is an example of a function that takes an object as an argument.

A function can be recursive, that is, it can call itself. For example, here is a function that computes factorials:

function factorial(n){
  if ((n == 0) || (n == 1))
    return 1;
  else
    return (n * factorial(n - 1));
}

You could then compute the factorials of one through five as follows:

var a = factorial(1); // returns 1
var b = factorial(2); // returns 2
var c = factorial(3); // returns 6
var d = factorial(4); // returns 24
var e = factorial(5); // returns 120

Using the arguments object

The arguments of a function are maintained in an array-like object. Within a function, you can address the arguments passed to it as follows:

arguments[i]

where i is the ordinal number of the argument, starting at zero. So, the first argument passed to a function would be arguments[0]. The total number of arguments is indicated by arguments.length.

Using the arguments object, you can call a function with more arguments than it is formally declared to accept. This is often useful if you don't know in advance how many arguments will be passed to the function. You can use arguments.length to determine the number of arguments actually passed to the function, and then access each argument using the arguments object.

For example, consider a function that concatenates several strings. The only formal argument for the function is a string that specifies the characters that separate the items to concatenate. The function is defined as follows:

function myConcat(separator) {
   var result = ""; // initialize list
   // iterate through arguments
   for (var i = 1; i < arguments.length; i++) {
      result += arguments[i] + separator;
   }
   return result;
}

You can pass any number of arguments to this function, and it concatenates each argument into a string "list":

// returns "red, orange, blue, "
myConcat(", ", "red", "orange", "blue");

// returns "elephant; giraffe; lion; cheetah; "
myConcat("; ", "elephant", "giraffe", "lion", "cheetah");

// returns "sage. basil. oregano. pepper. parsley. "
myConcat(". ", "sage", "basil", "oregano", "pepper", "parsley");

See the Function object in the JavaScript Reference for more information.

functionName.arguments[i]

Predefined Functions

JavaScript has several top-level predefined functions:

• eval
• isFinite
• isNaN
• parseInt and parseFloat
• Number and String
• encodeURI, decodeURI, encodeURIComponent, and decodeURIComponent (all available with Javascript 1.5 and later).

The following sections introduce these functions. See the JavaScript Reference for detailed information on all of these functions.

eval(expr);

isFinite(number);

if(isFinite(ClientInput)){
   /* take specific steps */
}

isNaN(testValue);

var floatValue = parseFloat(toFloat);

if (isNaN(floatValue)) {
   notFloat();
} else {
   isFloat();
}

parseFloat(str);

parseInt(str [, radix]);

var objRef = Number(objRef);
var objRef = String(objRef);

var D = new Date(430054663215);
// The following returns
// "Thu Aug 18 04:37:43 GMT-0700 (Pacific Daylight Time) 1983"
var x = String(D);

var str = "12";
var num = Number(str);

var str = "12";
document.write(typeof str);
document.write("<br/>");
var num = Number(str);
document.write(typeof num);

escape(string);
unescape(string);