Working with vectors

Adobe AIR 1.5 and later

A Vector instance is a typed array , which means that all the elements in a Vector instance always have the same data type. Some AIR APIs, such as NativeProcess and NetworkInfo, use Vectors as data types for properties or methods.

In JavaScript code running in Adobe AIR, the Vector class is referenced as air.Vector (in the AIRAliases.js file).

Basics of 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.

Important concepts and terms

The following reference list contains important terms to know when programming array and vector handling routines:

Array access ([]) operator
A pair of square brackets surrounding an index or key that uniquely identifies an array element. This syntax is used after a vector variable name to specify a single element of the vector rather than the entire vector.

Base type
The data type of the objects that a Vector instance is allowed to store.

A single item in a vector.

The numeric “address” used to identify a single element in an indexed array.

The standard convention that’s used in this documentation to represent the base type of a Vector instance, whatever that base type happens to be. The T convention is used to represent a class name, as shown in the Type parameter description. (“T” stands for “type,” as in “data type.”).

Type parameter
The syntax that’s used with the Vector class name to specify the Vector’s base type (the data type of the objects that it stores). The syntax consists of a period ( . ), then the data type name surrounded by angle brackets ( <> ). Put together, it looks like this: Vector.<T> . In this documentation, the class specified in the type parameter is represented generically as T .

A type of array whose elements are all instances of the same data type.

Creating vectors

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);

Inserting elements into a vector

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.

Note: If a Vector object’s fixed property is true , the total number of elements in the Vector can’t change. If you try to add a new element to a fixed-length Vector using the push() method or other means, an error occurs.

Retrieving values and removing vector elements

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("green pepper"); 
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.

Note: If a Vector object’s fixed property is true , the total number of elements in the Vector can’t change. If you try to remove an element from or truncate a fixed-length Vector using the techniques described here, an error occurs.

Properties and methods of Vector objects

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.

Example: Using AIR APIs that require vectors

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.

Accessing AIR APIs that return vector objects

The findInterfaces() method of the NetworkInfo class returns an array of NetworkInterface objects. For example, the following code lists the computer’s network interfaces:

var netInfo = air.NetworkInfo; 
var interfaces = netInfo.findInterfaces(); 
for (i = 0; i < interfaces.length; i++) 
    air.trace(" hardware address: ", interface.hardwareAddress); 

You iterate through the vector of NetworkInfo objects just as you would iterate through an array. You use a for loop and use square brackets to access indexed elements of the vector.

The interfaces property of the NetworkInterface object is a vector of InterfaceAddress objects. The following code extends the previous example, adding a function to enumerate interface addresses for each network interface:

var netInfo = air.NetworkInfo; 
var interfaces = netInfo.findInterfaces(); 
for (i = 0; i < interfaces.length; i++) 
    air.trace(" hardware address: ", interface.hardwareAddress); 
    air.trace(" addresses: ", traceAddresses(i); 
function traceAddresses(i) 
    returnString = new String(); 
    for (j = 0; j < interfaces[i].addresses.length; j++) 
        returnString += interfaces[i],addresses[j].address + " "; 

Setting AIR APIs that are vectors

The arguments property NativeProcessStartupInfo class is a vector of strings. To set this property, create a vector of strings using the air.Vector() constructor. You can use the push() method to add strings to the vector:

var arguments = new air.Vector["<String>"](); 
var startupInfo = new air.NativeProcessStartupInfo(); 
startupInfo.arguments = arguments; 
startupInfo.executable = File.applicationDirectory.resolvePath("myApplication.exe"); 
process = new air.NativeProcess(); 

For more information on using the native process API, see “Communicating with Native Processes” in Networking and communication .

// Ethnio survey code removed