Search Flex Samples

FLEX Indexed arrays

Indexed arrays store a series of one or more values organized such that each value can be accessed using an unsigned integer value. The first index is always the number 0, and the index increments by 1 for each subsequent element added to the array. As the following code shows, you can create an indexed array by calling the Array class constructor or by initializing the array with an array literal:

// Use Array constructor.
var myArray:Array = new Array();
trace(myArray); // output: one,two,three

// Use Array literal.
var myArray:Array = ["one", "two", "three"];
trace(myArray); // output: one,two,three

The Array class also contains properties and methods that allow you to modify indexed arrays. These properties and methods apply almost exclusively to indexed arrays rather than associative arrays.

Indexed arrays use an unsigned 32-bit integer for the index number. The maximum size of an indexed array is 232 - 1 or 4,294,967,295. An attempt to create an array that is larger than the maximum size results in a run-time error.

An array element can hold a value of any data type. ActionScript 3.0 does not support the concept of typed arrays, which means that you cannot specify that all the elements of an array belong to a specific data type.

This section explains how to create and modify indexed arrays using the Array class, starting with how to create an array. The methods that modify arrays are grouped into three categories that cover how to insert elements, remove elements, and sort arrays. Methods in a final group treat an existing array as read-only; these methods merely query arrays. Rather than modifying an existing array, the query methods all return a new array. The section concludes with a discussion about extending the Array class.


Creating arrays

The Array constructor function can be used in three ways. First, if you call the constructor with no arguments, you get an empty array. You can use the length property of the Array class to verify that the array has no elements. For example, the following code calls the Array constructor with no arguments:

var names:Array = new Array();
trace(names.length); // output: 0

Second, if you use a number as the only parameter to the Array constructor, an array of that length is created, with each element's value set to undefined. The argument must be an unsigned integer between the values 0 and 4,294,967,295. For example, the following code calls the Array constructor with a single numeric argument:

var names:Array = new Array(3);
trace(names.length); // output: 3
trace(names[0]); // output: undefined
trace(names[1]); // output: undefined
trace(names[2]); // output: undefined

Third, if you call the constructor and pass a list of elements as parameters, an array is created, with elements corresponding to each of the parameters. The following code passes three arguments to the Array constructor:

var names:Array = new Array("John", "Jane", "David");
trace(names.length); // output: 3
trace(names[0]); // output: John
trace(names[1]); // output: Jane
trace(names[2]); // output: David

You can also create arrays with array literals or object literals. An array literal can be assigned directly to an array variable, as shown in the following example:

var names:Array = ["John", "Jane", "David"];

Inserting array elements

Three of the Array class methods--push(), unshift(), and splice()--allow you to insert elements into an 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.

Removing array elements

Three methods of the Array class--pop(), shift(), and splice()--allow you to remove elements from an array. 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. 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. The data type of the return value is Object because arrays can hold values of any data type. The splice() method returns an array containing the values removed. You can change the oceans array example so that the call to splice() assigns the 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 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 using an array's length property. If you set the length property of an 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

Sorting an array

There are three methods--reverse(), sort(), and sortOn()--that allow you to change the order of an array, either by sorting or reversing the order. All of these methods modify the existing array. The reverse() method changes the order of the array such that the last element becomes the first element, the penultimate element becomes the second element, and so on. The sort() method allows you to sort an array in a variety of predefined ways, and even allows you to create custom sorting algorithms. The sortOn() method allows you to sort an indexed array of objects that have one or more common properties that can be used as sort keys.

The reverse() method takes no parameters and does not return a value, but allows you to toggle the order of your array from its current state to the reverse order. The following example reverses the order of the oceans listed in the oceans array:

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

The sort() method rearranges the elements in an array using the default sort order. The default sort order has the following characteristics:

  • The sort is case-sensitive, which means that uppercase characters precede lowercase characters. For example, the letter D precedes the letter b.
  • The sort is ascending, which means that lower character codes (such as A) precede higher character codes (such as B).
  • The sort places identical values adjacent to each other but in no particular order.
  • The sort is string-based, which means that elements are converted to strings before they are compared (for example, 10 precedes 3 because the string "1" has a lower character code than the string "3" has).

