Nape list of Shape type objects

Internally this list is at present implemented as a linked list with object pooled nodes and iterators with various fast paths made for standard access patterns (For instance accessing successive elements runs in constant time when using random access functions)

Iteration of this list can be done in various ways, but the preferred way on all targets, is through use of the foreach function:

list.foreach(function (obj) {
});
This method is inlined so that in haxe no closure will need to be created.

In AS3, a closure would need to be created in general, so for performance reasons you 'may' choose to use iteration as follows:
for (var i:int = 0; i < list.length; i++) {

var obj:Shape = list.at(i);

}


NOTE: It is 'not' safe to modify a list whilst iterating over it. If you wish to remove elements during an iteration you should use the filter method, for example:
list.filter(function (obj) {

// operate on object.
// ...
return (false if you want object to be removed);

});



In AS3, if you wish to avoid a closure generation, you can perform such an iteration in a safe manner as follows:
var i:int = 0;
while (i < list.length) {

var obj:Shape = list.at(i);
// operate on object.
// ...
if (should remove obj) {
    list.remove(obj);
    continue;
}
else i++;

}

Or if you are always clearing the list entirely you could write:
while (!list.empty()) {

var obj:Shape = list.pop();
// operate on object.
// ...

}

Static methods

staticfromArray(array:Array<Shape>):ShapeList

Convert standard Array to Nape list.

Parameters:

array

The array to be converted

Returns:

An equivalent Nape list.

Throws:

If

array argument is null.

If

array contains elements of type other than Shape

Constructor

new()

Construct a new list.

Variables

@:value(null)zpp_inner:ZPP_ShapeList = null

@private

read onlylength:Int

Length of list.

Methods

has(obj:Shape):Bool

Check if element is already in the list

Parameters:

obj

The object to test.

Returns:

True if object is in the list.

at(index:Int):Shape

Random access to elements of list by index.

Under normal circumstances, accessing succesive elements via this method will occur in constant time.

Parameters:

index

The index of the element in list to access.

Returns:

The element at the given index.

Throws:

#

If index is out of bounds.

push(obj:Shape):Bool

Push element to back of list.

When the order of objects is not important, it is best to use the add() method instead.

Parameters:

obj

The object to insert.

Returns:

True if object was successively inserted.

Throws:

#

If list is immutable.

unshift(obj:Shape):Bool

Push element to front of list.

When the order of objects is not important, it is best to use the add() method instead.

Parameters:

obj

The object to insert.

Returns:

True if object was successively inserted.

Throws:

#

If list is immutable.

pop():Shape

Pop element from back of list.

If you are wanting to clear a list, whilst operating on its elements, consider use of the filter method instead.

Returns:

The element removed from list.

Throws:

#

If list is immutable.

#

If the list is empty.

shift():Shape

Pop element from front of list.

If you are wanting to clear a list, whilst operating on its elements, consider use of the filter method instead.

Returns:

The element removed from list.

Throws:

#

If list is immutable.

#

If the list is empty.

inlineadd(obj:Shape):Bool

Insert element into list in most effecient way.

This method will defer to either the push or unshift function depending on which is most effecient in the context.

If order of elements is not important then you should always use this function to insert elements.

Parameters:

obj

The object to insert.

Returns:

True if object was successfuly inserted.

Throws:

#

If list is immutable

remove(obj:Shape):Bool

Remove element from list.

This is a linear time operation.

Parameters:

obj

The object to remove

Returns:

True if object was removed from list.

Throws:

#

If list is immutable

clear():Void

Clear the list, removing all elements.

Throws:

#

If list is iummutable

inlineempty():Bool

Test if list is empty or not.

Returns:

True if list is empty.

inlineiterator():ShapeIterator

Return Haxe iterator for list.

Use of this iterator, whilst stylistically better in Haxe should not be used, in preference for use of the foreach function which will not require allocation of an iterator object.

Equally in AS3, the foreach method should be the preferred way to iterate.

@:value({ deep : false })copy(deep:Bool = false):ShapeList

Produce a possibly deep copy of list.

Parameters:

deep

If true, then each element will have its own copy function called instead of simply having its reference copied over.

Returns:

The copied list.

merge(xs:ShapeList):Void

Merge given list into this one.

The result is that this list will have all objects from the argument that were not already in the list inserted. You should make no assumption about the order of these insertions.

Parameters:

xs

The list to merge.

Throws:

#

If xs argument is null.

@:keeptoString():String

@private

inlineforeach(lambda:Shape ‑> Void):ShapeList

Iterate over list applying function.

Any exception thrown by the supplied function will be treat as a signal to halt iteration acting as a 'break' statement.

This method should be preferred to using standard haxe iteration as there will be no allocation of an iterator object.

list.foreach(function (obj) {

if (ignore_object(obj)) return; //acts as a 'continue' statement
if (halt_iteration(obj)) throw "": //acts as a 'break' statement

});

Parameters:

lambda

The function to apply to each argument.

Returns:

A reference to 'this' list.

Throws:

#

If lambda argument is null.

filter(lambda:Shape ‑> Bool):ShapeList

Iterate over list filtering elements.

The given function will be applied to each element, whenever the function returns false, the element will be removed from the list.

Any exception thrown by the supplied function will be treat as a signal to halt iteration acting as a 'break' statement.

This method is to be greatly preferred for filtering logic as it is otherwise unsafe to modify the list during an iteration.

An example of using this method to clean up a list whilst performing actions on the elements.

list.filter(function (obj) {
// perform clean up with obj
return false; // remove from list.
});

Parameters:

lambda

The function to apply to each argument, deciding if element should be removed.

Returns:

A reference to 'this' list.

Throws:

#

If lambda argument is null.