Flash 8 ActionScript 2.0 Language Reference

Class Array

Object

You can store a wide variety of data types in an array element, including numbers, strings, objects, and even other arrays. You can create a multidimensional array by creating an indexed array and assigning to each of its elements a different indexed array. Such an array is considered multidimensional because it can be used to represent data in a table.

Array assignment is by reference rather than by value: when you assign one array variable to another array variable, both refer to the same array:

var oneArray:Array = new Array("a", "b", "c");
var twoArray:Array = oneArray; // Both array variables refer to the same array.
twoArray[0] = "z";             
trace(oneArray);               // Output: z,b,c.

The Array class should not be used to create associative arrays, which are different data structures that contain named elements instead of numbered elements. You should use the Object class to create associative arrays (also called hashes). Although ActionScript permits you to create associative arrays using the Array class, you can not use any of the Array class methods or properties. At its core, an associative array is an instance of the Object class, and each key-value pair is represented by a property and its value. Another reason to declare an associative array using the Object data type is that you can then use an object literal to populate your associative array (but only at the time you declare it). The following example creates an associative array using an object literal, accesses items using both the dot operator and the array access operator, and then adds a new key-value pair by creating a new property:

var myAssocArray:Object = {fname:"John", lname:"Public"};
trace(myAssocArray.fname);     // Output: John
trace(myAssocArray["lname"]);  // Output: Public
myAssocArray.initial = "Q";
trace(myAssocArray.initial);   // Output: Q

var my_array:Array = new Array();
my_array[0] = "January";
my_array[1] = "February";
my_array[2] = "March";
my_array[3] = "April";

CASEINSENSITIVE Constant

public static CASEINSENSITIVE : Number

The value of this constant is 1.

DESCENDING Constant

public static DESCENDING : Number

The value of this constant is 2.

length Property

public length : Number

Note: If you assign a value to the length property that is shorter than the existing length, the array will be truncated.

var my_array:Array = new Array();
trace(my_array.length); // initial length is 0
my_array[0] = "a";
trace(my_array.length); // my_array.length is updated to 1
my_array[1] = "b";
trace(my_array.length); // my_array.length is updated to 2
my_array[9] = "c";
trace(my_array.length); // my_array.length is updated to 10
trace(my_array); 
// displays: 
// a,b,undefined,undefined,undefined,undefined,undefined,undefined,undefined,c

// if the length property is now set to 5, the array will be truncated
my_array.length = 5; 
trace(my_array.length); // my_array.length is updated to 5
trace(my_array); // outputs: a,b,undefined,undefined,undefined

NUMERIC Constant

public static NUMERIC : Number

For example, given the Array of values [2005, 7, 35], if the NUMERIC constant is not included in the options parameter, the sorted Array is [2005, 35, 7], but if the NUMERIC constant is included, the sorted Array is [7, 35, 2005].

Note that this constant only applies to numbers in the array; it does not apply to strings that contain numeric data (such as ["23", "5"]).

The value of this constant is 16.

RETURNINDEXEDARRAY Constant

public static RETURNINDEXEDARRAY : Number

The value of this constant is 8.

UNIQUESORT Constant

public static UNIQUESORT : Number

The value of this constant is 4.

Array Constructor

public Array([value:Object])

Usage 1: If you don't specify any parameters, an array with a length of 0 is created.

Usage 2: If you specify only a length, an array is created with length number of elements. The value of each element is set to undefined.

Usage 3: If you use the element parameters to specify values, an array is created with specific values.

var my_array:Array = new Array();
trace(my_array.length); // Traces 0.

Usage 2: The following example creates a new Array object with an initial length of 4:

var my_array:Array = new Array(4);
trace(my_array.length); // Returns 4.
trace(my_array[0]); // Returns undefined.
if (my_array[0] == undefined) { // No quotation marks around undefined.
    trace("undefined is a special value, not a string");
} // Traces: undefined is a special value, not a string.

Usage 3: The following example creates the new Array object go_gos_array with an initial length of 5:

var go_gos_array:Array = new Array("Belinda", "Gina", "Kathy", "Charlotte", "Jane");
trace(go_gos_array.length); // Returns 5.
trace(go_gos_array.join(", ")); // Displays elements.

The initial elements of the go_gos_array array are identified, as shown in the following example:

