4.4.4. Enumerable

The Enumerable object contains methods for iterating over items in a list-like structure. The methods are added to other classes, such as Array, Hash, and ObjectRange. Most of the Enumerable methods accept an iterator argument—a function that will be applied to each member of the collection. In all methods, the argument interator is a function object conforming to Function(value, index).

each( iterator)

Calls iterator passing each element in the list in the first argument and the index of the element in the second argument.

all([ iterator])

This function is a way to test the entire collection of values using a given function. all will return false if iterator returns false or null for any of the elements. It will return true otherwise. If iterator is not given, then the test will be if the element itself is different than false or null. You can simply read it as "check if all elements are not-false."

any([ iterator])

This function is a way to test the entire collection of values using a given function. any will return true if iterator does not return false or null for any of the elements. It will return false otherwise. If iterator is not given, then the test will be if the element itself is different than false or null. You can simply read it as "check if any element is not-false."

collect( iterator)

Calls iterator for each element in the collection and returns each result in an Array, one result element for each element in the collection, in the same sequence.

detect( iterator)

Calls iterator for each element in the collection and returns the first element that caused iterator to return true (or, more precisely, not-false). Returns null if no element returns true.

entries()

Same as toArray().

find( iterator)

Same as detect().

findAll( iterator)

Calls iterator for each element in the collection and returns an Array with all the elements that caused iterator to return a value that resolves to true. This function is the opposite of reject().

grep(pattern [, iterator])

Tests the string value of each element in the collection against the pattern (a RegExp object). The function will return an Array containing all the elements that matched pattern. If iterator is given, then the Array will contain the result of calling iterator with each element that was a match.

include( obj)

Tries to find obj (any object) in the collection. Returns true if the object is found, false otherwise.

inject( initialValue, iterator)

Unlike the other Enumerable methods, inject's iterator argument should conform to Function(accumulator, value, index). Combines all the elements of the collection using iterator. The iterator is called passing the result of the previous iteration in the accumulator argument, except the first iteration, which gets initialValue (which can be any object). The last result is the final return value.

invoke(methodName [, arg1 [, arg2 [...]]])

Calls the method specified by methodName in each element of the collection, passing any given arguments (arg1 to argN), and returns the results in an Array object.

map( iterator)

Same as collect().

max([ iterator])

Returns the element with the greatest value in the collection or the greatest result of calling iterator on each element in the collection, if iterator is given.

member( obj)

Same as include().

min([ iterator])

Returns the element with the lowest value in the collection or the lowest result of calling iterator on each element in the collection, if iterator is given.

partition([ iterator])

Returns an Array containing two other arrays. The first array will contain all the elements that caused iterator to return true and the second array will contain the remaining elements. If iterator is not given, then the first array will contain the elements that resolve to true and the other array will contain the remaining elements.

pluck(propertyName)

Retrieves the value of the property specified by propertyName (which can also be the index of the element) in each element of the collection and returns the results in an Array object.

reject( iterator)

Calls iterator for each element in the collection and returns an Array with all the elements that caused iterator to return a value that resolves to false. This function is the opposite of findAll().

select( iterator)

Same as findAll().

sortBy( iterator)

Returns an Array with all the elements sorted according to the result of the iterator call.

toArray()

Returns an Array with all the elements of the collection.

zip(collection1[, collection2 [, ... collectionN [, transform]]])

Merges each given collection with the current collection. The merge operation returns a new array with the same number of elements as the current collection and each element is an array of the elements with the same index from each of the merged collections. If transform is given (a function object conforming to Function(value, index)), then each sub-array will be transformed by this function before being returned. Quick example: [1,2,3].zip([4,5,6], [7,8,9]).inspect() returns "[ [1,4,7],[2,5,8],[3,6,9] ]".

4.4.4.1. Examples

Consider a simple example of Enumerable's each() method:

['Bart', 'Lisa', 'Maggie'].each(function(name) { alert(name); } );

Because the Enumerable methods are mixed into the Array class, each() can be used as an instance method on a normal array. The method takes one argument, an iterator function, which is called once for each element in the array.

Consider a more complex example. Here we'll find an element according to some criteria, using Enumerable's find() method.

// <select id="employees">
//   <option value="5">Buchanan, Steven</option>
//   <option value="8">Callahan, Laura</option>
//   <option value="1">Davolio, Nancy</option>
// </select>

function findEmployeeById(id){
  return $$('#employees option'). find( function(employee){
     return (employee.value == id);
  }).innerHTML;
}

findEmployeeById(8);
// => "Callahan, Laura"