Top Level

Class Array

Object


public dynamic class Array
extends Object

Player version: Flash Player 5 — Became a native object in Flash Player 6, which improved performance significantly.

The Array class lets you access and manipulate indexed arrays. An indexed array is an object whose properties are identified by a number representing their position in the array. This number is referred to as the index. All indexed arrays are zero-based, which means that the first element in the array is [0], the second element is [1], and so on. To create an Array object, you use the constructor new Array(). To access the elements of an array, you use the array access ([]) operator.

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

Example
In the following example, my_array contains four months of the year:
var my_array:Array = new Array();
my_array[0] = "January";
my_array[1] = "February";
my_array[2] = "March";
my_array[3] = "April";




Property Summary
static CASEINSENSITIVE : Number
In the sorting methods, this constant specifies case-insensitive sorting.
static DESCENDING : Number
In the sorting methods, this constant specifies descending sort order.
length : Number
A non-negative integer specifying the number of elements in the array.
static NUMERIC : Number
In the sorting methods, this constant specifies numeric (instead of character-string) sorting.
static RETURNINDEXEDARRAY : Number
Specifies that a sort returns an indexed array as a result of calling the sort() or sortOn() method.
static UNIQUESORT : Number
In the sorting methods, this constant specifies the unique sorting requirement.

Properties inherited from class Object
__proto__, __resolve, constructor, prototype


Constructor Summary
Array([value:Object])
Lets you create an array.


Method Summary
concat([value:Object]) : Array
Concatenates the elements specified in the parameters with the elements in an array and creates a new array.
join([delimiter:String]) : String
Converts the elements in an array to strings, inserts the specified separator between the elements, concatenates them, and returns the resulting string.
pop() : Object
Removes the last element from an array and returns the value of that element.
push(value:Object) : Number
Adds one or more elements to the end of an array and returns the new length of the array.
reverse() : Void
Reverses the array in place.
shift() : Object
Removes the first element from an array and returns that element.
slice([startIndex:Number], [endIndex:Number]) : Array
Returns a new array that consists of a range of elements from the original array, without modifying the original array.
sort([compareFunction:Object], [options:Number]) : Array
Sorts the elements in an array.
sortOn(fieldName:Object, [options:Object]) : Array
Sorts the elements in an array according to one or more fields in the array.
splice(startIndex:Number, [deleteCount:Number], [value:Object]) : Array
Adds elements to and removes elements from an array.
toString() : String
Returns a string value representing the elements in the specified Array object.
unshift(value:Object) : Number
Adds one or more elements to the beginning of an array and returns the new length of the array.

Methods inherited from class Object
addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch


Property Detail

CASEINSENSITIVE Constant

public static CASEINSENSITIVE : Number

Player version: Flash Player 7

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
Array.sort(), Array.sortOn()

DESCENDING Constant

public static DESCENDING : Number

Player version: Flash Player 7

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
Array.sort(), Array.sortOn()

length Property

public length : Number

Player version: Flash Player 5

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.

Example
The following code explains how the length property is updated. The initial length is 0, and then updated to 1, 2, and 10. 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

Player version: Flash Player 7

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
Array.sort(), Array.sortOn()

RETURNINDEXEDARRAY Constant

public static RETURNINDEXEDARRAY : Number

Player version: Flash Player 7

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
Array.sort(), Array.sortOn()

UNIQUESORT Constant

public static UNIQUESORT : Number

Player version: Flash Player 7

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
Array.sort(), Array.sortOn()


Constructor Detail

Array Constructor

public Array([value:Object])

Player version: Flash Player 5

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.

Parameters
value:Object [optional] — Either:
  • An integer that specifies the number of elements in the array.
  • A list of one or more arbitrary values. The values can be of type Boolean, Number, String, Object, or Array. The first element in an array always has an index or position of 0.

Note: If only a single numeric parameter is passed to the Array constructor, it is assumed to be length and it is converted to an integer by using the Integer() function.

Example
Usage 1: The following example creates a new Array object with an initial length of 0:
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.

See also
[] array access, Array.length


Method Detail

concat Method

public concat([value:Object]) : Array

Player version: Flash Player 5

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.

Parameters
value:Object [optional] — Numbers, elements, or strings to be concatenated in a new array. If you don't pass any values, a duplicate of my_array is created.

Returns
Array — An array that contains the elements from this array followed by elements from the parameters.

Example
The following code concatenates two arrays:
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

Player version: Flash Player 5

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.

Parameters
delimiter:String [optional] — A character or string that separates array elements in the returned string. If you omit this parameter, a comma (,) is used as the default separator.

Returns
String — A string.

Example
The following example creates an array with three elements: Earth, Moon, and Sun. It then joins the array three times—first by using the default separator (a comma [,] and a space), then by using a dash (-), and then by using a plus sign (+).
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.

See also
String.split()

pop Method

public pop() : Object

Player version: Flash Player 5

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

Returns
Object — The value of the last element in the specified array.

Example
The following code creates the array myPets_array array containing four elements, and then removes its last element:
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.

See also
Array.push(), Array.shift(), Array.unshift()

push Method

public push(value:Object) : Number

Player version: Flash Player 5

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

Parameters
value:Object — One or more values to append to the array.

Returns
Number — An integer representing the length of the new array.

Example
The following example creates the array myPets_array with two elements, cat and dog. The second line adds two elements to the array.

Because the push() method returns the new length of the array, the trace() statement in the last line sends the new length of myPets_array (4) to the Output panel.

