Vector
Description
A Vector is an ordered collection of items where every item is of the same type.
- The base type can be any class, including built in classes and custom classes.
- Vectors are dynamic (the number of items is allowed to change) unless the
setFixedmethod is used to freeze the size. - Items will be initialized to
nullif a non-zero size is provided to the constructor. - When increasing the size of a Vector, the
pushorunshiftmethods must used. Assigning a value to an index beyond the final value will result in an out-of-bounds error.
Vectors can be instantiated via their constructor function, or with a literal syntax using square brackets ([]):
var v1:Vector.<String> = new Vector.<String>(26);
v1[0] = 'a';
v1[25] = 'z';
var v2:Vector.<String> = [ 'one', 'two', 'three' ];
Vector values are accessed via the square bracket operators ([]) and a zero-based index:
var m:String = v1[12];
v2[1] = 'TWO';
Iteration over vectors can be done in several ways:
- with a
forloop, for manual iteration - with a
for..inloop, for iteration by index - with a
for eachloop, for iteration by value - using the callback iterators:
every(),filter(),forEach(),map(),some()
var v:Vector.<String> = [ 'a', 'b', 'c' ];
for (var i:Number = 0; i < v.length; i++) {
trace('v[' + i +'] =', v[i]);
}
for (var n:Number in v) {
trace('v[' +n +'] =', v[n]);
}
for each(var s:String in v) {
trace(s);
}
See also:
#every()
#filter()
#forEach()
#map()
#some()
API overview
Constructor
Constants
Constants
| CASEINSENSITIVE: Number |
static
Sorting constant - String comparison will ignore case |
| DESCENDING: Number |
static
Sorting constant - The result will be in descending order |
| NUMERIC: Number |
static
Sorting constant - Sorts the elements numerically instead of alphabetically |
| RETURNINDEXEDARRAY: Number |
static
Sorting constant - Original Vector is unmodified but the indices each element would assume if the sort were applied are returned in a new Vector |
| UNIQUESORT: Number |
static
Sorting constant - Prevents sort unless all elements in the Vector are unique |
Functions
Public functions
| clear (): Void |
native Clear the Vector, resizing to zero in the process |
| concat ( args: Vector.<Object> ): Vector |
native Concatenates the Vectors specified in the parameters list with the elements in this Vector and creates a new Vector |
| contains ( value: Object ): Boolean |
native Indicates whether or not the Vector contains the provided value |
| every ( callback: Function , thisObject: Object = null ): Boolean |
Executes a callback function for each element of the Vector, stopping at the first |
| filter ( callback: Function , thisObject: Object = null ): Vector |
Executes a callback function for each element of the Vector and adds the element to the return Vector if the callback returns |
| forEach ( callback: Function , thisObject: Object = null ): Void |
Executes a callback function for each element of the Vector |
| indexOf ( o: Object , startIndex: Number = 0 ): Number |
native Searches forward for an item in the Vector from startIndex to the last item |
| join ( sep: String = , ): String |
Converts the elements in the Vector to strings, inserts the specified separator between the elements, concatenates them, and returns the resulting string |
| lastIndexOf ( o: Object , startIndex: Number = ): Number |
Searches backward for an item in the Vector from startIndex to the first item |
| map ( callback: Function , thisObject: Object = null ): Vector |
Executes a callback function for each element of the Vector, adding the result to a new return Vector |
| pop (): Object |
native Removes the last element from the Vector and returns that element |
| push ( args: Vector.<Object> ): Number |
Adds one or more elements to the end of the Vector and returns the new length of the Vector |
| pushSingle ( value: Object ): Object |
native Adds an element to the end of the Vector and returns the new length of the Vector |
| remove ( value: Object ): Void |
native Removes an object from the Vector |
| reverse (): Vector |
Reverses the elements of a Vector in place |
| setFixed (): Void |
native Freezes the length of the Vector to the current length, optimizing Vector operations |
| shift (): Object |
native Removes the first element from the Vector and returns that element |
| shuffle (): Vector |
Shuffles the elements of the Vector in place by randomly reordering them |
| slice ( startIndex: Number = 0 , endIndex: Number = 16777215 ): Vector |
native Returns a new Vector that consists of a range of elements from the original Vector, without modifying the original Vector |
| some ( callback: Function , thisObject: Object = null ): Boolean |
Executes a callback function for each element of the Vector, stopping at the first true result of the callback |
| sort ( sortBehavior: Object = 0 ): Object |
native Sorts the elements in the Vector |
| splice ( startIndex: Number , deleteCount: Number , items: Vector.<Object> ): Vector |
native Adds elements to and removes elements from the Vector |
| unshift ( args: Vector.<Object> ): Number |
Adds one or more elements to the beginning of the Vector, shifting the other elements to the right |
Constructor
Vector ( size: Number = 0 )
Attributes
length: Number
The number of elements in the Vector. The interval of valid indices is [0, length-1].
Constants
CASEINSENSITIVE: Number
static
Sorting constant - String comparison will ignore case.
awill be considered equal toA.
DESCENDING: Number
static
Sorting constant - The result will be in descending order.
cwill be placed beforea.3will be placed before1.3will also be placed before11unless combined withNUMERIC.
NUMERIC: Number
static
Sorting constant - Sorts the elements numerically instead of alphabetically.
3will be placed before11.'100'will be placed after'9'.
Numeric sorting for types other than String or Number is undefined; a custom sorting function should be used instead.
RETURNINDEXEDARRAY: Number
static
Sorting constant - Original Vector is unmodified but the indices each element would assume if the sort were applied are returned in a new Vector.
The return value is a Vector.<Number> of sort-ordered indices.
UNIQUESORT: Number
static
Sorting constant - Prevents sort unless all elements in the Vector are unique.
If there are any duplicates, the sort function will return the Number 0 and the original Vector will be unmodified.
Functions
concat ( args: Vector.<Object> ): Vector
native
Concatenates the Vectors specified in the parameters list with the elements in this Vector and creates a new Vector.
Parameters
| args: Vector.<Object> | A Vector with the same base type as this Vector that contains the elements from this Vector followed by elements from the Vectors in the parameters list. |
contains ( value: Object ): Boolean
native
Indicates whether or not the Vector contains the provided value.
@note This has been updated to work for numbers/string/etc, but untested.
Parameters
| value: Object | The value to query. |
Returns
| Boolean | true if the value is contained in the Vector, false otherwise. |
every ( callback: Function , thisObject: Object = null ): Boolean
Executes a callback function for each element of the Vector, stopping at the first false result of the callback.
Parameters
| callback: Function | A callback in the form of function(item:Object, index:Number, v:Vector):Boolean which will be called on each element of the Vector. |
| thisObject: Object = null | Required if the callback is an instance method and not a local or static function. |
Returns
| Boolean | True when every element passes the callback test, false if any one fails. |
filter ( callback: Function , thisObject: Object = null ): Vector
Executes a callback function for each element of the Vector and adds the element to the return Vector if the callback returns true.
Parameters
| callback: Function | A callback in the form of function(item:Object, index:Number, vector:Vector):Boolean which will be called for each element of the Vector. |
| thisObject: Object = null | Required if the callback is an instance method and not a local or static function. |
Returns
| Vector | A new Vector containing only the elements from the original Vector that passed the callback function test. |
forEach ( callback: Function , thisObject: Object = null ): Void
Executes a callback function for each element of the Vector.
Parameters
| callback: Function | A callback in the form of function(item:Object, index:Number, vector:Vector):void which will be called for each element of the Vector. |
| thisObject: Object = null | Required if the callback is an instance method and not a local or static function. |
getFullTypeName
(): String
Inherited from Object
native
Gets the fully qualified type name of the Object. The fully qualified type name includes the package of the type.
Returns
| String | fully qualified type name of the Object. |
getType
(): Type
Inherited from Object
native
Gets the Type that describes the Object.
Returns
| Type | The Type that describes the object. |
getTypeName
(): String
Inherited from Object
native
Gets the type name of the Object.
Returns
| String | type name of the Object. |
indexOf ( o: Object , startIndex: Number = 0 ): Number
native
Searches forward for an item in the Vector from startIndex to the last item.
Parameters
| o: Object | The item to find in the Vector. |
| startIndex: Number = 0 | The location in the Vector from which to start searching for the item. If no startIndex is given, the search begins at the first element of the Vector. If this parameter is negative, it is treated as length + fromIndex, meaning the search starts -fromIndex items from the end and continues from that position forward to the end of the Vector. |
Returns
| Number | The index of the item in the Vector, or -1 if the item is not found between the start index and the end of the Vector. |
join ( sep: String = , ): String
Converts the elements in the Vector to strings, inserts the specified separator between the elements, concatenates them, and returns the resulting string.
Parameters
| sep: String = , |
lastIndexOf ( o: Object , startIndex: Number = ): Number
Searches backward for an item in the Vector from startIndex to the first item.
Parameters
| o: Object | The item to find in the Vector. |
| startIndex: Number = | The index in the Vector to start the search from. If no startIndex is given, the search begins at the last element of the Vector. |
Returns
| Number | The index of the item in the Vector, or -1 if the item is not found between the start index and the beginning of the Vector. |
map ( callback: Function , thisObject: Object = null ): Vector
Executes a callback function for each element of the Vector, adding the result to a new return Vector.
Parameters
| callback: Function | A callback in the form of function(item:Object, index:Number, vector:Vector):Object which will be called for each element of the Vector. |
| thisObject: Object = null | Required if the callback is an instance method and not a local or static function. |
Returns
| Vector | A new Vector whose elements are the return values of the callback. The result Vector will have the same number of elements as the source Vector. |
pop (): Object
native
Removes the last element from the Vector and returns that element.
Returns
| Object | The value of the last element in the specified Vector. |
push ( args: Vector.<Object> ): Number
Adds one or more elements to the end of the Vector and returns the new length of the Vector.
Parameters
| args: Vector.<Object> | Arbitrary list of items to add to the Vector. |
Returns
| Number | The new length of the Vector. |
pushSingle ( value: Object ): Object
native
Adds an element to the end of the Vector and returns the new length of the Vector.
Parameters
| value: Object | The item to add to the end of the Vector. |
Returns
| Object | The new length of the Vector. |
remove ( value: Object ): Void
native
Removes an object from the Vector.
Parameters
| value: Object | The object to be removed. |
reverse (): Vector
Reverses the elements of a Vector in place.
Returns
| Vector | Returns a reference to the modified Vector. |
setFixed (): Void
native
Freezes the length of the Vector to the current length, optimizing Vector operations.
shift (): Object
native
Removes the first element from the Vector and returns that element. The remaining Vector elements are moved from their original position, i, to i - 1.
Returns
| Object | The first element in the Vector. |
shuffle (): Vector
Shuffles the elements of the Vector in place by randomly reordering them.
Returns
| Vector | Returns a reference to the modified Vector. |
slice ( startIndex: Number = 0 , endIndex: Number = 16777215 ): Vector
native
Returns a new Vector that consists of a range of elements from the original Vector, without modifying the original Vector.
Parameters
| startIndex: Number = 0 | A number specifying the index of the starting point for the slice. If startIndex is a negative number, the starting point begins at the end of the Vector, where -1 is the last element. |
| endIndex: Number = 16777215 | 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 Vector. If endIndex is a negative number, the ending point is specified from the end of the Vector, where -1 is the last element. |
some ( callback: Function , thisObject: Object = null ): Boolean
Executes a callback function for each element of the Vector, stopping at the first true result of the callback.
Parameters
| callback: Function | A callback in the form of function(item:Object, index:Number, v:Vector):Boolean which will be called on each element of the Vector. |
| thisObject: Object = null | Required if the callback is an instance method and not a local or static function. |
Returns
| Boolean | True when any element passes the callback test, false if every one fails. |
sort ( sortBehavior: Object = 0 ): Object
native
Sorts the elements in the Vector.
By default, Vector.sort() sorts in the following manner:
- Sorting is case-sensitive (
Zprecedesa). - Sorting is ascending (
aprecedesb). - The Vector is modified in place to reflect the sort order.
- Elements that sort identically are placed consecutively with no particular precedence.
- All elements, regardless of data type, are sorted as if they were strings, so
100precedes9, because "1" is a lower string value than "9".
To implement a different sorting behavior, provide one of the following as the value for the sortBehavior parameter:
- One or more sorting constants combined with bitwise OR (
|), e.g.myVector.sort(Vector.CASEINSENSITIVE | Vector.DESCENDING); - A custom sorting function with the signature:
function (x:Object, y:Object):Number
When providing a custom sorting function, the following behavior is expected:
- return
0when the two items are equal - return
1when the first item should be placed after the second - return
-1when the first item should be placed before the second
Parameters
| sortBehavior: Object = 0 | Either a bitwise OR of sorting constants (CASEINSENSITIVE, DESCENDING, UNIQUESORT, RETURNINDEXEDARRAY, NUMERIC) or a sorting function in the form of "function (x:Object, y:Object):Number" where x/y can be of any type and the function returns 0 for equality, 1 for x>y and -1 for x<y. |
splice ( startIndex: Number , deleteCount: Number , items: Vector.<Object> ): Vector
native
Adds elements to and removes elements from the Vector. This method modifies the Vector without making a copy.
Parameters
| startIndex: Number | An integer that specifies the index of the element in the Vector where the insertion or deletion begins. You can use a negative integer to specify a position relative to the end of the Vector (for example, -1 for the last element of the Vector). |
| deleteCount: Number | 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 Vector. (The default value is uint.MAX_VALUE.) If the value is 0, no elements are deleted. |
| items: Vector.<Object> | An optional list of one or more comma-separated values to insert into the Vector at the position specified in the startIndex parameter. |
Returns
| Vector | A Vector containing the elements that were removed from the original Vector. |