Programming with the Vector class

An array is like a container for grouping together a set of variables. A single array can contain many different values. You can store and access individual values contained in the array (known as the array's elements). You can also work with the values as a group by manipulating the array variable directly. The most common type of array is an indexed array, which uses a number index to select from among the array's values. ActionScript 3 includes two classes that serve as indexed arrays:

• Array class: An indexed array whose elements can be values of any type, including mixing types of values in the same array.
• Vector class: An indexed array whose elements must all be instances of the same class. The Vector class is available with Adobe Flash Player 10 and later.

If you need to store a collection of values that all have the same data type, the Vector class has a few benefits over the Array class. First of all, because all the elements of a Vector must have the same data type, the ActionScript compiler can check the data type when the code is compiled. Any code that attempts to add or retrieve a value of the wrong type can be caught at compile-time. Data types are also checked at runtime, so in cases where the data type can't be checked at compile-time, it is still checked and the data type restriction is still enforced. In addition to the type-checking benefit, code that uses the Vector class runs significantly faster than equivalent code that uses the Array class—a noteworthy benefit.

This Quick Start describes techniques for creating and working with the Vector class. To learn more about the Array class, see Programming with the Array class.

The following sections describe common tasks for working with Vector objects: creating a Vector instance, adding values to a Vector object, retrieving values from a Vector object, and sorting values in a Vector object.

A Vector object is an indexed array that stores only values of one class. The class that a particular Vector object stores is known as the Vector's base type. You specify a base type when you declare a Vector variable and also when you create a Vector object by calling the Vector class's constructor. As you might expect, the base class specified for a Vector variable must match the base type specified when calling the constructor.

When creating a Vector instance, to specify its base type you add extra information to the Vector class name using a format known as type parameter syntax. For example, the following statement declares a Vector variable named myVector, using type parameter syntax to specify that the Vector stored in myVector can contain only String values:

You use the same syntax when you call the Vector class constructor to actually create the Vector object:

As a rule, whenever the class name Vector appears in your code, you always use a type parameter with it.

Of course, you can combine the actions of declaring a variable and constructing an instance into one line of code:

Although the examples in this Quick Start mostly use simple built-in classes such as String and Number, the base type of a Vector can be any class. This includes custom classes that you define. For example, suppose your code defines a class named MyClass. In that case, the following code is valid and creates a Vector object whose elements must all be MyClass instances:

The Vector class constructor has two optional parameters that enable you to specify characteristics of your Vector instance. The first parameter is the length parameter. By default, a Vector is empty when it is created (it has 0 elements). However, if you pass a value for the length parameter, the Vector is instantiated with the specified number of elements already created:

Prespecifying the size of the Vector is faster than creating elements one at a time, so if you know ahead of time how many elements a Vector will contain, it is better to provide a length parameter value. If the base type of the Vector is Boolean or one of the numeric types (Number, int, uint), each element is prepopulated with the default value for its data type (false for Boolean, 0 for numeric types). Otherwise, each element initially contains the value null.

Another feature of Vector objects is that they can be fixed-length, meaning you can change values but can't change the total number of values by adding or removing them. By default, a Vector instance is not fixed-length. To create a fixed-length Vector, specify true for the second parameter (the fixed parameter) of the Vector class constructor:

Note: You can change the value of a Vector object's fixed property at any time to make a Vector fixed-length or remove the fixed-length restriction from a Vector:

Adding a value to a Vector object is similar to adding a value to an Array object, with one additional restriction. A Vector object must have a value (or null) for every element. In other words, you can't add a value at index position 4 unless the Vector already has values at indices 0–3. In practice, this means that to add a new element to a Vector, you must add it at the index position equal to the Vector object's length property. (Because the first element of a Vector has index 0, the length property's value is always one greater than the index of the last element in the Vector.) The following code listing demonstrates this technique:

In addition to using the array access ([]) operator to add a value to a Vector object, you can use the Vector object's push() or unshift() methods to add elements to the Vector. Just as with the Array class, the push() method creates a new element after the last element in a Vector, and the unshift() method creates a new element at index 0 of the Vector (and shifts all the existing elements one index position higher):

These methods have the additional advantage that you can pass multiple values as arguments to the method, and all the values are added to the Vector at once. However, there is a consequence of this flexibility. When you use the push() or unshift() method to add a value to a Vector, the compiler isn't able to check that the data types of the values match. Consequently, any code that uses push() or unshift() to add a value of the wrong type to the Vector won't be caught until you run the code.

Retrieving a value from a Vector object is identical to retrieving a value from an Array object. To retrieve the value of an element at a particular index, you just use the array access ([]) operator to specify the index of the element you want:

Using the array access ([]) operator retrieves the value, but doesn't remove it from the Vector object. To retrieve a value and remove it from the Vector, use the pop() method (which removes the final element) or the shift() method (which removes element 0 and shifts all the elements down one position):

Most parts of working with a Vector object are identical to working with an Array object. One way that they're notably different is in sorting the elements of a Vector. The Vector class only has one method for sorting values: the sort() method. The sort() method doesn't modify the original Vector object. Instead, it returns a new Vector with the same base type, containing the values in sorted order.

When you use the Vector class's sort() method, there is no default sorting behavior, not even for basic data types such as Number or String. Because of this, anytime you use the sort() method, you specify a custom sorting function that defines the sorting logic. For example, in the following code a Vector of Number objects is sorted using the sort() method. In this case, the code performs a basic numeric sort; lesser numbers are placed before greater numbers. The function that defines the sorting behavior, named sortNumbers(), is passed as an argument to the sort() method call. As Flash Player sorts each number, it calls the sortNumbers() function, passing in two numbers being compared, and the result determines the final sort order:

You can define a sorting function for any data type. For example, the following code sorts a Vector of Person objects by last name, then first name (it assumes there is a Person class that has firstName and lastName properties):

You can download the sample archive, programming_with_vector.zip, from the top of this page. This sample includes the following files:

• SortVectorOfNumber.fla and SortVectorOfNumber_CS5.fla (Flash CS5 version): A Flash Professional file demonstrating sorting Number values in a Vector, as described in "Sorting values in a Vector instance" in this Quick Start.
• SortVectorOfObject.fla and SortVectorOfObject_CS5.fla (Flash CS5 version): An example demonstrating sorting custom objects in a Vector, as described in "Sorting values in a Vector instance" in this Quick Start.
• Person.as: Source code for the Person class, referenced in SortVectorOfObject.fla.

To test each application, open the FLA file and choose Control > Test Movie.

You can find all the details of the Vector class in the following entries in the ActionScript 3.0 Reference for the Adobe Flash Platform:

• Vector class
• Vector.<T>() conversion function

Related Flash Quick Starts

• Embedding fonts
• Loading images and Library assets in Flash with ActionScript 3
• Loading and saving local files with the FileReference class
• Event handling
• Display list programming
• Creating a simple ActionScript 3 class
• Working with symbols and the Document class
• Programming with arrays