go_gos_array[0] = "Belinda";
go_gos_array[1] = "Gina";
go_gos_array[2] = "Kathy";
go_gos_array[3] = "Charlotte";
go_gos_array[4] = "Jane";

The following code adds a sixth element to the go_gos_array array and changes the second element:

go_gos_array[5] = "Donna";
go_gos_array[1] = "Nina"
trace(go_gos_array.join(" + "));
// Returns Belinda + Nina + Kathy + Charlotte + Jane + Donna.

concat Method

public concat([value:Object]) : Array

var alpha_array:Array = new Array("a","b","c");
var numeric_array:Array = new Array(1,2,3);
var alphaNumeric_array:Array =alpha_array.concat(numeric_array); 
trace(alphaNumeric_array);
// Creates array [a,b,c,1,2,3].

The following code concatenates three arrays:

var num1_array:Array = [1,3,5];
var num2_array:Array = [2,4,6];
var num3_array:Array = [7,8,9];
var nums_array:Array=num1_array.concat(num2_array,num3_array) 
trace(nums_array);
// Creates array [1,3,5,2,4,6,7,8,9].

Nested arrays are not flattened in the same way as normal arrays. The elements in a nested array are not broken into separate elements in array x_array, as shown in the following example:

var a_array:Array = new Array ("a","b","c");

// 2 and 3 are elements in a nested array.
var n_array:Array = new Array(1, [2, 3], 4); 

var x_array:Array = a_array.concat(n_array);
trace(x_array[0]); // a
trace(x_array[1]); // b
trace(x_array[2]); // c
trace(x_array[3]); // 1
trace(x_array[4]); // 2, 3 
trace(x_array[5]); // 4

join Method

public join([delimiter:String]) : String

var a_array:Array = new Array("Earth","Moon","Sun")
trace(a_array.join()); 
// Displays Earth,Moon,Sun.
trace(a_array.join(" - ")); 
// Displays Earth - Moon - Sun.
trace(a_array.join(" + ")); 
// Displays Earth + Moon + Sun.

The following example creates a nested array that contains two arrays. The first array has three elements: Europa, Io, and Callisto. The second array has two elements: Titan and Rhea. It joins the array by using a plus sign (+), but the elements within each nested array remain separated by commas (,).

var a_nested_array:Array = new Array(["Europa", "Io", "Callisto"], ["Titan", "Rhea"]);
trace(a_nested_array.join(" + "));
// Returns Europa,Io,Callisto + Titan,Rhea.

pop Method

public pop() : Object

var myPets_array:Array = new Array("cat", "dog", "bird", "fish");
var popped:Object = myPets_array.pop();
trace(popped); // Displays fish.
trace(myPets_array); // Displays cat,dog,bird.

push Method

public push(value:Object) : Number

var myPets_array:Array = new Array("cat", "dog");
var pushed:Number = myPets_array.push("bird", "fish");
trace(pushed); // Displays 4.

reverse Method

public reverse() : Void

var numbers_array:Array = new Array(1, 2, 3, 4, 5, 6);
trace(numbers_array); // Displays 1,2,3,4,5,6.
numbers_array.reverse();
trace(numbers_array); // Displays 6,5,4,3,2,1.

shift Method

public shift() : Object

var myPets_array:Array = new Array("cat", "dog", "bird", "fish");
var shifted:Object = myPets_array.shift();
trace(shifted); // Displays "cat".
trace(myPets_array); // Displays dog,bird,fish.

slice Method

public slice([startIndex:Number], [endIndex:Number]) : Array

If you don't pass any parameters, a duplicate of the original array is created.

var myPets_array:Array = new Array("cat", "dog", "fish", "canary", "parrot");
var myFourLeggedPets_array:Array = new Array();
var myFourLeggedPets_array = myPets_array.slice(0, 2);
trace(myFourLeggedPets_array);  // Returns cat,dog.
trace(myPets_array);  // Returns cat,dog,fish,canary,parrot.

The following example creates an array of five pets, and then uses slice() with a negative start parameter to copy the last two elements from the array:

var myPets_array:Array = new Array("cat", "dog", "fish", "canary", "parrot");
var myFlyingPets_array:Array = myPets_array.slice(-2);
trace(myFlyingPets_array); // Traces canary,parrot.

The following example creates an array of five pets and uses slice() with a negative end parameter to copy the middle element from the array:

var myPets_array:Array = new Array("cat", "dog", "fish", "canary", "parrot");
var myAquaticPets_array:Array = myPets_array.slice(2,-2);
trace(myAquaticPets_array); // Returns fish.