Because the push() method returns the new length of the array, the trace() statement in the last line sends the new length of myPets_array (4) to the log file.

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

See also
Array.pop(), Array.shift(), Array.unshift()

reverse Method

public reverse() : Void

Player version: Flash Player 5

Reverses the array in place.

Example
The following example uses this method to reverse the array numbers_array:
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

Player version: Flash Player 5

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

Returns
Object — The first element in an array.

Example
The following code creates the array myPets_array and then removes the first element from the array and assigns it to the variable shifted:
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.

See also
Array.pop(), Array.push(), Array.unshift()

slice Method

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

Player version: Flash Player 5

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.

Parameters
startIndex:Number [optional] — A number specifying the index of the starting point for the slice. If start is a negative number, the starting point begins at the end of the array, where -1 is the last element.
endIndex:Number [optional] — A number specifying the index of the ending point for the slice. If you omit this parameter, the slice includes all elements from the starting point to the end of the array. If end is a negative number, the ending point is specified from the end of the array, where -1 is the last element.

Returns
Array — An array that consists of a range of elements from the original array.

Example
The following example creates an array of five pets and uses slice() to populate a new array that contains only four-legged pets:
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

Player version: Flash Player 5 — Array sorting option added in Flash Player 7.

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:

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

Parameters
compareFunction:Object [optional] — A comparison function used to determine the sorting order of elements in an array. Given the elements A and B, the result of compareFunction can have one of the following three values:
  • -1, if A should appear before B in the sorted sequence
  • 0, if A equals B
  • 1, if A should appear after B in the sorted sequence
options:Number [optional] — One or more numbers or names of defined constants, separated by the | (bitwise OR) operator, that change the behavior of the sort from the default. The following values are acceptable for the options parameter:
  • Array.CASEINSENSITIVE or 1
  • Array.DESCENDING or 2
  • Array.UNIQUESORT or 4
  • Array.RETURNINDEXEDARRAY or 8
  • Array.NUMERIC or 16
For more information about this parameter, see the Array.sortOn() method.

Note: Array.sort() is defined in ECMA-262, but the array sorting options introduced in Flash Player 7 are Flash-specific extensions to the ECMA-262 specification.

Returns
Array — The return value depends on whether you pass any parameters, as described in the following list:
  • If you specify a value of 4 or Array.UNIQUESORT for the options parameter and two or more elements being sorted have identical sort fields, Flash returns a value of 0 and does not modify the array.
  • If you specify a value of 8 or Array.RETURNINDEXEDARRAY for the options parameter, Flash returns an array that reflects the results of the sort and does not modify the array.
  • Otherwise, Flash returns nothing and modifies the array to reflect the sort order.

Example
Usage 1: The following example shows the use of Array.sort() with and without a value passed for options:
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.

See also
| (bitwise OR), Array.sortOn()

sortOn Method

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

Player version: Flash Player 6 — The options parameter was added in Flash Player 7. The ability to use different options parameters on multiple sort fields was added in Flash Player 8.

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

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:

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.

Parameters
fieldName:Object — A string that identifies a field to be used as the sort value, or an array in which the first element represents the primary sort field, the second represents the secondary sort field, and so on.
options:Object [optional] — One or more numbers or names of defined constants, separated by the bitwise OR (|) operator, that change the sorting behavior. The following values are acceptable for the options parameter:

Code hinting is enabled if you use the string form of the flag (for example, DESCENDING) rather than the numeric form (2).

Returns
Array — The return value depends on whether you pass any parameters:
  • If you specify a value of 4 or Array.UNIQUESORT for the options parameter, and two or more elements being sorted have identical sort fields, a value of 0 is returned and the array is not modified.
  • If you specify a value of 8 or Array.RETURNINDEXEDARRAY for the options parameter, an array is returned that reflects the results of the sort and the array is not modified.
  • Otherwise, nothing is returned and the array is modified to reflect the sort order.

Example
The following example creates a new array and sorts it according to the name and city fields. The first sort uses name as the first sort value and city as the second. The second sort uses city as the first sort value and name as the second.
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);

See also
| (bitwise OR), Array.sort()

splice Method

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

Player version: Flash Player 5

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

Parameters
startIndex:Number — An integer that specifies the index of the element in the array where the insertion or deletion begins. You can specify a negative integer to specify a position relative to the end of the array (for example, -1 is the last element of the array).
deleteCount:Number [optional] — An integer that specifies the number of elements to be deleted. This number includes the element specified in the startIndex parameter. If no value is specified for the deleteCount parameter, the method deletes all of the values from the startIndex element to the last element in the array. If the value is 0, no elements are deleted.
value:Object [optional] — Specifies the values to insert into the array at the insertion point specified in the startIndex parameter.

Returns
Array — An array containing the elements that were removed from the original array.

Example
The following example creates an array and splices it by using element index 1 for the startIndex parameter. This removes all elements from the array starting with the second element, leaving only the element at index 0 in the original 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

Player version: Flash Player 5

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.

Returns
String — A string.

Example
The following example creates my_array and converts it to a 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.

This example outputs 1,2,3,4,5 as a result of the trace statement.

This example writes 1,2,3,4,5 to the log file.

See also
String.split(), Array.join()

unshift Method

public unshift(value:Object) : Number

Player version: Flash Player 5

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

Parameters
value:Object — One or more numbers, elements, or variables to be inserted at the beginning of the array.

Returns
Number — An integer representing the new length of the array.

Example
The following example shows the use of the Array.unshift() method:
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.

See also
Array.pop(), Array.push(), Array.shift()