nape.List

Package	nape
Class	List<T>
Subclasses	ContactList, ArbiterList, InteractionGroupList, InteractorList, ShapeList, EdgeList, InteractorList, BodyList, CompoundList, Vec2List, RayResultList, GeomPolyList, ListenerList, ConstraintList

This is not a real class or interface, but is written like this to avoid mass duplication as each list type is consistent with this interface through other means.

Note: In many cases a List type will be returned from a function internal to nape and will be marked internally as an 'immutable' List. This is documented in those cases; trying to modify (mutate) such a List will result in an error.

Iteration over these list types should be done like:

● haXe:

for(var obj in list) {}

● AS3:

list.foreach(function (obj:T):void {});
//or, if you need to be able to 'break' out of the loop:
for(var i:int = 0; i<list.length; i++) {
	var obj:T = list.at(i);
	//use obj
}
//or through use of iterator()

Public Properties

	Property	Defined By
	length : Int [read-only] Number of elements in list	List<T>

Public Methods

	Method	Defined By
	const empty() : Bool Whether list is empty	List<T>
	const copy() : List<T> Produce a copy of the list	List<T>

	const at(index:Int) : T Return element at index	List<T>
	const iterator() : ListIterator<T> Return iterator to list.	List<T>
	const foreach(lambda:T->Void) : Void Apply function to each element of the list	List<T>
	filter(lambda:T->Bool) : List<T> Filter out unwanted elements of the list.	List<T>

	push(obj:const T) : Bool Push element to back of list	List<T>
	unshift(obj:const T) : Bool Push element to front of list	List<T>
	add(obj:const T) : Bool Add element to list	List<T>

	pop() : T Pop element from back of list	List<T>
	shift() : T Pop element from front of list	List<T>
	remove(obj:const T) : Bool Remove given element from list	List<T>
	merge(xs:const List<T>) Merges the input list with 'this'	List<T>

Public Static Methods

	Method	Defined By
	static fromArray(array:const Array<T>) : List<T> Construct List from Array type.	List<T>
	static fromVector(vector:const flash.Vector<T>) : List<T> (flash9+) Construct List from Vector type.	List<T>

Property Detail

length

property

readonly property length : Int

Number of elements in list

Method Detail

empty

method

const function empty() : Bool

Returns whether list is empty or not

This is usually an O(1) operation.

copy

method

const function copy() : List<T>

Performs a shallow copy on the list
(Note: If List was immutable then copied list will now be mutable, equally any restrictions placed on the original list and what can be done with it are revoked such as if old list could not have same object added twice, the copied list will allow it)

This is an O(n) operation.

method

const function at(index:Int) : T

Returns element in list at given index

Normally this operation due to underlying list structure would be an O(n) operation, for the purposes of speed; optimisations are in place that make sequential access in general O(1).

Error if:

index < 0 || index >= length

iterator

method

const function iterator() : ListIterator<T>

This is a standard haXe iterator for haXe users of nape, though nothing stopping AS3 users using the iterators either. The iterator internally uses the at() operation on the list and so is subject to the same optimisation concerns (Note: this means that performing nested iteration will only be optimised for the innermost loop)

foreach

method

const function foreach(lambda:T->Void) : Void

Whilst perhaps of less use in haXe where we can use native iteration, in AS3 using this method will lead to cleaner code. We can 'break' out of this foreach loop by throwing an exception, or 'continue' by returning.

list.foreach(function (elem:T) { trace(elem); });

filter

method

function filter(lambda:T->Bool) : List<T>

Apply the argument to each element of the list, removing all elements for which the function returns false. The return value of this function is the list itself, not a new list!!. If an exception is thrown by the lambda, the filter loop will be broken and the rest of the list assumed to be included in the result.

Compare:

var i = 0;
while(i<list.length) {
   var elem = list.at(i);
   if(/*elem should be removed*/) {
      list.remove(elem);
      continue;
   }
   /*otherwise*/
   i++;
}

with:

list.filter(function(elem:T) {
   if(/*elem should be removed*/) return false;
   /*otherwise*/
   return true;
});

push

method

function push(obj:const T) : Bool

Pushes element to back of list, returns true if operation was successful. Lists in nape tend to be managed, and so this operation may well return false for example trying to push the same shape into a rigid body twice.

Normally this operation due to underlying list structure would be an O(n) operation, for the purpose of speed; optimisations are in place that make sequential pushing in general O(1).

Error if:

List is immutable

unshift

method

function unshift(obj:const T) : Bool

Pushes element to front of list, returns true if operation was successful. (*See push)

This operation is always O(1)

Error if:

List is immutable

add

method

function add(obj:const T) : Bool

Adds element to list returning true on success (*See push), no guarantee is made on where; normally it would be a case of adding to the front of the list but it may be in some cases that it instead adds to the back of list. The choice depends on what is more effecient at that time.

Error if:

List is immutable

pop

method

function pop() : T

Pops element from back of list.

This is always an O(n) operation!

Error if:

List is immutable

shift

method

function shift() : T

Pops element from front of list.

This is always an O(1) operation

Error if:

List is immutable

remove

method

function remove(obj:const T) : Bool

Removes given element from the list, returns true on success. If element exists more than once, the first occurence in list is removed.

This is always an O(n) operation

Error if:

List is immutable

merge

method

function merge(xs:const List<T>)

Merges the input list into the current list, eg: [1,4,7].merge([2,4,5,7]) == [1,2,4,5,7]

This is an ineffecient O(mn) operation for size of lists m and n

static function fromArray(array:const Array<T>) : List<T>

Construct List from Array type.

Error if:

Array contains non T elements.

fromVector

static

method

static function fromVector(vector:const flash.Vector<T>) : List<T>

Construct List from Vector type for flash9+ targets.