| Package | Top Level |
| Class | public dynamic class Array |
| Inheritance | Array  Object |
| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
[0], the second element is [1], and so on. To create an Array object, you use the new Array() constructor . Array() can also be
invoked as a function. In addition, you can use the array access ([]) operator to initialize an array or access the elements of an array.
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.
Arrays are sparse arrays, meaning there might be an element at index 0 and another at index 5, but nothing in the index positions between those two elements. In such a case, the elements in positions 1 through 4 are undefined, which indicates the absence of an element, not necessarily the presence of an element with the value undefined.
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.
Do not use the Array class to create associative arrays (also called hashes), which are data structures that contain named elements instead of numbered elements. To create associative arrays, use the Object class. Although ActionScript permits you to create associative arrays using the Array class, you cannot use any of the Array class methods or properties with associative arrays.
You can extend the Array class and override or add methods. However, you must specify the subclass as dynamic
or you will lose the ability to store data in an array.
More examples
Inserting array elements
Retrieving values and removing array elements
Sorting an array
Querying an array
Extending the Array class
Arrays example: PlayList
Learn more
Basics of arrays
Indexed arrays
Associative arrays
Multidimensional arrays
Cloning arrays
Related API Elements
Hide Inherited Public Properties
Show Inherited Public Properties| Property | Defined By | ||
|---|---|---|---|
 | constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | |
