Indexed 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.

The most basic way to add an element to an indexed array is to use the array access ( [] ) operator. To set the value of an indexed array element, use the Array or Vector object name and index number on the left side of an assignment statement:

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.

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.

Three methods of the Array and Vector classes— pop() , shift() , and splice() —allow you to remove elements. The pop() method removes an element from the end of the array. In other words, it removes the element at the highest index number. The shift() method removes an element from the beginning of the array, which means that it always removes the element at index number 0. The splice() method, which can also be used to insert elements, removes an arbitrary number of elements starting at the index number specified by the first argument sent to the method.

The following example uses all three methods to remove elements from an Array instance. An Array named oceans is created to store the names of large bodies of water. Some of the names in the Array are lakes rather than oceans, so they need to be removed.

First, the splice() method is used to remove the items Aral and Superior , and insert the items Atlantic and Indian . The first argument sent to splice() , the integer 2, indicates that the operation should start with the third item in the list, which is at index 2. The second argument, 2, indicates that two items should be removed. The remaining arguments, Atlantic and Indian , are values to be inserted at index 2.

Second, the pop() method is used to remove last element in the array, Huron . And third, the shift() method is used to remove the first item in the array, Victoria .

var oceans:Array = ["Victoria", "Pacific", "Aral", "Superior", "Indian", "Huron"]; 
oceans.splice(2, 2, "Arctic", "Atlantic"); // replaces Aral and Superior 
oceans.pop(); // removes Huron 
oceans.shift(); // removes Victoria 
trace(oceans);// output: Pacific,Arctic,Atlantic,Indian

The pop() and shift() methods both return the item that was removed. For an Array instance, the data type of the return value is Object because arrays can hold values of any data type. For a Vector instance, the data type of the return value is the base type of the Vector. The splice() method returns an Array or Vector containing the values removed. You can change the oceans Array example so that the call to splice() assigns the returned Array to a new Array variable, as shown in the following example:

var lakes:Array = oceans.splice(2, 2, "Arctic", "Atlantic"); 
trace(lakes); // output: Aral,Superior

You may come across code that uses the delete operator on an Array object element. The delete operator sets the value of an Array element to undefined , but it does not remove the element from the Array. For example, the following code uses the delete operator on the third element in the oceans Array, but the length of the Array remains 5:

var oceans:Array = ["Arctic", "Pacific", "Victoria", "Indian", "Atlantic"]; 
delete oceans[2]; 
trace(oceans);// output: Arctic,Pacific,,Indian,Atlantic 
trace(oceans[2]); // output: undefined 
trace(oceans.length); // output: 5

You can truncate an Array or Vector using an array’s length property. If you set the length property of an indexed array to a length that is less than the current length of the array, the array is truncated, removing any elements stored at index numbers higher than the new value of length minus 1. For example, if the oceans array were sorted such that all valid entries were at the beginning of the array, you could use the length property to remove the entries at the end of the array, as shown in the following code:

var oceans:Array = ["Arctic", "Pacific", "Victoria", "Aral", "Superior"]; 
oceans.length = 2; 
trace(oceans); // output: Arctic,Pacific

There are three methods— reverse() , sort() , and sortOn() —that allow you to change the order of an indexed array, either by sorting or reversing the order. All of these methods modify the existing array. The following table summarizes these methods and their behavior for Array and Vector objects:

var oceans:Array = ["Arctic", "Atlantic", "Indian", "Pacific"]; 
oceans.reverse(); 
trace(oceans); // output: Pacific,Indian,Atlantic,Arctic

var poets:Array = ["Blake", "cummings", "Angelou", "Dante"]; 
poets.sort(); // default sort 
trace(poets); // output: Angelou,Blake,Dante,cummings 
 
poets.sort(Array.CASEINSENSITIVE); 
trace(poets); // output: Angelou,Blake,cummings,Dante 
 
poets.sort(Array.DESCENDING); 
trace(poets); // output: cummings,Dante,Blake,Angelou 
 
