Chapter 3 DynaScript Predefined Objects

Array object

Object

Enables the creation and manipulation of arrays.

Standard: ECMAScript

Syntax

To use an Array property:

Array.propertyName

To use an Array method:

Array.MethodName( parameter )

The Array object has both a built-in object as well as constructors that allow users to create instances of an Array object. When referring to Array in the syntax of this chapter, we are referring to an instance of an array, not the built-in Array object.

Description

Calling an array as a function or as a constructor has equivalent results--both create and initialize a new Array object.

To create an Array with a constructor:

myArray = new Array( [item0 [, item1 [, item2...]]] );

myArray = new Array( length )

It is generally more efficient to create an array with the number of elements you expect to use (or approximately), rather than growing the Array dynamically.

Example

This example creates an array, fills it, then displays the contents:

<!--SCRIPT 
myArray = new Array(4)
myArray[0]= "number one";
myArray[1]= "number two";
myArray[2]= "number three";
myArray[3]= "number four";
document.WriteLn(myArray);
-->

length property

Syntax

Array.length

Description

Returns a value one higher than the highest element in the array.

Return

Integer

Example

This example returns 7:

<!--SCRIPT
myArray = new Array();
myArray[0] = "carrots";
myArray[1] = "corn";
myArray[6] = "green beans";
document.WriteLn( myArray.length );
-->

join method

Syntax

Array.join( separator )

Description

Converts the elements of the array into strings, which are then concatenated. If no separator is given, commas separate the strings.

Return

String object

Example

This example lists the elements of the Array separated by the
"&" character:

<!--SCRIPT 
    myArray = new Array();
    myArray[0] = "carrots";
    myArray[1] = "corn";
    myArray[2] = "green beans";
    myArray[3] = "celery";
    document.WriteLn( myArray.join( " & " ) );
-->

The output from this example is:

carrots & corn & green beans & celery

reverse method

Syntax

Array.reverse( )

Description

Reverses the order of the elements in the array.

Return

Array object.

Example

This example reverses and displays the content of the myArray array:

<!--SCRIPT 
    myArray = new Array();
    myArray[0] = "carrots";
    myArray[1] = "corn";
    myArray[2] = "green beans";
    myArray[3] = "celery";
    document.WriteLn( myArray.reverse());
-->

The output from this example is:

celery & green beans & corn & carrots

sort method

Syntax

Array.sort( [compareFunction] )

Description

Sorts the elements of an array. You can use a compareFunction to sort the array or you can use the default. The compare function takes two arguments, a and b. If:

a < b The return will be negative.
a = b The return will be 0.
a > b The return will be positive.

Return

Array object

Example

This example sorts the array alphabetically and displays the results:

<!--SCRIPT 
    myArray = new Array();
    myArray[0] = "carrots";
    myArray[1] = "corn";
    myArray[2] = "green beans";
    myArray[3] = "celery";
    document.WriteLn( myArray.sort() );
-->

toString method

Syntax

Array.toString( )

Description

Converts the elements of the array to concatenated strings, separated by commas.

Return

String

Example

This example converts the array elements to strings and displays them:

<!--SCRIPT 
    myArray = new Array();
    myArray[0] = "carrots";
    myArray[1] = "corn";
    myArray[2] = "green beans";
    myArray[3] = "celery";
    document.WriteLn( myArray.toString() );
-->