A class which provides a method `each’ to be used as an Enumerable object.
An enumerator can be created by following methods.
Kernel#to_enum
Kernel#enum_for
Also, most iteration methods without a block returns an enumerator. For example, Array#map returns an enumerator if a block is not given. The enumerator has the with_index method. So ary.map.with_index works as follows.
p %w[foo bar baz].map.with_index {|w,i| "#{i}:#{w}" } #=> ["0:foo", "1:bar", "2:baz"]
An enumerator object can be used as an external iterator. I.e. Enumerator#next returns the next value of the iterator. Enumerator#next raises StopIteration at end.
e = [1,2,3].each # returns an enumerator object. p e.next #=> 1 p e.next #=> 2 p e.next #=> 3 p e.next #raises StopIteration
An external iterator can be used to implement an internal iterator as follows.
def ext_each(e) while true begin vs = e.next_values rescue StopIteration return $!.result end y = yield(*vs) e.feed y end end o = Object.new def o.each p yield p yield(1) p yield(1, 2) 3 end # use o.each as an internal iterator directly. p o.each {|*x| p x; [:b, *x] } #=> [], [:b], [1], [:b, 1], [1, 2], [:b, 1, 2], 3 # convert o.each to an external iterator for # implementing an internal iterator. p ext_each(o.to_enum) {|*x| p x; [:b, *x] } #=> [], [:b], [1], [:b, 1], [1, 2], [:b, 1, 2], 3
Creates a new Enumerator object, which is to be used as an Enumerable object iterating in a given way.
In the first form, a generated Enumerator iterates over the given object using the given method with the given arguments passed. Use of this form is discouraged. Use Kernel#enum_for(), alias to_enum, instead.
e = Enumerator.new(ObjectSpace, :each_object) #-> ObjectSpace.enum_for(:each_object) e.select { |obj| obj.is_a?(Class) } #=> array of all classes
In the second form, iteration is defined by the given block, in which a “yielder” object given as block parameter can be used to yield a value by calling the yield method, alias +<<+.
fib = Enumerator.new { |y| a = b = 1 loop { y << a a, b = b, a + b } } p fib.take(10) #=> [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
static VALUE
enumerator_initialize(int argc, VALUE *argv, VALUE obj)
{
VALUE recv, meth = sym_each;
if (argc == 0) {
if (!rb_block_given_p())
rb_raise(rb_eArgError, "wrong number of argument (0 for 1+)");
recv = generator_init(generator_allocate(rb_cGenerator), rb_block_proc());
}
else {
recv = *argv++;
if (--argc) {
meth = *argv++;
--argc;
}
}
return enumerator_init(obj, recv, meth, argc, argv);
}
Iterates the given block using the object and the method specified in the first place. If no block is given, returns self.
static VALUE
enumerator_each(VALUE obj)
{
if (!rb_block_given_p()) return obj;
return enumerator_block_call(obj, 0, obj);
}
Same as Enumerator#with_index, except each_with_index does not receive an offset argument.
static VALUE
enumerator_each_with_index(VALUE obj)
{
return enumerator_with_index(0, NULL, obj);
}
Iterates the given block for each element with an arbitrary object given, and returns the initially given object.
If no block is given, returns an enumerator.
static VALUE
enumerator_with_object(VALUE obj, VALUE memo)
{
RETURN_ENUMERATOR(obj, 1, &memo);
enumerator_block_call(obj, enumerator_with_object_i, memo);
return memo;
}
Set the value for the next yield in the enumerator returns.
If the value is not set, the yield returns nil.
This value is cleared after used.
o = Object.new def o.each # (2) x = yield p x #=> "foo" # (5) x = yield p x #=> nil # (7) x = yield # not reached p x end e = o.to_enum # (1) e.next # (3) e.feed "foo" # (4) e.next # (6) e.next # (8)
static VALUE
enumerator_feed(VALUE obj, VALUE v)
{
struct enumerator *e = enumerator_ptr(obj);
if (e->feedvalue != Qundef) {
rb_raise(rb_eTypeError, "feed value already set");
}
e->feedvalue = v;
return Qnil;
}
Create a printable version of e.
static VALUE
enumerator_inspect(VALUE obj)
{
return rb_exec_recursive(inspect_enumerator, obj, 0);
}
Returns the next object in the enumerator, and move the internal position forward. When the position reached at the end, StopIteration is raised.
a = [1,2,3] e = a.to_enum p e.next #=> 1 p e.next #=> 2 p e.next #=> 3 p e.next #raises StopIteration
Note that enumeration sequence by next method does not affect other non-external enumeration methods, unless underlying iteration methods itself has side-effect, e.g. IO#each_line.
static VALUE
enumerator_next(VALUE obj)
{
VALUE vs = enumerator_next_values(obj);
return ary2sv(vs, 0);
}
Returns the next object as an array in the enumerator, and move the internal position forward. When the position reached at the end, StopIteration is raised.
This method can be used to distinguish yield and yield nil.
o = Object.new def o.each yield yield 1 yield 1, 2 yield nil yield [1, 2] end e = o.to_enum p e.next_values p e.next_values p e.next_values p e.next_values p e.next_values e = o.to_enum p e.next p e.next p e.next p e.next p e.next ## yield args next_values next # yield [] nil # yield 1 [1] 1 # yield 1, 2 [1, 2] [1, 2] # yield nil [nil] nil # yield [1, 2] [[1, 2]] [1, 2]
Note that enumeration sequence by next_values method does not affect other non-external enumeration methods, unless underlying iteration methods itself has side-effect, e.g. IO#each_line.
static VALUE
enumerator_next_values(VALUE obj)
{
struct enumerator *e = enumerator_ptr(obj);
VALUE vs;
if (e->lookahead != Qundef) {
vs = e->lookahead;
e->lookahead = Qundef;
return vs;
}
return get_next_values(obj, e);
}
Returns the next object in the enumerator, but don’t move the internal position forward. When the position reached at the end, StopIteration is raised.
a = [1,2,3] e = a.to_enum p e.next #=> 1 p e.peek #=> 2 p e.peek #=> 2 p e.peek #=> 2 p e.next #=> 2 p e.next #=> 3 p e.next #raises StopIteration
static VALUE
enumerator_peek(VALUE obj)
{
VALUE vs = enumerator_peek_values(obj);
return ary2sv(vs, 1);
}
Returns the next object as an array in the enumerator, but don’t move the internal position forward. When the position reached at the end, StopIteration is raised.
o = Object.new def o.each yield yield 1 yield 1, 2 end e = o.to_enum p e.peek_values #=> [] e.next p e.peek_values #=> [1] p e.peek_values #=> [1] e.next p e.peek_values #=> [1, 2] e.next p e.peek_values # raises StopIteration
static VALUE
enumerator_peek_values_m(VALUE obj)
{
return rb_ary_dup(enumerator_peek_values(obj));
}
Rewinds the enumeration sequence by the next method.
If the enclosed object responds to a “rewind” method, it is called.
static VALUE
enumerator_rewind(VALUE obj)
{
struct enumerator *e = enumerator_ptr(obj);
rb_check_funcall(e->obj, id_rewind, 0, 0);
e->fib = 0;
e->dst = Qnil;
e->lookahead = Qundef;
e->feedvalue = Qundef;
e->stop_exc = Qfalse;
return obj;
}
Iterates the given block for each element with an index, which starts from offset. If no block is given, returns an enumerator.
static VALUE
enumerator_with_index(int argc, VALUE *argv, VALUE obj)
{
VALUE memo;
rb_scan_args(argc, argv, "01", &memo);
RETURN_ENUMERATOR(obj, argc, argv);
memo = NIL_P(memo) ? 0 : (VALUE)NUM2LONG(memo);
return enumerator_block_call(obj, enumerator_with_index_i, (VALUE)&memo);
}
Iterates the given block for each element with an arbitrary object given, and returns the initially given object.
If no block is given, returns an enumerator.
static VALUE
enumerator_with_object(VALUE obj, VALUE memo)
{
RETURN_ENUMERATOR(obj, 1, &memo);
enumerator_block_call(obj, enumerator_with_object_i, memo);
return memo;
}