sort Method

public sort([compareFunction:Object], [options:Number]) : Array

By default, Array.sort() works as described in the following list:

• Sorting is case-sensitive (Z precedes a).
• Sorting is ascending (a precedes b).
• The array is modified to reflect the sort order; multiple elements that have identical sort fields are placed consecutively in the sorted array in no particular order.
• Numeric fields are sorted as if they were strings, so 100 precedes 99, because "1" is a lower string value than "9".

If you want to sort an array by using settings that deviate from the default settings, you can either use one of the sorting options described in the entry for the options parameter or you can create your own custom function to do the sorting. If you create a custom function, you can use it by calling the sort() method, using the name of your custom function as the first parameter (compareFunction).

var fruits_array:Array = new Array("oranges", "apples", "strawberries", "pineapples", "cherries");
trace(fruits_array);  // Displays oranges,apples,strawberries,pineapples,cherries.
fruits_array.sort();
trace(fruits_array);  // Displays apples,cherries,oranges,pineapples,strawberries.
trace(fruits_array);  // Writes apples,cherries,oranges,pineapples,strawberries.
fruits_array.sort(Array.DESCENDING);
trace(fruits_array);  // Displays strawberries,pineapples,oranges,cherries,apples.
trace(fruits_array);  // Writes strawberries,pineapples,oranges,cherries,apples.

Usage 2: The following example uses Array.sort() with a compare function. The entries are sorted in the form name:password. Sort using only the name part of the entry as a key:

var passwords_array:Array = new Array("mom:glam", "ana:ring", "jay:mag", "anne:home", "regina:silly");
function order(a, b):Number {
    var name1:String = a.split(":")[0];
    var name2:String = b.split(":")[0];
    if (name1<name2) {
    return -1;
    } else if (name1>name2) {
    return 1;
    } else {
    return 0;
    }
}
trace("Unsorted:");
//Displays Unsorted:
trace(passwords_array);
//Displays mom:glam,ana:ring,jay:mag,anne:home,regina:silly.
//Writes mom:glam,ana:ring,jay:mag,anne:home,regina:silly
passwords_array.sort(order);
trace("Sorted:");
//Displays Sorted:
trace(passwords_array);
//Displays ana:ring,anne:home,jay:mag,mom:glam,regina:silly.
//Writes ana:ring,anne:home,jay:mag,mom:glam,regina:silly.

sortOn Method

public sortOn(fieldName:Object, [options:Object]) : Array

• The array is an indexed array, not an associative array.
• Each element of the array holds an object with one or more properties.
• All of the objects have at least one property in common, the values of which can be used to sort the array. Such a property is called a field.

If you pass multiple fieldName parameters, the first field represents the primary sort field, the second represents the next sort field, and so on. Flash sorts according to Unicode values. (ASCII is a subset of Unicode.) If either of the elements being compared does not contain the field that is specified in the fieldName parameter, the field is assumed to be undefined, and the elements are placed consecutively in the sorted array in no particular order.

By default, Array.sortOn() works in the following way:

• Sorting is case-sensitive (Z precedes a).
• Sorting is ascending (a precedes b).
• The array is modified to reflect the sort order; multiple elements that have identical sort fields are placed consecutively in the sorted array in no particular order.
• Numeric fields are sorted as if they were strings, so 100 precedes 99, because "1" is a lower string value than "9".

Flash Player 7 added the options parameter, which you can use to override the default sort behavior. To sort a simple array (for example, an array with only one field), or to specify a sort order that the options parameter doesn't support, use Array.sort().

To pass multiple flags, separate them with the bitwise OR (|) operator:

my_array.sortOn(someFieldName, Array.DESCENDING | Array.NUMERIC);

Flash Player 8 added the ability to specify a different sorting option for each field when you sort by more than one field. In Flash Player 8, the options parameter accepts an array of sort options such that each sort option corresponds to a sort field in the fieldName parameter. The following example sorts the primary sort field, a, using a descending sort; the secondary sort field, b, using a numeric sort; and the tertiary sort field, c, using a case-insensitive sort:

Array.sortOn (["a", "b", "c"], [Array.DESCENDING, Array.NUMERIC, Array.CASEINSENSITIVE]);