poets.sort(Array.DESCENDING | Array.CASEINSENSITIVE); // use two options 
trace(poets); // output: Dante,cummings,Blake,Angelou

var names:Array = new Array("John Q. Smith", "Jane Doe", "Mike Jones"); 
function orderLastName(a, b):int 
{ 
    var lastName:RegExp = /\b\S+$/; 
    var name1 = a.match(lastName); 
    var name2 = b.match(lastName); 
    if (name1 < name2) 
    { 
        return -1; 
    } 
    else if (name1 > name2) 
    { 
        return 1; 
    } 
    else 
    { 
        return 0; 
    } 
} 
trace(names); // output: John Q. Smith,Jane Doe,Mike Jones 
names.sort(orderLastName); 
trace(names); // output: Jane Doe,Mike Jones,John Q. Smith

var poets:Array = new Array(); 
poets.push({name:"Angelou", born:"1928"}); 
poets.push({name:"Blake", born:"1757"}); 
poets.push({name:"cummings", born:"1894"}); 
poets.push({name:"Dante", born:"1265"}); 
poets.push({name:"Wang", born:"701"});

poets.sortOn("born", Array.NUMERIC); 
for (var i:int = 0; i < poets.length; ++i) 
{ 
    trace(poets[i].name, poets[i].born); 
} 
/* output: 
Wang 701 
Dante 1265 
Blake 1757 
cummings 1894 
Angelou 1928 
*/

var indices:Array; 
indices = poets.sortOn("born", Array.NUMERIC | Array.RETURNINDEXEDARRAY); 
for (var i:int = 0; i < indices.length; ++i) 
{ 
    var index:int = indices[i]; 
    trace(poets[index].name, poets[index].born); 
} 
/* output: 
Wang 701 
Dante 1265 
Blake 1757 
cummings 1894 
Angelou 1928 
*/

Four methods of the Array and Vector classes— concat() , join() , slice() , and toString() —all query the array for information, but do not modify the array. The concat() and slice() methods both return new arrays, while the join() and toString() methods both return strings. The concat() method takes a new array or list of elements as arguments and combines it with the existing array to create a new array. The slice() method has two parameters, aptly named startIndex and an endIndex , and returns a new array containing a copy of the elements “sliced” from the existing array. The slice begins with the element at startIndex and ends with the element just before endIndex . That bears repeating: the element at endIndex is not included in the return value.

The following example uses concat() and slice() to create new arrays using elements of other arrays:

var array1:Array = ["alpha", "beta"]; 
var array2:Array = array1.concat("gamma", "delta"); 
trace(array2); // output: alpha,beta,gamma,delta 
 
var array3:Array = array1.concat(array2); 
trace(array3); // output: alpha,beta,alpha,beta,gamma,delta 
 
var array4:Array = array3.slice(2,5); 
trace(array4); // output: alpha,beta,gamma

You can use the join() and toString() methods to query the array and return its contents as a string. If no parameters are used for the join() method, the two methods behave identically—they return a string containing a comma-delimited list of all elements in the array. The join() method, unlike the toString() method, accepts a parameter named delimiter , which allows you to choose the symbol to use as a separator between each element in the returned string.

The following example creates an Array called rivers and calls both join() and toString() to return the values in the Array as a string. The toString() method is used to return comma-separated values ( riverCSV ), while the join() method is used to return values separated by the + character.

var rivers:Array = ["Nile", "Amazon", "Yangtze", "Mississippi"]; 
var riverCSV:String = rivers.toString(); 
trace(riverCSV); // output: Nile,Amazon,Yangtze,Mississippi 
var riverPSV:String = rivers.join("+"); 
trace(riverPSV); // output: Nile+Amazon+Yangtze+Mississippi

One issue to be aware of with the join() method is that any nested Array or Vector instances are always returned with comma-separated values, no matter what separator you specify for the main array elements, as the following example shows:

var nested:Array = ["b","c","d"]; 
var letters:Array = ["a",nested,"e"];  
var joined:String = letters.join("+"); 
trace(joined); // output: a+b,c,d+e