View source

abstract Vector<T>(IVector<T>)

package openfl

@:multiType(T)

Available on all platforms

The Vector class lets you access and manipulate a vector — an array whose elements all have the same data type. The data type of a Vector's elements is known as the Vector's base type. The base type can be any class, including built in classes and custom classes. The base type is specified when declaring a Vector variable as well as when creating an instance by calling the class constructor.

As with an Array, you can use the array access operator ([]) to set or retrieve the value of a Vector element. Several Vector methods also provide mechanisms for setting and retrieving element values. These include push(), pop(), shift(), unshift(), and others. The properties and methods of a Vector object are similar — in most cases identical — to the properties and methods of an Array. In most cases where you would use an Array in which all the elements have the same data type, a Vector instance is preferable. However, Vector instances are dense arrays, meaning it must have a value (or null) in each index. Array instances don't have this same restriction.

The Vector's base type is specified using postfix type parameter syntax. Type parameter syntax is a sequence consisting of a dot (.), left angle bracket (<), class name, then a right angle bracket (>), as shown in this example:

In the first line of the example, the variable v is declared as a Vector. instance. In other words, it represents a Vector (an array) that can only hold String instances and from which only String instances can be retrieved. The second line constructs an instance of the same Vector type (that is, a Vector whose elements are all String objects) and assigns it to v.

var v:Vector.<String>;
v = new Vector.<String>();

A variable declared with the Vector. data type can only store a Vector instance that is constructed with the same base type T. For example, a Vector that's constructed by calling new Vector.<String>() can't be assigned to a variable that's declared with the Vector. data type. The base types must match exactly. For example, the following code doesn't compile because the object's base type isn't the same as the variable's declared base type (even though Sprite is a subclass of DisplayObject):

// This code doesn't compile even though Sprite is a DisplayObject subclass
var v:Vector.<DisplayObject> = new Vector.<Sprite>();

To convert a Vector with base type T to a Vector of a superclass of T, use the Vector() global function.

In addition to the data type restriction, the Vector class has other restrictions that distinguish it from the Array class:

  • A Vector is a dense array. Unlike an Array, which may have values in indices 0 and 7 even if there are no values in positions 1 through 6, a Vector must have a value (or null) in each index.
  • A Vector can optionally be fixed-length, meaning the number of elements it contains can't change.
  • Access to a Vector's elements is bounds-checked. You can never read a value from an index greater than the final element (length - 1). You can never set a value with an index more than one beyond the current final index (in other words, you can only set a value at an existing index or at index [length]).

As a result of its restrictions, a Vector has three primary benefits over an Array instance whose elements are all instances of a single class:

  • Performance: array element access and iteration are much faster when using a Vector instance than they are when using an Array.
  • Type safety: in strict mode the compiler can identify data type errors. Examples of data type errors include assigning a value of the incorrect data type to a Vector or expecting the wrong data type when reading a value from a Vector. Note, however, that when using the push() method or unshift() method to add values to a Vector, the arguments' data types are not checked at compile time. Instead, they are checked at run time.
  • Reliability: runtime range checking (or fixed-length checking) increases reliability significantly over Arrays.

Static variables

staticfixed:Bool

Indicates whether the length property of the Vector can be changed. If the value is true, the length property can't be changed. This means the following operations are not allowed when fixed is true:

  • setting the length property directly
  • assigning a value to index position length
  • calling a method that changes the length property, including: pop() push() shift() unshift() * splice() (if the splice() call changes the length of the Vector).

staticlength:Int

The range of valid indices available in the Vector. A Vector instance has index positions up to but not including the length value.

Every Vector element always has a value that is either an instance of the base type or null. When the length property is set to a value that's larger than its previous value, additional elements are created and populated with the default value appropriate to the base type (null for reference types).

When the length property is set to a value that's smaller than its previous value, all the elements at index positions greater than or equal to the new length value are removed from the Vector.

Static methods

@:value({ vec : null })staticinlineconcat(this:IVector<T>, ?vec:Vector<T>):Vector<T>

Concatenates the Vectors specified in the parameters list with the elements in this Vector and creates a new Vector. The Vectors in the parameters list must have the same base type, or subtype, as this Vector. If you do not pass any parameters, the returned Vector is a duplicate (shallow clone) of the original Vector.

Parameters:

vec

A Vector of the base type, or subtype, of this Vector.

Returns:

A Vector with the same base type as this Vector that contains the elements from this Vector followed by elements from the Vector in the parameter list.

Throws:

TypeError

