• all
• any
• collect
• detect
• each
• eachSlice
• entries
• find
• findAll
• grep
• inGroupsOf
• include
• inject
• invoke
• map
• max
• member
• min
• partition
• pluck
• reject
• select
• size
• sortBy
• toArray
• zip

Enumerable provides a large set of useful methods for enumerations, that is, objects that act as collections of values. It is a cornerstone of Prototype.

Enumerable is what we like to call a module: a consistent set of methods intended not for independent use, but for mixin: incorporation into other objects that “fit” with it. This meaning of the term “module” is borrowed from the Ruby world, which is fitting enough, since Enumerable attempts to mimic at least part of its Ruby-world namesake.

Quite a few objects, in Prototype, mix Enumerable in already. The most visible cases are Array and Hash, but you’ll find it in less obvious spots as well, such as in ObjectRange and various DOM- or AJAX-related objects.

The context parameter

Every method of Enumerable that takes an iterator also takes the context object as the next (optional) parameter. The context object is what the iterator is going to be binded to, so the this keyword inside of it will point to the object.

var myObject = {};

['foo', 'bar', 'baz'].each(function(name, index) {
  this[name] = index;
}, myObject); // we have specified the context

myObject
//-> { foo: 0, bar: 1, baz: 2}

If there is no context argument, the iterator function will preserve the scope it would have anyway.

Aliases: it’s all about having it your way

Just like its Ruby counterpart, Enumerable cares about your comfort enough to provide more than one name for a few behaviors. This is intended to reduce your learning curve when your technical background made you familiar with one name or another. However, the documentation attempts to clearly state when one name is “preferred” over the other (perhaps due to readability, widely accepted intuitiveness, etc.).

Here are the aliases you’ll find in Enumerable:

• map is the same as collect.
• find is the preferred way of using detect.
• findAll is the same as select.
• include is the same as member.
• entries is the same as toArray.

Using it efficiently

When using Enumerable, beginners often create sub-par code, performance-wise, by simple lack of familiarity with the API. There are several use cases when one method will be significantly faster (and often make for more readable code!) than another. Here are the two main points about this.

collect, invoke, pluck and each: thinking about the use case

Beginners tend to use each whenever they need to manipulate all elements in the enumeration, and collect whenever they need to yield a value the same way for each element. This is the proper way for the generic case, but there are specific use cases where it can be written way more concisely, more elegantly, and with much better performance.

• When you need to invoke the same method on all the elements, go with invoke.
• When you need to fetch the same property on all the elements, go with pluck.

reject and findAll vs. partition

The findAll/select methods retrieve all the elements that match a given predicate. Conversely, the reject method retrieves all the elements that do not match a predicate. In the specific case where you need both sets, you can avoid looping twice: just use partition.

Mixing Enumerable in your own objects

So, let’s say you’ve created your very own collection-like object (say, some sort of Set, or perhaps something that dynamically fetches data ranges from the server side, lazy-loading style). You want to be able to mix Enumerable in (and we commend you for it). How do you go about this?

The Enumerable module basically makes only one requirement on your object: it must provide a method named _each (note the leading underscore), that will accept a function as its unique argument, and will contain the actual “raw iteration” algorithm, invoking its argument with each element in turn.

As detailed in the documentation for each, Enumerable provides all the extra layers (handling iteration short-circuits, passing numerical indices, etc.). You just need to implement the actual basic iteration, as fits your internal structure.

If this leaves you goggling, just have a look at Prototype’s Array, Hash or ObjectRange objects’ source code. They all begin with their own _each method, which should help you grasp the idea.

Once you’re done with this, you just need to mix Enumerable in, which you’ll usually do before defining your methods, so as to make sure whatever overrides you provide for Enumerable methods will indeed prevail. In short, your code will probably end up looking like this:

var YourObject = Class.create();
Object.extend(YourObject.prototype, Enumerable);
Object.extend(YourObject.prototype, {
  initialize: function() { // with whatever constructor arguments you need
    // Your construction code
  },

  _each: function(iterator) {
    // Your iteration code, invoking iterator at every turn
  },

  // Your other methods here, including Enumerable overrides
});

Then, obviously, your object can be used like this:

var obj = new YourObject();
// Whatever use here, e.g. to fill it up
obj.pluck('somePropName');
obj.invoke('someMethodName');
obj.size();
// etc.

Methods

all([iterator = Prototype.K[, context]]) -> Boolean

any([iterator = Prototype.K[, context]]) -> Boolean

collect(iterator[, context]) -> Array

detect(iterator[, context]) -> firstElement | undefined

each(iterator[, context]) -> Enumerable

eachSlice(size[, iterator = Prototype.K[, context]]) -> [slice...]

entries() -> Array

find(iterator) -> firstElement | undefined

findAll(iterator[, context]) -> Array

grep(regex[, iterator = Prototype.K[, context]]) -> Array

inGroupsOf(size[, filler = null]) -> [group...]

include(object) -> Boolean

inject(accumulator, iterator[, context]) -> accumulatedValue

invoke(methodName[, arg...]) -> Array

map(iterator) -> Array

max([iterator = Prototype.K[, context]]) -> maxValue

member(object) -> Boolean

min([iterator = Prototype.K[, context]]) -> minValue

partition([iterator = Prototype.K[, context]]) -> [TrueArray, FalseArray]

pluck(propertyName) -> Array

reject(iterator[, context]) -> Array

select(iterator) -> Array

size() -> Number

sortBy(iterator[, context]) -> Array

toArray() -> Array

zip(Sequence...[, iterator = Prototype.K]) -> Array