Javascript Function Statement


Function Statement

Description

Declares a new function.

Syntax

function functionname([argument1 [, argument2 [, ...argumentn]]])
{
   statements
}

The function statement syntax has the following parts:

Part Description
functionname The name of the function.
argument1...argumentn An optional, comma-separated list of arguments the function understands.
statements One or more JScript statements.
Remarks

Use the function statement to declare a function for later use. The code contained in statements is not executed until the function is called from elsewhere in the script.

The following example illustrates the use of the function statement: 

function myfunction(arg1, arg2)
{
  var r;
  r = arg1 * arg2;
  return(r);
}

arguments Property

Description

Returns an array containing each argument passed to the currently executing function.

Syntax

function.arguments[ ]

The function argument is the name of the currently executing function.

Remarks

The arguments property allows a graceful way for functions to handle a variable number of arguments. The length property of the array contains the number of arguments passed to the function.

The following example illustrates the use of the arguments property: 

function ArgTest()
{
   var i, s, numargs = ArgTest.arguments.length;
   s = numargs;  
   if (numargs < 2)
     s += " argument was passed to ArgTest. It was ";
   else
     s += " arguments were passed to ArgTest. They were " ;
   
   for (i = 0; i < numargs; i++)
     {
       s += ArgTest.arguments[i] + " ";
     }
   return(s);
}

length Property (Array)
Description

Returns an integer value one higher than the highest element defined in an array.

Syntax

numVar = arrayObj.length

Remarks

As the elements in an array do not have to be contiguous, the length property is not necessarily the number of elements in the array. For example, in the following array definition, my_array.length contains 7, not 2: 

var my_array = new Array( );
my_array[0] = "Test";
my_array[6] = "Another Test";

If a value smaller than its previous value is assigned to the length property, the array is truncated, and any elements with array indexes equal to or greater than the new value of the length property are lost.

If a value larger than its previous value is assigned to the length property, the array is expanded, and any new elements created have the value undefined.

The following example illustrates the use of the length property: 

function LengthDemo()
{
  var a, l;
  a = new Array(0,1,2,3,4);
  l = a.length;
  return(l);
}
new Operator
Description

Creates a new object.

Syntax

new constructor[(arguments)]

The constructor argument calls object's constructor. The parentheses can be omitted if the constructor takes no arguments.

Remarks

The new operator performs the following tasks:

  1. It creates an object with no members.
  2. It calls the constructor for that object, passing a pointer to the newly created object as the this pointer.

The constructor then initializes the object according to the arguments passed to the constructor.

These are examples of valid uses of the new operator: 

my_object = new Object;
my_array = new Array();
my_date = new Date("Jan 5 1996");
length Property (Function)
Description

Returns the number of arguments defined for a function.

Syntax

functionname.length

The functionname argument is required and is the name of the function in question.

Remarks

The length property of a function is initialized by the scripting engine to the number of arguments in the function's definition when an instance of the function is created.

What happens when a function is called with a number of arguments different from the value of its length property depends on the function.

The following example illustrates the use of the length property: 

function ArgTest(a, b)
{
   var i, s = "The ArgTest function expected ";
   var numargs = ArgTest.arguments.length;
   var expargs = ArgTest.length;
   if (expargs < 2)
     s += expargs + " argument. ";
   else
     s += expargs + " arguments. ";
   if (numargs < 2)
     s += numargs + " was passed.";
   else
     s += numargs + " were passed.";
   return(s);
}

caller Property

Description

Returns a reference to the function that invoked the current function.

Syntax

functionname.caller

Remarks

The caller property is only defined for a function while that function is executing. If the function is called from the top level of a JScript program, caller contains null.

If the caller property is used in a string context, the result is the same as functionname.toString, that is, the decompiled text of the function is displayed.

The following example illustrates the use of the caller property: 

function CallLevel()
{
  if (CallLevel.caller == null)
    return("CallLevel was called from the top level.");
  else
    return("CallLevel was called by another function.");
}