If any argument is not a Vector of the base type, or cannot be converted to a Vector of the base type.

staticinlineconvert<T, U>(vec:IVector<T>):IVector<U>

Attempts to cast a Vector to another Vector object of a similar type

Parameters:

vec

A Vector object to cast

Returns:

The casted Vector object

staticinlinecopy(this:IVector<T>):Vector<T>

Creates a new shallow clone of the current Vector object

Returns:

A new Vector object

staticinlineevery(this:IVector<T>, callback:Function, ?thisObject:Dynamic):Bool

Executes a test function on each item in the Vector until an item is reached that returns false for the specified function. You use this method to determine whether all items in a Vector 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. That is the most common way of using this method.

Parameters:

callback

The function to run on each item in the Vector. This function is invoked with three arguments: the current item from the Vector, the index of the item, and the Vector object:

	 	function callback(item:T, index:Int, vector:Vector<T>):Bool {
	 		// your code here
}

The callback function should return a Boolean value.

thisObject

The object that the identifer this in the callback function refers to when the function is called. ***Ignored on targets other than neko and js.

Returns:

A Boolean value of true if the specified function returns true when called on all items in the Vector; otherwise, false.

staticinlinefilter(this:IVector<T>, callback:T ‑> Bool):Vector<T>

Executes a test function on each item in the Vector and returns a new Vector containing all items that return true for the specified function. If an item returns false, it is not included in the result Vector. The base type of the return Vector matches the base type of the Vector on which the method is called.

Parameters:

callback

The function to run on each item in the Vector.

@:value({ fromIndex : 0 })staticinlineindexOf(this:IVector<T>, searchElement:T, fromIndex:Int = 0):Int

Searches for an item in the Vector and returns the index position of the item. The item is compared to the Vector elements using strict equality (===).

Parameters:

searchElement

The item to find in the Vector.

fromIndex

The location in the Vector from which to start searching for the item. If this parameter is negative, it is treated as length + fromIndex, meaning the search starts -fromIndex items from the end and searches from that position forward to the end of the Vector.

Returns:

A zero-based index position of the item in the Vector. If the searchElement argument is not found, the return value is -1.

staticinlineinsertAt(this:IVector<T>, index:Int, element:T):Void

Insert a single element into the Vector. This method modifies the Vector without making a copy.

Parameters:

index

An integer that specifies the position in the Vector where the element is to be inserted. 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).

element

The value to insert

Throws:

RangeError

If this method is called while fixed is true.

@:value({ sep : "," })staticinlinejoin(this:IVector<T>, 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. A nested Vector is always separated by a comma (,), not by the separator passed to the join() method.

Parameters:

sep

A character or string that separates Vector elements in the returned string. If you omit this parameter, a comma is used as the default separator.

Returns:

A string consisting of the elements of the Vector converted to strings and separated by the specified string.

@:value({ fromIndex : null })staticinlinelastIndexOf(this:IVector<T>, searchElement:T, ?fromIndex:Int):Int

Searches for an item in the Vector, working backward from the specified index position, and returns the index position of the matching item. The item is compared to the Vector elements using strict equality (===).

Parameters:

searchElement

The item to find in the Vector.

fromIndex

The location in the Vector from which to start searching for the item. The default is the maximum allowable index value, meaning that the search starts at the last item in the Vector. If this parameter is negative, it is treated as length + fromIndex, meaning the search starts -fromIndex items from the end and searches from that position backward to index 0.

Returns:

A zero-based index position of the item in the Vector. If the searchElement argument is not found, the return value is -1.

@:genericstaticinlineofArray<T>(array:Array<T>):Vector<T>

Creates a new Vector object using the values from an Array object

Parameters:

array

An Array object

Returns:

A new Vector object

staticinlinepop(this:IVector<T>):Null<T>

Removes the last element from the Vector and returns that element. The length property of the Vector is decreased by one when this function is called.

Returns:

The value of the last element in the specified Vector.

Throws:

RangeError

If this method is called while fixed is true.

staticinlinepush(this:IVector<T>, value:T):Int

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

Because this function can accept multiple arguments, the data type of the arguments is not checked at compile time even in strict mode. However, if an argument is passed that is not an instance of the base type, an exception occurs at run time.

Parameters:

value

A value to append to the Vector.

Returns:

The length of the Vector after the new elements are added.

Throws:

TypeError

If any argument is not an instance of the base type T of the Vector.

RangeError

If this method is called while fixed is true.

staticinlineremoveAt(this:IVector<T>, index:Int):T

Remove a single element from the Vector. This method modifies the Vector without making a copy.

Parameters:

index

An integer that specifies the index of the element in the Vector that is to be deleted. 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).

