Array Collection (mx.collections.ArrayCollection)

ArrayCollection is an oft-used, powerful collection class found in the mx.collections package.

An ArrayCollection is an ordered, unbound collection of object references. Ordered means each item added to a collection has a specific index (starting at 0). Unbound means the collection will automatically grow as more items are added. And because a collection holds references, an item can be in a collection more than once.

Let's see ArrayCollection in action:

   import mx.collections.ArrayCollection;
   
   // create an ArrayCollection
   var collection:ArrayCollection = new ArrayCollection();
   
   // create a dummy object
   var item:Object = new Object();
   
   
   // add an item to the end
   collection.addItem( item );
   
   // check if an item is in a collection
   var belongs:Boolean = collection.contains( item );
   
   // get the index of an item
   var index:int = collection.getItemIndex( item );
   
   // get an item by its index
   item = collection.getItemAt( index );
   
   // remove an item by it's index
   collection.removeItemAt( index );
   
   // add an item at a specific index
   collection.addItemAt( item, 0 );
   
   // remove all the items
   collection.removeAll();

Array Wrapping

An ArrayCollection is really a wrapper around an Array. You can easily get an Array into/out of an ArrayCollection. Note, that adding and removing items from an ArrayCollection also adds and removes the items from the underlying Array.

   // wrap an Array with an ArrayCollection
   var array:Array = [ "A", "B", "C", "D", "E" ];
   var collection:ArrayCollection = new ArrayCollection( array );
   
   trace( array.length ); // 5
   trace( collection.length ); // 5
   
   // removing an item from the collection also removes it from the array
   collection.removeItemAt( 2 );
      
   trace( array.length ); // 4
   trace( collection.length ); // 4
   
   // get the collection contents as an array
   var array2:Array = collection.toArray();

Looping

Looping over a collection can done via "for" and "for each":

   // loop through each element using "for each"
   var numbers:ArrayCollection = new ArrayCollection( [1, 2, 3, 4, 5] );
   var number:String;
   for each( number in numbers )
   {
      trace( number );
   }
   
   // loop through each element of an array using "for"
   var letters:ArrayCollection = new ArrayCollection( ["A", "B", "C", "D", "E"] );
   var index:int;
   for( index = 0; index < letters.length; index++ )
   {
      trace( "Element " + index + " is " + letters[index] );
   }

Collection Binding and Events

One very powerful feature of an ArrayCollection (and similar collections) is automatic monitoring of the objects inside the collection.

Read more about about Collection Events.

Miscellaneous Collection Information

Items Added Multiple Times

Note, items can be added to a collection more than once. However, a call to getItemIndex() will return the first index of the item.

   // add the same item to a collection 3 times
   collection.addItem( item );
   collection.addItem( item );
   collection.addItem( item );
   
   // the length of the collection is 3
   trace( collection.length );
   // the returned index of the item is 0 (even though it exists at indexes 0, 1, and 2)
   trace( collection.getItemIndex(item) );

Packed Indexes

Note, ArrayCollections are packed. This means when an item is removed, all the indexes of the other items in the collection are updated to be sequential without gaps. So for a collection with N items, the indexes of its items will always be 0 through N-1.

   // add several items to a collection
   collection.addItem( "A" );
   collection.addItem( "B" );
   collection.addItem( "C" );
   collection.addItem( "D" );
   collection.addItem( "E" );
   
   // get the index of "E"
   trace( collection.getItemIndex("E") ); // returns 4
   // remove "C"
   collection.removeItemAt( 2 );
   // get the index of "E"
   trace( collection.getItemIndex("E") ); // returns 3

Collection Sorting, Filtering, and Refreshing

Learn more about Collection sorting, filtering, and refreshing...