Note: The fieldName and options arrays must have the same number of elements; otherwise, the options array is ignored. Also, the Array.UNIQUESORT and Array.RETURNINDEXEDARRAY options can be used only as the first element in the array; otherwise, they are ignored.

var rec_array:Array = new Array();
rec_array.push({name: "john", city: "omaha", zip: 68144});
rec_array.push({name: "john", city: "kansas city", zip: 72345});
rec_array.push({name: "bob", city: "omaha", zip: 94010});
for(i=0; i<rec_array.length; i++){
    trace(rec_array[i].name + ", " + rec_array[i].city);
}
// Results:
// john, omaha
// john, kansas city
// bob, omaha

rec_array.sortOn(["name", "city"]);
for(i=0; i<rec_array.length; i++){
    trace(rec_array[i].name + ", " + rec_array[i].city);
}
// Results:
// bob, omaha
// john, kansas city
// john, omaha

rec_array.sortOn(["city", "name" ]);
for(i=0; i<rec_array.length; i++){
    trace(rec_array[i].name + ", " + rec_array[i].city);
}
// Results:
// john, kansas city
// bob, omaha
// john, omaha

The following array of objects is used by the remaining examples, which show how to use the options parameter:

var my_array:Array = new Array();
my_array.push({password: "Bob", age:29});
my_array.push({password: "abcd", age:3});
my_array.push({password: "barb", age:35});
my_array.push({password: "catchy", age:4});

Performing a default sort on the password field produces the following results:

my_array.sortOn("password");
// Bob
// abcd
// barb
// catchy

Performing a case-insensitive sort on the password field produces the following results:

my_array.sortOn("password", Array.CASEINSENSITIVE);
// abcd
// barb
// Bob
// catchy

Performing a case-insensitive, descending sort on the password field produces the following results:

my_array.sortOn("password", Array.CASEINSENSITIVE | Array.DESCENDING);
// catchy
// Bob
// barb
// abcd

Performing a default sort on the age field produces the following results:

my_array.sortOn("age");
// 29
// 3
// 35
// 4

Performing a numeric sort on the age field produces the following results:

my_array.sortOn("age", Array.NUMERIC);
// my_array[0].age = 3
// my_array[1].age = 4
// my_array[2].age = 29
// my_array[3].age = 35

Performing a descending numeric sort on the age field produces the following results:

my_array.sortOn("age", Array.DESCENDING | Array.NUMERIC);
// my_array[0].age = 35
// my_array[1].age = 29
// my_array[2].age = 4
// my_array[3].age = 3

When you use the Array.RETURNEDINDEXARRAY sorting option, you must assign the return value to a different array. The original array is not modified.

var indexArray:Array = my_array.sortOn("age", Array.RETURNINDEXEDARRAY);

splice Method

public splice(startIndex:Number, [deleteCount:Number], [value:Object]) : Array

var myPets_array:Array = new Array("cat", "dog", "bird", "fish");
trace( myPets_array.splice(1) ); // Displays dog,bird,fish.
trace( myPets_array ); // cat

The following example creates an array and splices it by using element index 1 for the startIndex parameter and the number 2 for the deleteCount parameter. This removes two elements from the array, starting with the second element, leaving the first and last elements in the original array:

var myFlowers_array:Array = new Array("roses", "tulips", "lilies", "orchids");
trace( myFlowers_array.splice(1,2 ) ); // Displays tulips,lilies.
trace( myFlowers_array ); // roses,orchids

The following example creates an array and splices it by using element index 1 for the startIndex parameter, the number 0 for the deleteCount parameter, and the string chair for the value parameter. This does not remove anything from the original array, and adds the string chair at index 1:

var myFurniture_array:Array = new Array("couch", "bed", "desk", "lamp");
trace( myFurniture_array.splice(1,0, "chair" ) ); // Displays empty array. 
trace( myFurniture_array ); // displays couch,chair,bed,desk,lamp

toString Method

public toString() : String

var my_array:Array = new Array();
my_array[0] = 1;
my_array[1] = 2;
my_array[2] = 3;
my_array[3] = 4;
my_array[4] = 5;
trace(my_array.toString()); // Displays 1,2,3,4,5.

unshift Method

public unshift(value:Object) : Number

var pets_array:Array = new Array("dog", "cat", "fish");
trace( pets_array ); // Displays dog,cat,fish.
pets_array.unshift("ferrets", "gophers", "engineers");
trace( pets_array ); // Displays ferrets,gophers,engineers,dog,cat,fish.