Creating arrays



You can use several techniques to create an Array instance or a Vector instance. However, the techniques to create each type of array are somewhat different.

Creating an Array instance

You create an Array object by calling the Array() constructor or by using Array literal syntax.

The Array() constructor function can be used in three ways. First, if you call the constructor with no arguments, you get an empty array. You can use the length property of the Array class to verify that the array has no elements. For example, the following code calls the Array() constructor with no arguments:

var names:Array = new Array(); 
trace(names.length); // output: 0

Second, if you use a number as the only parameter to the Array() constructor, an array of that length is created, with each element’s value set to undefined . The argument must be an unsigned integer between the values 0 and 4,294,967,295. For example, the following code calls the Array() constructor with a single numeric argument:

var names:Array = new Array(3); 
trace(names.length); // output: 3 
trace(names[0]); // output: undefined 
trace(names[1]); // output: undefined 
trace(names[2]); // output: undefined

Third, if you call the constructor and pass a list of elements as parameters, an array is created, with elements corresponding to each of the parameters. The following code passes three arguments to the Array() constructor:

var names:Array = new Array("John", "Jane", "David"); 
trace(names.length); // output: 3 
trace(names[0]); // output: John 
trace(names[1]); // output: Jane 
trace(names[2]); // output: David

You can also create arrays with Array literals. An Array literal can be assigned directly to an array variable, as shown in the following example:

var names:Array = ["John", "Jane", "David"];

Creating a Vector instance

You create a Vector instance by calling the Vector.<T>() constructor. You can also create a Vector by calling the Vector.<T>() global function. That function converts a specified object to a Vector instance. ActionScript has no Vector equivalent to Array literal syntax.

Any time you declare a Vector variable (or similarly, a Vector method parameter or method return type) you specify the base type of the Vector variable. You also specify the base type when you create a Vector instance by calling the Vector.<T>() constructor. Put another way, any time you use the term Vector in ActionScript, it is accompanied by a base type.

You specify the Vector’s base type using type parameter syntax. The type parameter immediately follows the word Vector in the code. It consists of a dot ( . ), then the base class name surrounded by angle brackets ( <> ), as shown in this example:

var v:Vector.<String>; 
v = new Vector.<String>();

In the first line of the example, the variable v is declared as a Vector.<String> instance. In other words, it represents an indexed array that can only hold String instances. The second line calls the Vector() constructor to create an instance of the same Vector type (that is, a Vector whose elements are all String objects). It assigns that object to v .

Using the Vector.<T>() constructor

If you use the Vector.<T>() constructor without any arguments, it creates an empty Vector instance. You can test that a Vector is empty by checking its length property. For example, the following code calls the Vector.<T>() constructor with no arguments:

var names:Vector.<String> = new Vector.<String>(); 
trace(names.length); // output: 0

If you know ahead of time how many elements a Vector initially needs, you can pre-define the number of elements in the Vector. To create a Vector with a certain number of elements, pass the number of elements as the first parameter (the length parameter). Because Vector elements can’t be empty, the elements are filled with instances of the base type. If the base type is a reference type that allows null values, the elements all contain null . Otherwise, the elements all contain the default value for the class. For example, a uint variable can’t be null . Consequently, in the following code listing the Vector named ages is created with seven elements, each containing the value 0:

var ages:Vector.<uint> = new Vector.<uint>(7); 
trace(ages); // output: 0,0,0,0,0,0,0

Finally, using the Vector.<T>() constructor you can also create a fixed-length Vector by passing true for the second parameter (the fixed parameter). In that case the Vector is created with the specified number of elements and the number of elements can’t be changed. Note, however, that you can still change the values of the elements of a fixed-length Vector.

Unlike with the Array class, you can’t pass a list of values to the Vector.<T>() constructor to specify the Vector’s initial values.

Using the Vector.<T>() global function

In addition to the Vector.<T>() constructor, you can also use the Vector.<T>() global function to create a Vector object. The Vector.<T>() global function is a conversion function. When you call the Vector.<T>() global function you specify the base type of the Vector that the method returns. You pass a single indexed array (Array or Vector instance) as an argument. The method then returns a Vector with the specified base type, containing the values in the source array argument. The following code listing shows the syntax for calling the Vector.<T>() global function:

var friends:Vector.<String> = Vector.<String>(["Bob", "Larry", "Sarah"]);

The Vector.<T>() global function performs data type conversion on two levels. First, when an Array instance is passed to the function, a Vector instance is returned. Second, whether the source array is an Array or Vector instance the function attempts to convert the source array’s elements to values of the base type. The conversion uses standard ActionScript data type conversion rules. For example, the following code listing converts the String values in the source Array to integers in the result Vector. The decimal portion of the first value ( "1.5" ) is truncated, and the non-numeric third value ( "Waffles" ) is converted to 0 in the result:

var numbers:Vector.<int> = Vector.<int>(["1.5", "17", "Waffles"]); 
trace(numbers); // output: 1,17,0

If any of the source elements can’t be converted, an error occurs.

When code calls the Vector.<T>() global function, if an element in the source array is an instance of a subclass of the specified base type, the element is added to the result Vector (no error occurs). Using the Vector.<T>() global function is the only way to convert a Vector with base type T to a Vector with a base type that’s a superclass of T .