| length : uint
A non-negative integer specifying the number of elements in the array. | Array | ||
| Method | Defined By | ||
|---|---|---|---|
Lets you create an array that contains the specified elements. | Array | ||
Lets you create an array of the specified number of elements. | Array | ||
Concatenates the elements specified in the parameters with the elements in an array and creates a new array. | Array | ||
Executes a test function on each item in the array until an item is reached that returns false for the
specified function. | Array | ||
Executes a test function on each item in the array and constructs a new array for all items that return true for the specified function. | Array | ||
Executes a function on each item in the array. | Array | ||
|
Indicates whether an object has a specified property defined. | Object | |
Searches for an item in an array by using strict equality (===) and returns the index
position of the item. | Array | ||
Insert a single element into an array. | Array | ||
|
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | |
Converts the elements in an array to strings, inserts the specified separator between the
elements, concatenates them, and returns the resulting string. | Array | ||
Searches for an item in an array, working backward from the last item, and returns the index position of the matching item using strict equality (===). | Array | ||
Executes a function on each item in an array, and constructs a new array of items corresponding to the results of the function on
each item in the original array. | Array | ||
Removes the last element from an array and returns the value of that element. | Array | ||
|
Indicates whether the specified property exists and is enumerable. | Object | |
Adds one or more elements to the end of an array and returns the new length of the array. | Array | ||
Remove a single element from an array. | Array | ||
Reverses the array in place. | Array | ||
|
Sets the availability of a dynamic property for loop operations. | Object | |
Removes the first element from an array and returns that element. | Array | ||
Returns a new array that consists of a range of elements from the original array, without modifying the original array. | Array | ||
Executes a test function on each item in the array until an item is reached that returns true. | Array | ||
Sorts the elements in an array. | Array | ||
Sorts the elements in an array according to one or more fields in the array. | Array | ||
Adds elements to and removes elements from an array. | Array | ||
Returns a string that represents the elements in the specified array. | Array | ||
Returns a string that represents the elements in the specified array. | Array | ||
Adds one or more elements to the beginning of an array and returns the new length of the array. | Array | ||
|
Returns the primitive value of the specified object. | Object | |
| Constant | Defined By | ||
|---|---|---|---|
| CASEINSENSITIVE : uint = 1 [static]
Specifies case-insensitive sorting for the Array class sorting methods. | Array | ||
| DESCENDING : uint = 2 [static]
Specifies descending sorting for the Array class sorting methods. | Array | ||
| NUMERIC : uint = 16 [static]
Specifies numeric (instead of character-string) sorting for the Array class sorting methods. | Array | ||
| RETURNINDEXEDARRAY : uint = 8 [static]
Specifies that a sort returns an array that consists of array indices. | Array | ||
| UNIQUESORT : uint = 4 [static]
Specifies the unique sorting requirement for the Array class sorting methods. | Array | ||
length | property |
length:uint| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
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.
Implementation
public function get length():uint public function set length(value:uint):voidExample ( How to use this example )
names with the string element Bill.
It then uses the push() method to add another string element Kyle. The length of the array, as
determined by the length property, was one element before the use of push() and is two
elements after push() is called. Another string, Jeff,
is added to make the length of names three elements. The shift() method is then called twice
to remove Bill and Kyle, making the final array of length one.
var names:Array = new Array("Bill");
names.push("Kyle");
trace(names.length); // 2
names.push("Jeff");
trace(names.length); // 3
names.shift();
names.shift();
trace(names.length); // 1
Array | () | Constructor |
public function Array(... values)| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Lets you create an array that contains the specified elements. You can specify values of any type. The first element in an array always has an index (or position) of 0.
Note: This class shows two constructor entries because the constructor accepts variable types of arguments. The constructor behaves differently depending on the type and number of arguments passed, as detailed in each entry. ActionScript 3.0 does not support method or constructor overloading.
Parameters... values — A comma-separated list of one or more arbitrary values.
Note: If only a single numeric parameter is passed to the Array constructor,
it is assumed to specify the array's |
Throws
RangeError — The argument is a number that is not an integer greater than or equal to 0.
|
More examples
Related API Elements
Example ( How to use this example )
one, two, and three,
and then converts the elements to a string.
package {
import flash.display.Sprite;
public class Array_Array_3 extends Sprite {
public function Array_Array_3() {
var myArr:Array = new Array("one", "two", "three");
trace(myArr.length); // 3
trace(myArr); // one,two,three
}
}
}
Array | () | Constructor |
public function Array(numElements:int = 0)| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Lets you create an array of the specified number of elements.
If you don't specify any parameters, an array containing 0 elements is created.
If you specify a number of elements, an array is created with numElements number of elements.
Note: This class shows two constructor method entries because the constructor accepts variable types of arguments. The constructor behaves differently depending on the type and number of arguments passed, as detailed in each entry. ActionScript 3.0 does not support method or constructor overloading.
ParametersnumElements:int (default = 0) |
Throws
RangeError — The argument is a number that is not an integer greater than or equal to 0.
|
More examples
Related API Elements
Example ( How to use this example )
myArr with no arguments
and an initial length of 0:
package {
import flash.display.Sprite;
public class Array_Array extends Sprite {
public function Array_Array() {
var myArr:Array = new Array();
trace(myArr.length); // 0
}
}
}
"one", and adds the string element "six" to the end
of the array by using the push() method:
package {
import flash.display.Sprite;
public class Array_Array_2 extends Sprite {
public function Array_Array_2() {
var myArr:Array = new Array(5);
trace(myArr.length); // 5
myArr[0] = "one";
myArr.push("six");
trace(myArr); // one,,,,,six
trace(myArr.length); // 6
}
}
}
concat | () | method |
AS3 function concat(... args):Array| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Concatenates the elements specified in the parameters with the elements in an array and creates a new array. If the parameters specify an array, the elements of that array are concatenated. If you don't pass any parameters, the new array is a duplicate (shallow clone) of the original array.
Parameters
... args — A value of any data type (such as numbers, elements, or strings) to be concatenated in a new array.
|
Array — An array that contains the elements from this array followed by elements from
the parameters.
|
More examples
Example ( How to use this example )
- The
numbersarray, which contains the numbers1,2, and3. - The
lettersarray, which contains the lettersa,b, andc. - The
numbersAndLettersarray, which calls theconcat()method to produce the array[1,2,3,a,b,c]. - The
lettersAndNumbersarray, which calls theconcat()method to produce the array[a,b,c,1,2,3].
var numbers:Array = new Array(1, 2, 3);
var letters:Array = new Array("a", "b", "c");
var numbersAndLetters:Array = numbers.concat(letters);
var lettersAndNumbers:Array = letters.concat(numbers);
trace(numbers); // 1,2,3
trace(letters); // a,b,c
trace(numbersAndLetters); // 1,2,3,a,b,c
trace(lettersAndNumbers); // a,b,c,1,2,3
every | () | method |
AS3 function every(callback:Function, thisObject:* = null):Boolean| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Executes a test function on each item in the array until an item is reached that returns false for the
specified function. You use this method to determine whether all items in an array meet a criterion, such as having values
less than a particular number.
For this method, the second parameter, thisObject, must be null if the
first parameter, callback, is a method closure. Suppose you create a function in a movie clip
called me:
function myFunction(obj:Object):void {
//your code here
}
Suppose you then use the every() method on an array called myArray:
myArray.every(myFunction, me);
Because myFunction is a member of the Timeline class, which cannot be overridden
by me, the Flash runtime will throw an exception.
You can avoid this runtime error by assigning the function to a variable, as follows:
var myFunction:Function = function(obj:Object):void {
//your code here
};
myArray.every(myFunction, me);
Parameters
callback:Function — The function to run on each item in the array. This function can contain a simple comparison (for example, item < 20) or a more complex operation, and is invoked with three arguments; the
value of an item, the index of an item, and the Array object:
function callback(item:*, index:int, array:Array):Boolean; | |
thisObject:* (default = null)this for the function.
|
Boolean — A Boolean value of true if all items in the array return true for the specified function; otherwise, false.
|
Related API Elements
Example ( How to use this example )
isNumeric is true for the first array and false for the second:
package {
import flash.display.Sprite;
public class Array_every extends Sprite {
public function Array_every() {
var arr1:Array = new Array(1, 2, 4);
var res1:Boolean = arr1.every(isNumeric);
trace("isNumeric:", res1); // true
var arr2:Array = new Array(1, 2, "ham");
var res2:Boolean = arr2.every(isNumeric);
trace("isNumeric:", res2); // false
}
private function isNumeric(element:*, index:int, arr:Array):Boolean {
return (element is Number);
}
}
}
filter | () | method |
AS3 function filter(callback:Function, thisObject:* = null):Array| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Executes a test function on each item in the array and constructs a new array for all items that return true for the specified function. If an item returns false, it is not included in the new array.
For this method, the second parameter, thisObject, must be null if the
first parameter, callback, is a method closure. Suppose you create a function in a movie clip
called me:
function myFunction(obj:Object):void {
//your code here
}
Suppose you then use the filter() method on an array called myArray:
myArray.filter(myFunction, me);
Because myFunction is a member of the Timeline class, which cannot be overridden
by me, the Flash runtime will throw an exception.
You can avoid this runtime error by assigning the function to a variable, as follows:
var myFunction:Function = function(obj:Object):void {
//your code here
};
myArray.filter(myFunction, me);
Parameters
callback:Function — The function to run on each item in the array. This function can contain a simple comparison (for example, item < 20) or a more complex operation, and is invoked with three arguments; the
value of an item, the index of an item, and the Array object:
function callback(item:*, index:int, array:Array):Boolean; | |
thisObject:* (default = null)this for the function.
|
Array — A new array that contains all items from the original array that returned true.
|
Related API Elements
Example ( How to use this example )
package {
import flash.display.Sprite;
public class Array_filter extends Sprite {
public function Array_filter() {
var employees:Array = new Array();
employees.push({name:"Employee 1", manager:false});
employees.push({name:"Employee 2", manager:true});
employees.push({name:"Employee 3", manager:false});
trace("Employees:");
employees.forEach(traceEmployee);
var managers:Array = employees.filter(isManager);
trace("Managers:");
managers.forEach(traceEmployee);
}
private function isManager(element:*, index:int, arr:Array):Boolean {
return (element.manager == true);
}
private function traceEmployee(element:*, index:int, arr:Array):void {
trace("\t" + element.name + ((element.manager) ? " (manager)" : ""));
}
}
}
forEach | () | method |
AS3 function forEach(callback:Function, thisObject:* = null):void| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Executes a function on each item in the array.
For this method, the second parameter, thisObject, must be null if the
first parameter, callback, is a method closure. Suppose you create a function in a movie clip
called me:
function myFunction(obj:Object):void {
//your code here
}
Suppose you then use the forEach() method on an array called myArray:
myArray.forEach(myFunction, me);
Because myFunction is a member of the Timeline class, which cannot be overridden
by me, the Flash runtime will throw an exception.
You can avoid this runtime error by assigning the function to a variable, as follows:
var myFunction:Function = function(obj:Object):void {
//your code here
};
myArray.forEach(myFunction, me);
Parameters
callback:Function — The function to run on each item in the array. This function can contain a simple command
(for example, a trace() statement) or a more complex operation, and is invoked with three arguments; the
value of an item, the index of an item, and the Array object:
function callback(item:*, index:int, array:Array):void; | |
thisObject:* (default = null)this for the function.
|
Example ( How to use this example )
trace() statement in the traceEmployee() function on each item in the array:
package {
import flash.display.Sprite;
public class Array_forEach extends Sprite {
public function Array_forEach() {
var employees:Array = new Array();
employees.push({name:"Employee 1", manager:false});
employees.push({name:"Employee 2", manager:true});
employees.push({name:"Employee 3", manager:false});
trace(employees);
employees.forEach(traceEmployee);
}
private function traceEmployee(element:*, index:int, arr:Array):void {
trace(element.name + " (" + element.manager + ")");
}
}
}
trace() statement in a slightly altered traceEmployee() function on each item in the array:
package {
import flash.display.Sprite;
public class Array_forEach_2 extends Sprite {
public function Array_forEach_2() {
var employeeXML:XML = <employees>
<employee name="Steven" manager="false" />
<employee name="Bruce" manager="true" />
<employee name="Rob" manager="false" />
</employees>;
var employeesList:XMLList = employeeXML.employee;
var employeesArray:Array = new Array();
for each (var tempXML:XML in employeesList) {
employeesArray.push(tempXML);
}
employeesArray.sortOn("@name");
employeesArray.forEach(traceEmployee);
}
private function traceEmployee(element:*, index:Number, arr:Array):void {
trace(element.@name + ((element.@manager == "true") ? " (manager)" : ""));
}
}
}
indexOf | () | method |
AS3 function indexOf(searchElement:*, fromIndex:int = 0):int| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Searches for an item in an array by using strict equality (===) and returns the index
position of the item.
Parameters
searchElement:* — The item to find in the array.
| |
fromIndex:int (default = 0) |
int — A zero-based index position of the item in the array. If the searchElement argument
is not found, the return value is -1.
|
Related API Elements
Example ( How to use this example )
package {
import flash.display.Sprite;
public class Array_indexOf extends Sprite {
public function Array_indexOf() {
var arr:Array = new Array(123,45,6789);
arr.push("123-45-6789");
arr.push("987-65-4321");
var index:int = arr.indexOf("123");
trace(index); // -1
var index2:int = arr.indexOf(123);
trace(index2); // 0
}
}
}
insertAt | () | method |
AS3 function insertAt(index:int, element:*):void| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 19, AIR 19 |
Insert a single element into an array. This method modifies the array without making a copy.
Parameters
index:int — An integer that specifies the position in the array where the element is to be inserted.
You can use a negative integer to specify a position relative to the end of the array
(for example, -1 is the last element of the array).
| |
element:* |
join | () | method |
AS3 function join(sep:*):String| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 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.
Parameters
sep:* (default = NaN) |
String — A string consisting of the elements of an array
converted to strings and separated by the specified parameter.
|
More examples
Related API Elements
Example ( How to use this example )
myArr with elements one,
two, and three and then a string containing one and two and three
using the join() method.
var myArr:Array = new Array("one", "two", "three");
var myStr:String = myArr.join(" and ");
trace(myArr); // one,two,three
trace(myStr); // one and two and three
specialChars with elements (,
), -, and a blank space and then creates a string containing (888) 867-5309.
Then, using a for loop, it removes each type of special character listed in specialChars to
produce a string (myStr) that contains only the digits of the phone number remaining: 888675309.
Note that other characters, such as +, could have been added to specialChars and then this
routine would work with international phone number formats.
var phoneString:String = "(888) 867-5309";
var specialChars:Array = new Array("(", ")", "-", " ");
var myStr:String = phoneString;
var ln:uint = specialChars.length;
for(var i:uint; i < ln; i++) {
myStr = myStr.split(specialChars[i]).join("");
}
var phoneNumber:Number = new Number(myStr);
trace(phoneString); // (888) 867-5309
trace(phoneNumber); // 8888675309
lastIndexOf | () | method |
AS3 function lastIndexOf(searchElement:*, fromIndex:int = 0x7fffffff):int| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Searches for an item in an array, working backward from the last item, and returns the index position of the matching item using strict equality (===).
Parameters
searchElement:* — The item to find in the array.
| |
fromIndex:int (default = 0x7fffffff)fromIndex, the search starts at the last item
in the array.
|
int — A zero-based index position of the item in the array. If the searchElement argument is
not found, the return value is -1.
|
Related API Elements
Example ( How to use this example )
package {
import flash.display.Sprite;
public class Array_lastIndexOf extends Sprite {
public function Array_lastIndexOf() {
var arr:Array = new Array(123,45,6789,123,984,323,123,32);
var index:int = arr.indexOf(123);
trace(index); // 0
var index2:int = arr.lastIndexOf(123);
trace(index2); // 6
}
}
}
map | () | method |
AS3 function map(callback:Function, thisObject:* = null):Array| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Executes a function on each item in an array, and constructs a new array of items corresponding to the results of the function on each item in the original array.
For this method, the second parameter, thisObject, must be null if the
first parameter, callback, is a method closure. Suppose you create a function in a movie clip
called me:
function myFunction(obj:Object):void {
//your code here
}
Suppose you then use the map() method on an array called myArray:
myArray.map(myFunction, me);
Because myFunction is a member of the Timeline class, which cannot be overridden
by me, the Flash runtime will throw an exception.
You can avoid this runtime error by assigning the function to a variable, as follows:
var myFunction:Function = function(obj:Object):void {
//your code here
};
myArray.map(myFunction, me);
Parameters
callback:Function — The function to run on each item in the array. This function can contain a simple command (such as changing the case of an array of strings) or a more complex operation, and is invoked with three arguments; the
value of an item, the index of an item, and the Array object:
function callback(item:*, index:int, array:Array):String; | |
thisObject:* (default = null)this for the function.
|
Array — A new array that contains the results of the function on each item in the original array.
|
Related API Elements
Example ( How to use this example )
package {
import flash.display.Sprite;
public class Array_map extends Sprite {
public function Array_map() {
var arr:Array = new Array("one", "two", "Three");
trace(arr); // one,two,Three
var upperArr:Array = arr.map(toUpper);
trace(upperArr); // ONE,TWO,THREE
}
private function toUpper(element:*, index:int, arr:Array):String {
return String(element).toUpperCase();
}
}
}
pop | () | method |
AS3 function pop():*| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Removes the last element from an array and returns the value of that element.
Returns* — The value of the last element (of any data type) in the specified array.
|
More examples
Related API Elements
Example ( How to use this example )
letters with elements a,
b, and c. The last element (c) is then removed from the array using the
pop() method and assigned to the String object letter.
var letters:Array = new Array("a", "b", "c");
trace(letters); // a,b,c
var letter:String = letters.pop();
trace(letters); // a,b
trace(letter); // c
push | () | method |
AS3 function push(... args):uint| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Adds one or more elements to the end of an array and returns the new length of the array.
Parameters
... args — One or more values to append to the array.
|
uint — An integer representing the length of the new array.
|
More examples
Related API Elements
Example ( How to use this example )
letters and then populates the array
with the elements a, b, and c
using the push() method.
var letters:Array = new Array();
letters.push("a");
letters.push("b");
letters.push("c");
trace(letters.toString()); // a,b,c
letters, which is initially
populated with the element a. The push() method
is then used once to add the elements b and c to the end of the array,
which is three elements after the push.
var letters:Array = new Array("a");
var count:uint = letters.push("b", "c");
trace(letters); // a,b,c
trace(count); // 3
removeAt | () | method |
AS3 function removeAt(index:int):*| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 19, AIR 19 |
Remove a single element from an array. This method modifies the array without making a copy.
Parameters
index:int — An integer that specifies the index of the element in the array that is to be deleted.
You can use a negative integer to specify a position relative to the end of the array
(for example, -1 is the last element of the array).
|
* — The element that was removed from the original array.
|
reverse | () | method |
AS3 function reverse():Array| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Reverses the array in place.
ReturnsArray — The new array.
|
More examples
Example ( How to use this example )
letters with elements a,
b, and c. The order of the array elements is then reversed using the
reverse() method to produce the array [c,b,a].
var letters:Array = new Array("a", "b", "c");
trace(letters); // a,b,c
letters.reverse();
trace(letters); // c,b,a
shift | () | method |
AS3 function shift():*| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Removes the first element from an array and returns that element. The remaining array elements are moved from their original position, i, to i-1.
Returns* — The first element (of any data type) in an array.
|
More examples
Related API Elements
Example ( How to use this example )
letters with elements a,
b, and c. The shift() method is then used to remove the first
element (a) from letters and assign it to the string firstLetter.
var letters:Array = new Array("a", "b", "c");
var firstLetter:String = letters.shift();
trace(letters); // b,c
trace(firstLetter); // a
slice | () | method |
AS3 function slice(startIndex:int = 0, endIndex:int = 16777215):Array| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
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, the new array is a duplicate (shallow clone) of the original array.
Parameters
startIndex:int (default = 0)startIndex is a negative number, the starting
point begins at the end of the array, where -1 is the last element.
| |
endIndex:int (default = 16777215)endIndex is a negative
number, the ending point is specified from the end of the array, where -1 is the
last element.
|
Array — An array that consists of a range of elements from the original array.
|
More examples
Example ( How to use this example )
letters with elements
[a,b,c,d,e,f]. The array someLetters is then created by calling the
slice() method on elements one (b) through three (d),
resulting in an array with elements b and c.
var letters:Array = new Array("a", "b", "c", "d", "e", "f");
var someLetters:Array = letters.slice(1,3);
trace(letters); // a,b,c,d,e,f
trace(someLetters); // b,c
letters with elements
[a,b,c,d,e,f].The array someLetters is then created by calling the
slice() method on element two (c), resulting in an array with elements
[c,d,e,f].
var letters:Array = new Array("a", "b", "c", "d", "e", "f");
var someLetters:Array = letters.slice(2);
trace(letters); // a,b,c,d,e,f
trace(someLetters); // c,d,e,f
letters with elements
[a,b,c,d,e,f]. The array someLetters is then created by calling the
slice() method on the second to last element from the end (e), resulting
in an array with elements e and f.
var letters:Array = new Array("a", "b", "c", "d", "e", "f");
var someLetters:Array = letters.slice(-2);
trace(letters); // a,b,c,d,e,f
trace(someLetters); // e,f
some | () | method |
AS3 function some(callback:Function, thisObject:* = null):Boolean| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Executes a test function on each item in the array until an item is reached that returns true. Use this method to determine whether any items in an array meet a criterion, such as having a value less than a particular number.
For this method, the second parameter, thisObject, must be null if the
first parameter, callback, is a method closure. Suppose you create a function in a movie clip
called me:
function myFunction(obj:Object):void {
//your code here
}
Suppose you then use the some() method on an array called myArray:
myArray.some(myFunction, me);
Because myFunction is a member of the Timeline class, which cannot be overridden
by me, the Flash runtime will throw an exception.
You can avoid this runtime error by assigning the function to a variable, as follows:
var myFunction:Function = function(obj:Object):void {
//your code here
};
myArray.some(myFunction, me);
Parameters
callback:Function — The function to run on each item in the array. This function can contain a simple comparison (for example
item < 20) or a more complex operation, and is invoked with three arguments; the
value of an item, the index of an item, and the Array object:
function callback(item:*, index:int, array:Array):Boolean; | |
thisObject:* (default = null)this for the function.
|
Boolean — A Boolean value of true if any items in the array return true for the specified function; otherwise false.
|
Related API Elements
Example ( How to use this example )
package {
import flash.display.Sprite;
public class Array_some extends Sprite {
public function Array_some() {
var arr:Array = new Array();
arr[0] = "one";
arr[1] = "two";
arr[3] = "four";
var isUndef:Boolean = arr.some(isUndefined);
if (isUndef) {
trace("array contains undefined values: " + arr);
} else {
trace("array contains no undefined values.");
}
}
private function isUndefined(element:*, index:int, arr:Array):Boolean {
return (element == undefined);
}
}
}
sort | () | method |
AS3 function sort(... args):Array| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Sorts the elements in an array. This method sorts according to Unicode values. (ASCII is a subset of Unicode.)
By default, Array.sort() 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.
- All elements, regardless of data type, are sorted as if they were strings, so 100 precedes 99, because "1" is a lower string value than "9".
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 sortOptions portion of the ...args parameter description, or you can create your own custom function to do the sorting.
If you create a custom function, you call the sort() method, and use the name
of your custom function as the first argument (compareFunction)
Parameters
... args — The arguments specifying a comparison function and one or more values that determine the behavior of the sort.
This method uses the syntax and argument order
|
Array — The return value depends on whether you pass any arguments, as described in
the following list:
|
More examples
Related API Elements
Example ( How to use this example )
vegetables with elements
[spinach, green pepper, cilantro, onion, avocado]. The array is then sorted by
the sort() method, which is called with no parameters. The result is vegetables sorted in
alphabetical order ([avocado, cilantro, green pepper, onion, spinach]).
var vegetables:Array = new Array("spinach",
"green pepper",
"cilantro",
"onion",
"avocado");
trace(vegetables); // spinach,green pepper,cilantro,onion,avocado
vegetables.sort();
trace(vegetables); // avocado,cilantro,green pepper,onion,spinach
vegetables with elements
[spinach, green pepper, Cilantro, Onion, and Avocado]. The array is then sorted by
the sort() method, which is called with no parameters the first time; the result is
[Avocado,Cilantro,Onion,green pepper,spinach]. Then sort() is called on
vegetables again with the CASEINSENSITIVE constant as a parameter.
The result is vegetables sorted in alphabetical order
([Avocado, Cilantro, green pepper, Onion, spinach]).
var vegetables:Array = new Array("spinach",
"green pepper",
"Cilantro",
"Onion",
"Avocado");
vegetables.sort();
trace(vegetables); // Avocado,Cilantro,Onion,green pepper,spinach
vegetables.sort(Array.CASEINSENSITIVE);
trace(vegetables); // Avocado,Cilantro,green pepper,Onion,spinach
vegetables, which is then
populated through five calls to push(). Each time push() is
called, a new Vegetable object is created by a call to the Vegetable()
constructor, which accepts a String (name) and Number (price) object.
Calling push() five times with the values shown results in the following
array: [lettuce:1.49, spinach:1.89, asparagus:3.99, celery:1.29, squash:1.44]. The
sort() method is then used to sort the array, resulting in the array
[asparagus:3.99, celery:1.29, lettuce:1.49, spinach:1.89, squash:1.44].
var vegetables:Array = new Array();
vegetables.push(new Vegetable("lettuce", 1.49));
vegetables.push(new Vegetable("spinach", 1.89));
vegetables.push(new Vegetable("asparagus", 3.99));
vegetables.push(new Vegetable("celery", 1.29));
vegetables.push(new Vegetable("squash", 1.44));
trace(vegetables);
// lettuce:1.49, spinach:1.89, asparagus:3.99, celery:1.29, squash:1.44
vegetables.sort();
trace(vegetables);
// asparagus:3.99, celery:1.29, lettuce:1.49, spinach:1.89, squash:1.44
//The following code defines the Vegetable class
class Vegetable {
private var name:String;
private var price:Number;
public function Vegetable(name:String, price:Number) {
this.name = name;
this.price = price;
}
public function toString():String {
return " " + name + ":" + price;
}
}
sort() method is used with a custom sort function
(sortOnPrice), which sorts according to price instead of alphabetically. Note that the
new function getPrice() extracts the price.
var vegetables:Array = new Array();
vegetables.push(new Vegetable("lettuce", 1.49));
vegetables.push(new Vegetable("spinach", 1.89));
vegetables.push(new Vegetable("asparagus", 3.99));
vegetables.push(new Vegetable("celery", 1.29));
vegetables.push(new Vegetable("squash", 1.44));
trace(vegetables);
// lettuce:1.49, spinach:1.89, asparagus:3.99, celery:1.29, squash:1.44
vegetables.sort(sortOnPrice);
trace(vegetables);
// celery:1.29, squash:1.44, lettuce:1.49, spinach:1.89, asparagus:3.99
function sortOnPrice(a:Vegetable, b:Vegetable):Number {
var aPrice:Number = a.getPrice();
var bPrice:Number = b.getPrice();
if(aPrice > bPrice) {
return 1;
} else if(aPrice < bPrice) {
return -1;
} else {
//aPrice == bPrice
return 0;
}
}
// The following code defines the Vegetable class and should be in a separate package.
class Vegetable {
private var name:String;
private var price:Number;
public function Vegetable(name:String, price:Number) {
this.name = name;
this.price = price;
}
public function getPrice():Number {
return price;
}
public function toString():String {
return " " + name + ":" + price;
}
}
numbers with elements
[3,5,100,34,10]. A call to sort() without any parameters sorts
alphabetically, producing the undesired result [10,100,3,34,5]. To properly
sort numeric values, you must pass the constant NUMERIC to the sort()
method, which sorts numbers as follows: [3,5,10,34,100].
Note: The default behavior of the sort() function
is to handle each entity as a string.
If you use the Array.NUMERIC argument, the Flash runtime attempts to convert
any non-numeric values to integers for sorting purposes. If it fails, the runtime throws an error.
For example, the runtime can successfully convert a String value of "6"
to an integer, but will throw an error if it encounters a String value of "six".
var numbers:Array = new Array(3,5,100,34,10); trace(numbers); // 3,5,100,34,10 numbers.sort(); trace(numbers); // 10,100,3,34,5 numbers.sort(Array.NUMERIC); trace(numbers); // 3,5,10,34,100
sortOn | () | method |
AS3 function sortOn(fieldName:Object, options:Object = null):Array| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
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 set to 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 and later, 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 (default = null)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, |
Array — The return value depends on whether you pass any parameters:
|
More examples
Related API Elements
Example ( How to use this example )
vegetables and the array
is then populated using five calls to push(). Each time push() is
called, a new Vegetable object is created by calling the Vegetable()
constructor, which accepts a String (name) and Number (price) object.
Calling push() five times with the values shown results in the following
array: [lettuce:1.49, spinach:1.89, asparagus:3.99, celery:1.29, squash:1.44]. The
sortOn() method is then used with the name parameter to produce the following array:
[asparagus:3.99, celery:1.29, lettuce:1.49, spinach:1.89, squash:1.44]. The
sortOn() method is then called again with the price parameter, and the
NUMERIC and DESCENDING constants to produce an array sorted by numbers in descending order:
[asparagus:3.99, spinach:1.89, lettuce:1.49, squash:1.44, celery:1.29].
var vegetables:Array = new Array();
vegetables.push(new Vegetable("lettuce", 1.49));
vegetables.push(new Vegetable("spinach", 1.89));
vegetables.push(new Vegetable("asparagus", 3.99));
vegetables.push(new Vegetable("celery", 1.29));
vegetables.push(new Vegetable("squash", 1.44));
trace(vegetables);
// lettuce:1.49, spinach:1.89, asparagus:3.99, celery:1.29, squash:1.44
vegetables.sortOn("name");
trace(vegetables);
// asparagus:3.99, celery:1.29, lettuce:1.49, spinach:1.89, squash:1.44
vegetables.sortOn("price", Array.NUMERIC | Array.DESCENDING);
trace(vegetables);
// asparagus:3.99, spinach:1.89, lettuce:1.49, squash:1.44, celery:1.29
class Vegetable {
public var name:String;
public var price:Number;
public function Vegetable(name:String, price:Number) {
this.name = name;
this.price = price;
}
public function toString():String {
return " " + name + ":" + price;
}
}
records and the
array is then populated using three calls to push(). Each time push() is
called, the strings name and city and a zip number are
added to records. Three for loops are used to print the array elements. The
first for loop prints the elements in the order in which they were added. The second for
loop is run after records has been sorted by name and then city using the
sortOn() method. The third for loop produces different output because
records is re-sorted by city then by name.
var records:Array = new Array();
records.push({name:"john", city:"omaha", zip:68144});
records.push({name:"john", city:"kansas city", zip:72345});
records.push({name:"bob", city:"omaha", zip:94010});
for(var i:uint = 0; i < records.length; i++) {
trace(records[i].name + ", " + records[i].city);
}
// Results:
// john, omaha
// john, kansas city
// bob, omaha
trace("records.sortOn('name', 'city');");
records.sortOn(["name", "city"]);
for(var i:uint = 0; i < records.length; i++) {
trace(records[i].name + ", " + records[i].city);
}
// Results:
// bob, omaha
// john, kansas city
// john, omaha
trace("records.sortOn('city', 'name');");
records.sortOn(["city", "name"]);
for(var i:uint = 0; i < records.length; i++) {
trace(records[i].name + ", " + records[i].city);
}
// Results:
// john, kansas city
// bob, omaha
// john, omaha
users and the
array is then populated using four calls to push(). Each time push() is
called, a User object is created with the User() constructor and a name
string and age uint are added to users. The resulting array set is
[Bob:3,barb:35,abcd:3,catchy:4].
The array is then sorted in the following ways:
- By name only, producing the array
[Bob:3,abcd:3,barb:35,catchy:4] - By name and using the
CASEINSENSITIVEconstant, producing the array[abcd:3,barb:35,Bob:3,catchy:4] - By name and using the
CASEINSENSITIVEandDESCENDINGconstants, producing the array[catchy:4,Bob:3,barb:35,abcd:3] - By age only, producing the array
[abcd:3,Bob:3,barb:35,catchy:4] - By age and using the
NUMERICconstant, producing the array[Bob:3,abcd:3,catchy:4,barb:35] - By age and using the
DESCENDINGandNUMERICconstants, producing the array[barb:35,catchy:4,Bob:3,abcd:3]
An array called indices is then created and assigned the results of a sort
by age and using the NUMERIC and RETURNINDEXEDARRAY constants,
resulting in the array [Bob:3,abcd:3,catchy:4,barb:35], which is then printed out
using a for loop.
class User {
public var name:String;
public var age:Number;
public function User(name:String, age:uint) {
this.name = name;
this.age = age;
}
public function toString():String {
return this.name + ":" + this.age;
}
}
var users:Array = new Array();
users.push(new User("Bob", 3));
users.push(new User("barb", 35));
users.push(new User("abcd", 3));
users.push(new User("catchy", 4));
trace(users); // Bob:3,barb:35,abcd:3,catchy:4
users.sortOn("name");
trace(users); // Bob:3,abcd:3,barb:35,catchy:4
users.sortOn("name", Array.CASEINSENSITIVE);
trace(users); // abcd:3,barb:35,Bob:3,catchy:4
users.sortOn("name", Array.CASEINSENSITIVE | Array.DESCENDING);
trace(users); // catchy:4,Bob:3,barb:35,abcd:3
users.sortOn("age");
trace(users); // abcd:3,Bob:3,barb:35,catchy:4
users.sortOn("age", Array.NUMERIC);
trace(users); // Bob:3,abcd:3,catchy:4,barb:35
users.sortOn("age", Array.DESCENDING | Array.NUMERIC);
trace(users); // barb:35,catchy:4,Bob:3,abcd:3
var indices:Array = users.sortOn("age", Array.NUMERIC | Array.RETURNINDEXEDARRAY);
var index:uint;
for(var i:uint = 0; i < indices.length; i++) {
index = indices[i];
trace(users[index].name, ": " + users[index].age);
}
// Results:
// Bob : 3
// abcd : 3
// catchy : 4
// barb : 35
splice | () | method |
AS3 function splice(startIndex:int, deleteCount:uint, ... values):Array| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Adds elements to and removes elements from an array. This method modifies the array without making a copy.
Note: To override this method in a subclass of Array, use ...args for the parameters,
as this example shows:
public override function splice(...args) {
// your statements here
}
Parameters
startIndex:int — An integer that specifies the index of the element in the array where the insertion or
deletion begins. You can use 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:uint — An integer that specifies the number of elements to be deleted. This number includes the
element specified in the startIndex parameter. If you do not specify a value 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.
| |
... values — An optional list of one or more comma-separated values
to insert into the array at the position specified in the startIndex parameter.
If an inserted value is of type Array, the array is kept intact and inserted as a single element.
For example, if you splice an existing array of length three with another array of length three,
the resulting array will have only four elements. One of the elements, however, will be an array of length three.
|
Array — An array containing the elements that were removed from the original array.
|
More examples
Example ( How to use this example )
vegetables with the elements
[spinach, green pepper, cilantro, onion, avocado]. The splice()
method is then called with the parameters 2 and 2, which assigns
cilantro and onion to the spliced array. The
vegetables array then contains [spinach,green pepper,avocado]. The
splice() method is called a second time using the parameters 1, 0,
and the spliced array to assign
[cilantro,onion] as the second element in vegetables.
var vegetables:Array = new Array("spinach",
"green pepper",
"cilantro",
"onion",
"avocado");
var spliced:Array = vegetables.splice(2, 2);
trace(vegetables); // spinach,green pepper,avocado
trace(spliced); // cilantro,onion
vegetables.splice(1, 0, spliced);
trace(vegetables); // spinach,cilantro,onion,green pepper,avocado
cilantro and onion trace out as if vegetables
has 5 elements, even though it actually has four (and the second element is another array containing
two elements). To add cilantro and onion individually, you would use:
var vegetables:Array = new Array("spinach",
"green pepper",
"cilantro",
"onion",
"avocado");
var spliced:Array = vegetables.splice(2, 2);
trace(vegetables); // spinach,green pepper,avocado
trace(spliced); // cilantro,onion
vegetables.splice(1, 0, "cilantro", "onion");
trace(vegetables); // spinach,cilantro,onion,green pepper,avocado
toLocaleString | () | method |
public function toLocaleString():String| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Returns a string that represents the elements in the specified array. 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. In the ActionScript 3.0 implementation, this method returns the same value as the Array.toString() method.
String — A string of array elements.
|
Related API Elements
toString | () | method |
public function toString():String| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Returns a string that represents the elements in the specified array. 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.
String — A string of array elements.
|
More examples
Related API Elements
Example ( How to use this example )
vegnums variable of the String data type.
var vegetables:Array = new Array(); vegetables.push(1); vegetables.push(2); vegetables.push(3); vegetables.push(4); vegetables.push(5); var vegnums:String = vegetables.toString(); trace(vegnums+",6"); // 1,2,3,4,5,6
unshift | () | method |
AS3 function unshift(... args):uint| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Adds one or more elements to the beginning of an array and returns the new length of the array. The other elements in the array are moved from their original position, i, to i+1.
Parameters
... args — One or more numbers, elements, or variables to be inserted at the beginning of the array.
|
uint — An integer representing the new length of the array.
|
More examples
Related API Elements
Example ( How to use this example )
names.
The strings Bill and Jeff are added by the push() method,
and then the strings Alfred and Kyle are added to the beginning of
names by two calls to the unshift() method.
var names:Array = new Array();
names.push("Bill");
names.push("Jeff");
trace(names); // Bill,Jeff
names.unshift("Alfred");
names.unshift("Kyle");
trace(names); // Kyle,Alfred,Bill,Jeff
CASEINSENSITIVE | Constant |
public static const CASEINSENSITIVE:uint = 1| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Specifies case-insensitive sorting for the Array class sorting methods. You can use this constant
for the options parameter in the sort() or sortOn() method.
The value of this constant is 1.
Related API Elements
DESCENDING | Constant |
public static const DESCENDING:uint = 2| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Specifies descending sorting for the Array class sorting methods.
You can use this constant for the options parameter in the sort()
or sortOn() method.
The value of this constant is 2.
Related API Elements
NUMERIC | Constant |
public static const NUMERIC:uint = 16| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Specifies numeric (instead of character-string) sorting for the Array class sorting methods.
Including this constant 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].
This constant applies only 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.
Related API Elements
RETURNINDEXEDARRAY | Constant |
public static const RETURNINDEXEDARRAY:uint = 8| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Specifies that a sort returns an array that consists of array indices. You can use this constant
for the options parameter in the sort() or sortOn()
method, so you have access to multiple views of the array elements while the original array is unmodified.
The value of this constant is 8.
Related API Elements
UNIQUESORT | Constant |
public static const UNIQUESORT:uint = 4| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Specifies the unique sorting requirement for the Array class sorting methods.
You can use this constant for the options parameter in the sort() or sortOn()
method. The unique sorting option terminates the sort if any two elements
or fields being sorted have identical values.
The value of this constant is 4.
Related API Elements
myArr with no arguments
and an initial length of 0:
package {
import flash.display.Sprite;
public class ArrayExample extends Sprite {
public function ArrayExample() {
var myArr:Array = new Array();
trace(myArr.length); // 0
}
}
}
Mon Apr 10 2017, 12:28 PM -07:00