each(callback, arguments)

Calls a function on each element in the collection in forward order

The following example modifies items in the collection in the order they were added:

var collection = new Collection(['one', 'two', 'three']);
collection.reach( function(element, index, elements){ trace(element); } );

one
two
three

reach(callback, arguments)

Calls a function on each element in the collection in reverse order

Processing elements in reverse order is usually necessary when deleting elements from the collection.

For the sake of brevity, the following example traces the items in the collection in reverse order:

var collection = new Collection(['one', 'two', 'three']);
collection.reach( function(element, index, elements){ trace(element); } );

three
two
one

indexOf(element, fromIndex)

Returns the first index at which a given element can be found in the array, or -1 if it is not present

The following example displays the 0-based index of the item "two":

var collection = new Collection(['one', 'two', 'three']);
trace(collection.indexOf('two'));

1

get(index)

Gets an element from the collection

The following example returns the second item in the collection:

var collection = new Collection(['one', 'two', 'three']);
trace(collection.get(1));

two

find(value, property)

Finds and returns elements (by name, or other property) within the collection

The following example finds and returns the reference to the element named "star3":

var collection = new Collection($selection);
var star = collection.find('star3').pop();
trace(star);

[object SymbolInstance]

The following example uses a wildcard to identify all elements whose names start with the word "star", then selects them on stage:

var collection = new Collection($selection);
$selection = collection.find('star*');

The following example uses a Regular Expression to find and return all elements whose names end with 1, 2, or 3. Note that the ElementCollection is returned using the ElementSelector function:

var elements = $('*').find(/[123]$/);

Note that by default, the property matched in all find operations is name, but the second argument allows you to use an alternative property.

In this example, an array of graphic objects is passed in, then the ones which are set to play once are returned from the find() operation:

var collection = new Collection(graphics);
var elements = collection.find('play once', 'loop');
list(elements);

[object ElementCollection length=3]: Array (depth:1, objects:0, values:3, time:0.0 seconds)
-------------------------------------------------------------------------------------------
array => Array
	 0: "item: 2 - elements/shapes/square"
	 1: "item: 2 - elements/shapes/triangle"
	 2: "item: 2 - elements/shapes/square" 

Whilst this is a good way to grab items from an existing collection, creating a new collection from scratch could be more-easily accomplished using the ElementSelector and an attribute expression:

var collection = $('[loop=play once]');	

add(elements)

Adds elements to the collection

The following example adds some new items to the collection:

var collection = new Collection(['one', 'two', 'three']);
collection
    .add([4,5,6])
    .list();

[object Collection length=6]: Array (depth:1, objects:0, values:6, time:0.0 seconds)
------------------------------------------------------------------------------------
array => Array
	 0: "one"
	 1: "two"
	 2: "three"
	 3: 4
	 4: 5
	 5: 6

remove(elementsOrValue, property)

Removes elements from the collection

The following example creates then removes elements from the collection:

var collection = new Collection([1, 2, 3, 4, 5]);
collection
	.list()
	.remove([1, 3, 5])
	.list();

[object Collection length=5]: Array (depth:1, objects:0, values:5, time:0.0 seconds)
------------------------------------------------------------------------------------
array => Array
	 0: 1
	 1: 2
	 2: 3
	 3: 4
	 4: 5


[object Collection length=2]: Array (depth:1, objects:0, values:2, time:0.0 seconds)
------------------------------------------------------------------------------------
array => Array
	 0: 2
	 1: 4

You can also remove elements from the collection in exactly the same way as the find() method works to identify elements to remove.

The following example, first selects all elements on the stage, then removes only the stars:

var collection = new Collection(starsAndSquares);
collection
	.list('All elements')
	.remove('star*')
	.list('Squares only');

All elements: Array (depth:1, objects:0, values:8, time:0.0 seconds)
--------------------------------------------------------------------------------
array => Array
	 0: "name: star4"
	 1: "name: star3"
	 2: "name: star2"
	 3: "name: star1"
	 4: "name: square4"
	 5: "name: square3"
	 6: "name: square2"
	 7: "name: square1"


