ACTIONSCRIPT 3 Developer’s Guide en

ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Working with arrays
songTitles[5] = "Happy Birthday";
If the Array or Vector doesn’t already have an element at that index, the index is created and the value is stored there.
If a value exists at that index, the new value replaces the existing one.
An Array object allows you to create an element at any index. However, 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;
Three of the Array and Vector class methods—push(), unshift(), and splice()—allow you to insert elements into
an indexed array. The push() method appends one or more elements to the end of an array. In other words, the last
element inserted into the array using the push() method will have the highest index number. The unshift() method
inserts one or more elements at the beginning of an array, which is always at index number 0. The splice() method
will insert any number of items at a specified index in the array.
The following example demonstrates all three methods. An array named planets is created to store the names of the
planets in order of proximity to the Sun. First, the push() method is called to add the initial item, Mars. Second, the
unshift() method is called to insert the item that belongs at the front of the array, Mercury. Finally, the splice()
method is called to insert the items Venus and Earth after Mercury, but before Mars. The first argument sent to
splice(), the integer 1, directs the insertion to begin at index 1. The second argument sent to splice(), the integer
0, indicates that no items should be deleted. Finally, the third and fourth arguments sent to splice(), Venus and
Earth, are the items to be inserted.
var planets:Array = new Array();
planets.push("Mars"); // array contents: Mars
planets.unshift("Mercury"); // array contents: Mercury,Mars
planets.splice(1, 0, "Venus", "Earth");
trace(planets); // array contents: Mercury,Venus,Earth,Mars
The push() and unshift() methods both return an unsigned integer that represents the length of the modified array.
The splice() method returns an empty array when used to insert elements, which may seem strange, but makes more
sense in light of the splice() method’s versatility. You can use the splice() method not only to insert elements into
an array, but also to remove elements from an array. When used to remove elements, the splice() method returns
an array containing the elements 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
add a new element to a fixed-length Vector using the techniques described here, an error occurs.
Retrieving values and removing array elements
Flash Player 9 and later, Adobe AIR 1.0 and later
The simplest way to retrieve the value of an element from an indexed array is to use the array access ([]) operator. To
retrieve the value of an indexed array element, use the Array or Vector object name and index number on the right
side of an assignment statement:
var myFavoriteSong:String = songTitles[3];
It’s possible to attempt to retrieve a value from an Array or Vector using an index where no element exists. In that case,
an Array object returns the value undefined and a Vector throws a RangeError exception.
Last updated 6/6/2012
31