Array Object

Provides support for expando arrays of any data type. There are three forms of the Array constructor.

function Array( [size : int] )
function Array( [... varargs : Object[]] ) 
function Array( [array : System.Array )

Arguments

  • size
    Optional. The size of the array. As arrays are zero-based, created elements will have indexes from zero to size -1.

  • varargs
    Optional. A typed array that contains all the parameters passed to the constructor. These parameters are used as the first elements of the array.

  • array
    Optional. An array to be copied to the array being constructed.

Remarks

If only one argument is passed to the Array constructor and the argument is a number, it must be an unsigned 32-bit integer (any integer less than approximately four billion). The passed value is the size of the array. If the value is a number that is less than zero or is not an integer, a run-time error occurs.

A variable of data type System.Array can be passed to the Array constructor. This produces a JScript array that is a copy of the input array. The System.Array must have only one dimension.

If a single value is passed to the Array constructor and it is not a number or an array, the length property of the array is set to 1, and the value of the first element of the array (element 0) becomes the single, passed-in argument. If several arguments are passed to the constructor, the length of the array is set to the number of arguments, and those arguments will be the first elements in the new array.

Notice that JScript arrays are sparse arrays; that is, although you can allocate an array with many elements, only the elements that actually contain data exist. This reduces the amount of memory used by the array.

The Array object interoperates with System.Array data type. Consequently, an Array object can call the methods and properties of the System.Array data type, and a System.Array data type can call the methods and properties of the Array object. Furthermore, Array objects are accepted by functions that take System.Array data types, and vice versa. For more information, see Array Members.

When an Array object is passed to a function that takes a System.Array or when System.Array methods are called from an Array object, the contents of the Array are copied. Thus, the original Array object cannot be modified by the System.Array methods or by passing it to a function that accepts a System.Array. Only nondestructive Array methods can be called on a System.Array.

Tip

Array objects are convenient when you want a generic stack or a list of items and performance is not a top concern. In all other contexts, typed array data types should be used. A typed array, which has much of the same functionality as the Array object, also helps provide type safety, performance improvements, and better interaction with other languages.

Note

The Array object interoperates with the .NET Framework System.Array data type within JScript. However, other Common Language Specification (CLS) languages cannot use the Array object because only JScript provides the object; it is not derived from a .NET Framework type. Consequently, when type-annotating the parameters and return types of CLS-compliant methods, make sure to use the System.Array data type instead of the Array object. However, you may use the Array object to type annotate identifiers other than the parameters or return types. For more information, see Writing CLS-Compliant Code.

Example

The individual elements of the array can be accessed using [ ] notation. For example:

var my_array = new Array();
for (var i = 0; i < 10; i++) {
   my_array[i] = i;
}
var x = my_array[4];

Since arrays in Microsoft JScript are zero-based, the final statement in the preceding example accesses the fifth element of the array. That element contains the value 4.

Properties and Methods

Array Object Properties and Methods

Requirements

Version 2

See Also

Reference

new Operator

Concepts

Typed Arrays