Squares only: Array (depth:1, objects:0, values:4, time:0.0 seconds)
--------------------------------------------------------------------------------
array => Array
	 0: "name: square4"
	 1: "name: square3"
	 2: "name: square2"
	 3: "name: square1"

filter(callback, thisObject)

Filters the collection using a callback function

The following example filters out any elements with the letter "w" in them:

var collection = new Collection(['one', 'two', 'three']);
collection
    .filter( function(element){ return element.indexOf('w') == -1; } )
    .list();

[object Collection length=2]: Array (depth:1, objects:0, values:2, time:0.0 seconds)
------------------------------------------------------------------------------------
array => Array
	 0: "one"
	 1: "three"

attr(name, value)

Modifies a particular attribute on all items in the collection

As this method modifies the properties of objects, stage elements will be used instead of strings for the examples. Before running the examples, create or drag some movieclip instances into random positions on the stage.

The following example modifies the "y" property of selected elements to position them 100px from the top:

var collection = new Collection($selection);
collection.attr('y', 100);

The following example modifies 2 properties at the same time, using an Object of named values:

var collection = new Collection($selection);
collection.attr( {'y':100, rotation:45} );

The following example modifies the "x" property of selected elements, using a callback function to position them sequentially from left to right on stage:

var collection = new Collection($selection);
collection.attr( 'x', function(element, index, elements){ return index * 100; } );

A similar result could also be achieved using each():

var collection = new Collection($selection);
collection.each( function(element, index, elements){ element.x = index * 100; } );

sort()

Sorts the internal elements of a collection

The following example sorts the collection:

var collection = new Collection([5, 4, 3, 2, 1]);
collection
    .list()
    .sort()
    .list();

Unsorted: Array (depth:1, objects:0, values:5, time:0.0 seconds)
--------------------------------------------------------------------------------
array => Array
	 0: 5
	 1: 4
	 2: 3
	 3: 2
	 4: 1


Sorted: Array (depth:1, objects:0, values:5, time:0.0 seconds)
--------------------------------------------------------------------------------
array => Array
	 0: 1
	 1: 2
	 2: 3
	 3: 4
	 4: 5

list()

Utility function to list the contents of the collection

The following example lists the contents of a collection:

new Collection(['one', 'two', 'three']).list();

[object Collection length=2]: Array (depth:1, objects:0, values:2, time:0.0 seconds)
------------------------------------------------------------------------------------
array => Array
	 0: "one"
	 1: "two"
	 2: "three"

call(callback, ...params)

A chainable utility function to call an external callback function a single time

The call() method allows you to call a single arbitrary function as part of a chain of commands. The function could be one of your own custom functions, or even a method on the current collection should you see fit. Function parameters are added after the callback reference as additional mthod arguments.

The following example calls the native trace function, passing in the collection's elements, then calls an additional collection method, simply to demonstrate chaining:

var collection = new Collection(['one', 'two', 'three']);
var value = collection
    .call(trace, collection.elements)
    .get(0);

trace(value);

one,two,three
one

apply(callback, params, scope)

A chainable utility function to call an external callback function a single time

The apply() method has exactly the same function as the call() method, allowing you to call a single function as part of a chain of commands, but passes the callback parameters as an Array, an optionally allows you to set the scope of the call as well.

The following example calls a trace method on an object, the first scoped to the collection (by default) and the second scoped to the object:

var obj =
{
	elements:['x', 'y', 'z'],
	trace:function(a, b)
	{
		trace(a, b, this.elements);
	}
}

var collection = new Collection(['one', 'two', 'three']);

var value = collection
    .apply(obj.trace, ['a', 'b']) // will trace the collection's elements
    .apply(obj.trace, ['a', 'b'], obj) // will trace obj's elements
    .get(0);

trace(value);

a, b, one,two,three
a, b, x,y,z
one

toString()

Return a string representation of the collection

The following example demonstrates the result of tracing a collection:

var collection = new Collection(['one', 'two', 'three']);
trace(collection);

[object Collection length=3]