Returns:

The element that was removed from the original Vector.

Throws:

RangeError

If the index argument specifies an index to be deleted that's outside the Vector's bounds.

RangeError

If this method is called while fixed is true.

staticinlinereverse(this:IVector<T>):Vector<T>

Reverses the order of the elements in the Vector. This method alters the Vector on which it is called.

Returns:

The Vector with the elements in reverse order.

staticinlineshift(this:IVector<T>):Null<T>

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:

The first element in the Vector.

Throws:

RangeError

If fixed is true.

@:value({ endIndex : null, startIndex : 0 })staticinlineslice(this:IVector<T>, startIndex:Int = 0, ?endIndex:Int):Vector<T>

Returns a new Vector that consists of a range of elements from the original Vector, without modifying the original Vector. The returned Vector includes the startIndex element and all elements up to, but not including, the endIndex element.

If you don't pass any parameters, the new Vector is a duplicate (shallow clone) of the original Vector. If you pass a value of 0 for both parameters, a new, empty Vector is created of the same type as the original Vector.

Parameters:

startIndex

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

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.

Returns:

A Vector that consists of a range of elements from the original Vector.

staticinlinesome(this:IVector<T>, callback:Function, ?thisObject:Dynamic):Bool

Parameters:

callback

The function to run on each item in the Vector. This function is invoked with three arguments: the current item from the Vector, the index of the item, and the Vector object:

function callback(item:T, index:Int, vector:Vector<T>):Bool

The callback function should return a Boolean value.

thisObject

The object that the identifer this in the callback function refers to when the function is called. ***Ignored on targets other than neko and js.

Returns:

A Boolean value of true if any items in the Vector return true for the specified function; otherwise, false.

staticinlinesort(this:IVector<T>, sortBehavior:(T, T) ‑> Int):Void

Sorts the elements in the Vector object, and also returns a sorted Vector object. This method sorts according to the parameter sortBehavior, which is either a function that compares two values, or a set of sorting options.

The method takes one parameter. The parameter is one of the following:

  • a function that takes two arguments of the base type (T) of the Vector and returns a Number:

    function compare(x:T, y:T):Number {}

    The logic of the function is that, given two elements x and y, the function returns one of the following three values:

    • a negative number, if x should appear before y in the sorted sequence
    • 0, if x equals y
    • a positive number, if x should appear after y in the sorted sequence

  • a number which is a bitwise OR of the following values: 1 or Array.CASEINSENSITIVE 2 or Array.DESCENDING 4 or Array.UNIQUESORT 8 or Array.RETURNINDEXEDARRAY * 16 or Array.NUMERIC

    If the value is 0, the 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".

Parameters:

sortBehavior

A Function or a Number value that determines the behavior of the sort. A Function parameter specifies a comparison method. A Number value specifies the sorting options.

Returns:

A Vector object, with elements in the new order.

staticinlinesplice(this:IVector<T>, startIndex:Int, deleteCount:Int, items:Rest<Unknown>):Vector<T>

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

Note: To override this method in a subclass of Vector, 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 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:uint

(default = 4294967295) — An integer that specifies the number of elements to be deleted. This number includes the element specified in the startIndex parameter. If the value is 0, no elements are deleted.

...

items — An optional list of one or more comma-separated values to insert into the Vector at the position specified in the startIndex parameter.

Returns:

a Vector containing the elements that were removed from the original Vector.

Throws:

RangeError

If the startIndex and deleteCount arguments specify an index to be deleted that's outside the Vector's bounds.

RangeError

If this method is called while fixed is true and the splice() operation changes the length of the Vector.

staticinlinetoString(this:IVector<T>):String

Returns a string that represents the elements in the Vector. Every element in the Vector, 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 Vector.join() method.

Returns:

A string of Vector elements.

staticinlineunshift(this:IVector<T>, value:T):Void

Adds one or more elements to the beginning of the Vector and returns the new length of the Vector. The other elements in the Vector are moved from their original position, i, to i + the number of new elements.

Because this function can accept multiple arguments, the data type of the arguments is not checked at compile time even in strict mode. However, if an argument is passed that is not an instance of the base type, an exception occurs at run time.

Parameters:

value

An instance of the base type of the Vector to be inserted at the beginning of the Vector.

Returns:

An integer representing the new length of the Vector.

Throws:

TypeError

If any argument is not an instance of the base type T of the Vector.

RangeError

If this method is called while fixed is true.