A non-negative integer specifying the number of elements in the array. This property is automatically updated when new elements are added to the array. When you assign a value to an array element (for example, my_array[index] = value), if index is a number, and index+1 is greater than the length property, the length property is updated to index+1.

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

Lets you create an array. You can use the constructor to create different types of arrays: an empty array, an array with a specific length but whose elements have undefined values, or an array whose elements have specific values.

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.

See also

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.

Concatenates the elements specified in the parameters with the elements in an array and creates a new array. If the value parameters specify an array, the elements of that array are concatenated, rather than the array itself. The array my_array is left unchanged.

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

Converts the elements in an array to strings, inserts the specified separator between the elements, concatenates them, and returns the resulting string. A nested array is always separated by a comma (,), not by the separator passed to the join() method.

See also

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.

Removes the last element from an array and returns the value of that element.

See also

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.

Adds one or more elements to the end of an array and returns the new length of the array.

See also

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

Reverses the array in place.

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.

Removes the first element from an array and returns that element.

See also

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.

Returns a new array that consists of a range of elements from the original array, without modifying the original array. The returned array includes the startIndex element and all elements up to, but not including, the endIndex element.

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.

Sorts the elements in an array. Flash sorts according to Unicode values. (ASCII is a subset of Unicode.)

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

See also

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.

Sorts the elements in an array according to one or more fields in the array. The array should have the following characteristics:

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

See also

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

Adds elements to and removes elements from an array. This method modifies the array without making a copy.

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

Returns a string value representing the elements in the specified Array object. Every element in the array, starting with index 0 and ending with the highest index, is converted to a concatenated string and separated by commas. To specify a custom separator, use the Array.join() method.

See also

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.

Adds one or more elements to the beginning of an array and returns the new length of the array.

See also

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.

In the sorting methods, this constant specifies case-insensitive sorting. You can use this constant for the options parameter in the sort() or sortOn() method.

The value of this constant is 1.

See also

In the sorting methods, this constant specifies descending sort order. You can use this constant for the options parameter in the sort() or sortOn() method.

The value of this constant is 2.

See also

In the sorting methods, this constant specifies numeric (instead of character-string) sorting. Including it in the options parameter causes the sort() and sortOn() methods to sort numbers as numeric values, not as strings of numeric characters. Without the NUMERIC constant, sorting treats each array element as a character string and produces the results in Unicode order.

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.

See also

Specifies that a sort returns an indexed array as a result of calling the sort() or sortOn() method. You can use this constant for the options parameter in the sort() or sortOn() method. This provides preview or copy functionality by returning an array that represents the results of the sort and leaves the original array unmodified.

The value of this constant is 8.

See also

In the sorting methods, this constant specifies the unique sorting requirement. You can use this constant for the options parameter in the sort() or sortOn() method. The unique sorting option aborts the sort if any two elements or fields being sorted have identical values.

The value of this constant is 4.

See also