arguments.length 101
arguments.length
Availability
Flash Player 5.
Usage
arguments.length:Number
Description
Property; the number of parameters actually passed to a function.
Example
The following ActionScript includes a function called
getArgLength
, which returns the number
of arguments that are passed into the function. Although the method expects three arguments,
you can pass as many arguments as you want.
function getArgLength(param_arg1:String, param_arg2:String, param_arg3:String)
{
return (arguments.length);
}
trace(getArgLength("one", "two", "three")); // output: 3
trace(getArgLength("one", "two")); // output: 2
trace(getArgLength("one", "two", "three", "four")); // output: 4
In the following example, the function called
listSum
adds the values passed to it and returns the
sum. The function uses a
for
loop to examine each argument passed. If the value is a number, the
value is added to the
sum
variable. At the end of the function, the value of
sum

using the Array class’s
push
method:
var myArray:Array = Array();
myArray.push(12);
trace(myArray); //traces 12
myArray[4] = 7;
trace(myArray); //traces 12,undefined,undefined,undefined,7
Usage 2: The following example creates an array of length 4 but with no elements defined:
var myArray:Array = Array(4);
trace(myArray.length); // traces 4
trace(myArray); // traces undefined,undefined,undefined,undefined
Usage 3: The following example creates an array with three defined elements:
var myArray:Array = Array(["firstElement", "secondElement", "thirdElement"]);
trace (myArray); // traces firstElement,secondElement,thirdElement
Note: Unlike the Array class constructor, the Array() function does not use the keyword new.
See also
Array class
CHAPTER 2
ActionScript Language Reference
Array class 103
Array class
Availability
Flash Player 5 (became a native object in Flash Player 6, which improved
performance significantly).
Description
The Array class lets you access and manipulate arrays. An 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 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

Extracts a section of an array and returns it as a new array.
Array.sort()
Sorts an array in place.
Array.sortOn()
Sorts an array according to a field in the array.
Array.splice()
Adds and removes elements from an array.
Array.toString()
Returns a string value representing the elements in the Array object.
Array.unshift()
Adds one or more elements to the beginning of an array and returns the array’s
new length.
Property Description
Array.length
A non-negative integer specifying the number of elements in the array.
CHAPTER 2
ActionScript Language Reference
104 Chapter 2: ActionScript Language Reference
Constructor for the Array class
Availability
Flash Player 5.
Usage
new Array() : Array
new Array(length:Number) : Array
new Array(element0, element1, element2,...elementN) : Array
Parameters
length
An integer that specifies the number of elements in the array.
element0...elementN
A list of two or more arbitrary values. The values can be of type

trace("undefined is a special value, not a string");
} // traces: undefined is a special value, not a string
Array class 105
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.length, [] (array access)
106 Chapter 2: ActionScript Language Reference

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
Array.join() 107
Array.join()
Availability
Flash Player 5.
Usage
my_array.join([separator:String]) : String
Parameters
separator
A character or string that separates array elements in the returned string. If you omit

108 Chapter 2: ActionScript Language Reference
Array.length
Availability
Flash Player 5.
Usage
my_array.length:Number
Description
Property; 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:
var my_array:Array = new Array();

its last element:
var myPets_array:Array = new Array("cat", "dog", "bird", "fish");
var popped:String = myPets_array.pop();
trace(popped); // displays fish
trace(myPets_array); // displays cat,dog,bird
See Also
Array.push(), Array.shift(), Array.unshift()
110 Chapter 2: ActionScript Language Reference
Array.push()
Availability
Flash Player 5.
Usage
my_array.push(value,...) : Number
Parameters
value
One or more values to append to the array.
Returns
An integer representing the length of the new array.
Description
Method; adds one or more elements to the end of an array and returns the array’s new length.
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()

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
112 Chapter 2: ActionScript Language Reference
Array.shift()
Availability
Flash Player 5.
Usage
my_array.shift() : Object
Parameters
None.
Returns
The first element in an array.
Description
Method; removes the first element from an array and returns that element.
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:String = myPets_array.shift();
trace(shifted); // displays "cat"
trace(myPets_array); // displays dog,bird,fish
See also
Array.pop(), Array.push(), Array.unshift()
Array.slice() 113