You may find that you need to sort your array without regard to case, or in descending order, or perhaps your array contains numbers that you want to sort numerically instead of alphabetically. The sort() method has an options parameter that allows you to alter each characteristic of the default sort order. The options are defined by a set of static constants in the Array class, as shown in the following list:

  • Array.CASEINSENSITIVE: This option makes the sort disregard case. For example, the lowercase letter b precedes the uppercase letter D.
  • Array.DESCENDING: This reverses the default ascending sort. For example, the letter B precedes the letter A.
  • Array.UNIQUESORT: This causes the sort to abort if two identical values are found.
  • Array.NUMERIC: This causes numerical sorting, so that 3 precedes 10.

The following example highlights some of these options. An array named poets is created that is sorted using several different options.

var poets:Array = ["Blake", "cummings", "Angelou", "Dante"];
poets.sort(); // default sort
trace(poets); // output: Angelou,Blake,Dante,cummings

trace(poets); // output: Angelou,Blake,cummings,Dante

trace(poets); // output: cummings,Dante,Blake,Angelou

poets.sort(Array.DESCENDING | Array.CASEINSENSITIVE); // use two options
trace(poets); // output: Dante,cummings,Blake,Angelou

You can also write your own custom sort function, which you can pass as a parameter to the sort() method. For example, if you have a list of names in which each list element contains a person's full name, but you want to sort the list by last name, you must use a custom sort function to parse each element and use the last name in the sort function. The following code shows how this can be done with a custom function that is used as a parameter to the Array.sort() method:

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;
return 0;
trace(names); // output: John Q. Smith,Jane Doe,Mike Jones
trace(names); // output: Jane Doe,Mike Jones,John Q. Smith

The custom sort function orderLastName() uses a regular expression to extract the last name from each element to use for the comparison operation. The function identifier orderLastName is used as the sole parameter when calling the sort() method on the names array. The sort function accepts two parameters, a and b, because it works on two array elements at a time. The sort function's return value indicates how the elements should be sorted:

  • A return value of -1 indicates that the first parameter, a, precedes the second parameter, b.
  • A return value of 1 indicates that the second parameter, b, precedes the first, a.
  • A return value of 0 indicates that the elements have equal sorting precedence.

The sortOn() method is designed for indexed arrays with elements that contain objects. These objects are expected to have at least one common property that can be used as the sort key. The use of the sortOn() method for arrays of any other type yields unexpected results.

The following example revises the poets array so that each element is an object instead of a string. Each object holds both the poet's last name and year of birth.

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

You can use the sortOn() method to sort the array by the born property. The sortOn() method defines two parameters, fieldName and options. The fieldName argument must be specified as a string. In the following example, sortOn() is called with two arguments, "born" and Array.NUMERIC. The Array.NUMERIC argument is used to ensure that the sort is done numerically instead of alphabetically. This is a good practice even when all the numbers have the same number of digits because it ensures that the sort will continue to behave as expected if a number with fewer or more digits is later added to the array.

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

Generally, the sort() and sortOn() methods modify an array. If you wish to sort an array without modifying the existing array, pass the Array.RETURNINDEXEDARRAY constant as part of the options parameter. This option directs the methods to return a new array that reflects the sort and to leave the original array unmodified. The array returned by the methods is a simple array of index numbers that reflects the new sort order and does not contain any elements from the original array. For example, to sort the poets array by birth year without modifying the array, include the Array.RETURNINDEXEDARRAY constant as part of the argument passed for the options parameter.

The following example stores the returned index information in an array named indices and uses the indices array in conjunction with the unmodified poets array to output the poets in order of birth year:

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

Querying an array

The remaining four methods of the Array class--concat(), join(), slice(), 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 arrays 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


Related Flex Samples

Learn Flex: Flex Samples | Flex Video Tutorials Flex Examples