The SC.Enumerable mixin describes a generic interface for accessing any kind of collection, ordered or unordered.  Unless you are working with a private array, you should always use SC.Enumerable (and SC.Array) methods to work with collections of objects (such as Arrays).  SC.Enumerable methods are almost as fast as native functions provided by Array but they can also work with a broader range of objects and work properly with key value observing.

This section will explain how to work with objects that use the SC.Enumerable API.

Basic Iterating

Enumerables may be ordered or unordered.  An ordered enumerable is like an Array - objects appear in a specific order, which you can usually access by a specific value.  Unordered enumerables do not guarantee that your objects will be stored in any particular order.  However they will often be faster at other operations such as adding/remove items to testing for membership.

Since enumerables may be unordered, you cannot access a generic enumerable's content by a specific index.  Instead, you must iterate through the contents when you want to work with their contents.  The most common way you iterate through an enumerable is with the forEach() method:

var set = SC.Set.create(1,2,3);

set.forEach(function(item) {

  console.log(item);

}, this);

> 1

> 2

> 3

forEach() as defined on SC.Enumerable works exactly like the forEach() method defined in JavaScript 1.6.  The first parameter you pass should be a callback function that will be invoked once for each item in the enumerable.  An optional second parameter is a target object that will become the value of "this" when the callback is invoked.

IMPORTANT: Whenever you want to invoke a callback in forEach() or any of the other iterators defined here, you should generally pass "this" as the second parameter to make your callback work like other code in the same method.  You do not need to .bind() or otherwise prepare your function callback before passing it to forEach().

The callback you pass into forEach() should have the following signature:

function callback(item, index, enumerable) { ... }

The following parameters are passed to the callback.   If you don't care about some of the parameters, you can define your function to receive fewer parameters instead:

• item: the current item in the iteration
• index: the current index in the iteration.  For unordered enumerables, this is just a number that will increase each time your callback is invoked.  It has no meaning to the actual internal structure of the enumerable.
• enumerable: the enumerable you are iterating over

Note that modifying an enumerable from within an iterator will have an unknown effect on how the rest of your methods will be called.  You should invoke this with caution.

...MORE TO COME