Example
The following example creates an array of five pets and uses
slice()
to populate a new array
comprising 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
114 Chapter 2: ActionScript Language Reference
Array.sort()

•
1 or
Array.CASEINSENSITIVE
•
2 or
Array.DESCENDING
•
4 or
Array.UNIQUESORT
•
8 or
Array.RETURNINDEXEDARRAY

•
16 or
Array.NUMERIC
For information on this parameter, see Array.sortOn().
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
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
option
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

If you want to specify one or more fields on which to sort, using either the default sort or the
options
parameter, use Array.sortOn().
Example
Usage 1: The following example shows the use of
Array.sort()
with and without a value passed
for
option
:
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
fruits_array.sort(Array.DESCENDING);
trace(fruits_array); // displays
strawberries,pineapples,oranges,cherries,apples
Usage 2: The following example uses
Array.sort()
with a compare function:
var passwords_array:Array = new Array("mom:glam", "ana:ring", "jay:mag",
"anne:home", "regina:silly");
function order(a, b):Number {
//Entries to be sorted are in form name:password
//Sort using only the name part of the entry as a key.
var name1:String = a.split(":")[0];
var name2:String = b.split(":")[0];

option |... ) : Array
Note: Where brackets ([]) are shown, you must include them in the code; that is, the brackets don’t
represent optional parameters.
Parameters
fieldName
A string that identifies a field (in an element of the Array) to be used as the
sort value.
option
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
option
:
•
1 or
Array.CASEINSENSITIVE

•
2 or
Array.DESCENDING
•
4 or
Array.UNIQUESORT
•
8 or
Array.RETURNINDEXEDARRAY

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.
118 Chapter 2: ActionScript Language Reference
By default,
Array
.
sortOn()
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”.
You can use the
option
flags to override these defaults. The following examples use different
forms of the
option
flag for illustration purposes. If you want to sort a simple array (for example,
an array with only one field), or if you want to specify a sort order that the
options

// Bob
// catchy
Performing a case-insensitive, descending sort on the password field produces the following
results:
my_array.sortOn("password", 1|2);
// catchy
// Bob
Array.sortOn() 119
// 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", 16);
// 3
// 4
// 29
// 35
Performing a descending numeric sort on the age field produces the following results:
my_array.sortOn("age", 18);
// 35
// 29
// 4
// 3
Performing a sort changes the elements in the array produces the following results:
// Before sorting

and
city
: 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

,
the method deletes all the values from the
start
element to the last element in the array. If the
value is 0, no elements are deleted.
value
An optional parameter that specifies the values to insert into the array at the insertion
point specified in the
start
parameter.
Returns
The elements that were removed from the array.
Description
Method; adds and removes elements from an array. This method modifies the array without
making a copy.
Example
The following example creates an array and splices it using element index 1 for the
start

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) ); // dog,bird,fish
trace( myPets_array ); // cat
The following example creates an array and splices it using element index 1 for the
start

parameter and the number 2 for the
deleteCount
parameter. This removes two elements from

A string.
Description
Method; returns a String value representing the elements in the specified Array object. Every
element in the array, starting with index 0 and ending with index
my_array.length-1
, is
converted to a concatenated string and separated by commas. To specify a custom separator, use
Array.join().
Example
The following example creates
my_array
and

converts it to a string:
The following example creates
my_array
, converts it to a string, and outputs 1,2,3,4,5 as a result
of the
trace
statement:
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
See Also
Array.join(),
String.split()

function
An identifier for a function.
parameter
A string that is passed to the function named in the
function
parameter.
Returns
Nothing.
Description
Protocol; a special protocol for URLs in HTML text fields. In HTML text fields, text can be
linked using the HTML
A
tag. The
HREF
attribute of the
A
tag contains a URL that can be for a
standard protocol such as HTTP, HTTPS, or FTP. The
asfunction
protocol is an additional
protocol that is specific to Flash, which causes the link to invoke an ActionScript function.
Example
In the following example, the
playMP3()
function is defined. The TextField object
list_txt
is
created and set so HTML text can be rendered. The text
Track 1
and