Working with vectors

When you declare a Vector variable or instantiate a Vector object, you explicitly specify the data type of the objects that the Vector can contain. The specified data type is known as the Vector’s base type . At run time, any code that sets or retrieves a value of a Vector is checked. If the data type of the object being added or retrieved doesn’t match the Vector’s base type, an error occurs.

In addition to the data type restriction, the Vector class has other restrictions that distinguish it from the Array class:

• A Vector is a dense array. An Array object may have values in indices 0 and 7 even if it has no values in positions 1 through 6. However, a Vector must have a value (or null ) in each index.

• A Vector can optionally be fixed length. This means that the number of elements the Vector contains can’t change.

• Access to a Vector’s elements is bounds-checked. You can never read a value from an index greater than the final element ( length - 1). You can never set a value with an index more than one beyond the current final index. (In other words, you can only set a value at an existing index or at index [length] .)

As a result of its restrictions, a Vector has three primary benefits over an Array instance whose elements are all instances of a single class:

• Performance: array element access and iteration are much faster when using a Vector instance than when using an Array instance.

• Type safety: examples of such errors include assigning a value of the incorrect data type to a Vector or expecting the wrong data type when reading a value from a Vector. At run time, data types are checked when adding data to or reading data from a Vector object.

• Reliability: run-time range checking (or fixed-length checking) increases reliability significantly over Arrays.

Aside from the additional restrictions and benefits, the Vector class is very much like the Array class. The properties and methods of a Vector object are similar—usually identical—to the properties and methods of an Array. In most situations where you would use an Array in which all the elements have the same data type, a Vector instance is preferable.

You create a Vector instance by calling the air.Vector["<T>"]() constructor. When you call this constructor, you specify the base type of the Vector variable. 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 left bracket, then a string containing the base class name surrounded by angle brackets ( <> ), followed by a right bracket. This example shows this syntax:

var v = new air.Vector["<String>"]();

In this example, the variable v is declared as a vector of String objects. In other words, it represents an indexed array that can only hold String instances.

If you use the air.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 = new air.Vector["<String>"](); 
air.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 Number variable can’t be null . Consequently, in the following code listing the Vector named ages is created with three elements, each containing the default Number value NaN :

var ages = new air.Vector["<Number>"](3); 
air.trace(ages); // output: NaN, NaN, NaN

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.

If you create a Vector of AIR runtime objects (classes defined in the window.runtime object), reference the class’s fully qualified ActionScript 3.0 name when calling the Vector constructor. For example, the following code creates a Vector of File objects:

var files = new air.Vector["flash.filesystem.File"](3);

The most basic way to add an element to vector is to use the array access ( [] ) operator:

songTitles[5] = "Happy Birthday";

If the Vector doesn’t already have an element at that index, the index is created and the value is stored there.

With a Vector object, you can only assign a value to an existing index or to the next available index. The next available index corresponds to the Vector object’s length property. The safest way to add a new element to a Vector object is to use code like this listing:

myVector[myVector.length] = valueToAdd;

As with arrays, three of the Vector class methods— push() , unshift() , and splice() —allow you to insert elements into a vector.

The simplest way to retrieve the value of an element from vector is to use the array access ( [] ) operator. To retrieve the value of an vector element, use the vector object name and index number on the right side of an assignment statement:

var myFavoriteSong = songTitles[3];

It’s possible to attempt to retrieve a value from a vector using an index where no element exists. In that case, a Vector throws a RangeError exception.

Three methods of the Array and Vector classes— pop() , shift() , and splice() —allow you to remove elements.

var vegetables = new air.Vector["<String>"]; 
vegetables.push("spinach"); 
vegetables.push("green pepper"); 
vegetables.push("cilantro"); 
vegetables.push("onion"); 
var spliced = vegetables.splice(2, 2); 
air.trace(spliced); // output: spinach,green pepper

You can truncate a vector using the length property.

If you set the length property of a vector to a length that is less than the current length of the vector, the vector is truncated. Any elements stored at index numbers higher than the new value of length minus 1 are removed.

Many of the same methods and properties of Array objects are available for vector object. For example, you can call the reverse() method to change the order of elements of a Vector. You can call the sort() method to sort the elements of a Vector. However, the Vector class does not include a sortOn() method.

For details on supported properties and methods, see the Vector class documentation in the Adobe AIR Language Reference for HTML Developers.

Some Adobe AIR runtime classes use vectors as properties or method return values. For example, the findInterfaces() method of the NetworkInfo class returns an array of NetworkInterface objects. The arguments property NativeProcessStartupInfo class is a vector of strings.