# Ruby Programming/Reference/Objects/Enumerable
## Enumerable

Enumerator appears in Ruby as Enumerable::Enumerator in 1.8.x and (just) Enumerator in 1.9.x.

# Forms of Enumerator

There are several different ways in which an Enumerator can be used:
* As a proxy for “each”
* As a source of values from a block
* As an external iterator

## 1. As a proxy for “each”

This is the first way of using Enumerator, introduced in ruby 1.8. It solves the following problem: Enumerable methods like #map and #select call #each on your object, but what if you want to iterate using some other method such as #each_byte or #each_with_index?
An Enumerator is a simple proxy object which takes a call to #each and redirects it to a different method on the underlying object.
The call to ‘enum_for’ (or equivalently ‘to_enum’) creates the Enumerator proxy. It is a shorthand for the following:
In ruby 1.9, Enumerable::Enumerator has changed to just Enumerator

## 2. As a source of values from a block

In ruby 1.9, Enumerator.new can instead take a block which is executed when #each is called, and directly yields the values.
“g << 1” is an alternative syntax for “g.yield 1”
No fancy language features such as Fiber or Continuation are used, and this form of Enumerator is easily retro-fitted to ruby 1.8
It is quite similar to creating your own object which yields values:
However it also lays the groundwork for “lazy” evaluation of enumerables, described later.

## 3. As an external iterator

ruby 1.9 also allows you turn an Enumerator around so that it becomes a “pull” source of values, sometimes known as “external iteration”. Look carefully at the difference between this and the previous example:
The flow of control switches back and forth, and the first time you call #next a Fiber is created which holds the state between calls. Therefore it is less efficient that iterating directly using #each.
When you call #next and there are no more values, a StopIteration exception is thrown. This is silently caught by the while loop. StopIteration is a subclass of IndexError which is a subclass of StandardError.
The nearest equivalent feature in ruby 1.8 is Generator, which was implemented using Continuations.

# Lazy evaluation

In an Enumerator with a block, the target being yielded to is passed as an explicit parameter. This makes it possible to set up a chain of method calls so that each value is passed left-to-right along the whole chain, rather than building up intermediate arrays of values at each step.
The basic pattern is an Enumerator with a block which processes input values and yields (zero or more) output values for each one.
So let’s wrap this in a convenience method:
This new method ‘defer’ can be used as a ‘lazy’ form of both select and map. Rather than building an array of values and returning that array at the end, it immediately yields each value. This means you start getting the answers sooner, and it will work with huge or even infinite lists. Example:
Although we start with a list of a billion items, at the end we only use the first 10 values generated, so we stop iterating once this has been done.
You can get the same capability in ruby 1.8 using the facets library. For convenience it also provides a Denumberable module with lazy versions of familiar Enumerable methods such as map, select and reject.

# Methods which return Enumerators

From 1.8.7 on, many Enumerable methods will return an Enumerator if not given a block.
This means that usually you don’t need to call enum_for explicitly. The very first example on this page reduces to just:
This can lead to somewhat odd behaviour for non-map like methods - when you call #each on the object later, you have to provide it with the “right sort” of block.

# More Enumerator readings

* ticket 707
* enum_for in Strictly Untyped blog
* Generator in Anthony Lewis’ blog

### each_with_index

each_with_index calls its block with the item and its index.

### find_all

find_all returns only those items for which the called block is not false