Vector

private class
system.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 setFixed method is used to freeze the size.
  • Items will be initialized to null if a non-zero size is provided to the constructor.
  • When increasing the size of a Vector, the push or unshift methods 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 for loop, for manual iteration
  • with a for..in loop, for iteration by index
  • with a for each loop, 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

Vector ( size: Number = 0 )

Attributes

Public attributes

length: Number

The number of elements in the Vector

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 false result of the callback

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

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.

  • a will be considered equal to A.

DESCENDING: Number

static

Sorting constant - The result will be in descending order.

  • c will be placed before a.
  • 3 will be placed before 1.
  • 3 will also be placed before 11 unless combined with NUMERIC.

NUMERIC: Number

static

Sorting constant - Sorts the elements numerically instead of alphabetically.

  • 3 will be placed before 11.
  • '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

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.

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 (Z precedes a).
  • Sorting is ascending (a precedes b).
  • 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 100 precedes 9, 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 0 when the two items are equal
  • return 1 when the first item should be placed after the second
  • return -1 when 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.

toString (): String
Inherited from Object

native

Returns a String that describes the Object. This can be overriden to provide extra details when printing objects using trace().


Returns

String String that described the Object.

unshift ( args: Vector.<Object> ): Number

Adds one or more elements to the beginning of the Vector, shifting the other elements to the right.

Parameters

args: Vector.<Object>

Returns

Number The new length of the Vector.

: