класс Enumerator

Создаёт новый объект Enumerator, который можно использовать как Enumerable.

Итерация задаётся переданным блоком. В нём объект «yielder», передаваемый в качестве параметра блока, можно использовать для выдачи значения вызовом метода yield (имеющего псевдоним <<):

fib = Enumerator.new do |y|
  a = b = 1
  loop do
    y << a
    a, b = b, a + b
  end
end

fib.take(10) # => [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]

Необязательный параметр можно использовать для ленивого вычисления размера (см. Enumerator#size). Это может быть значение или вызываемый объект.

Создаёт бесконечный перечислитель из любого блока, вызывая его снова и снова. Результат предыдущей итерации передаётся следующей. Если задан initial, он передаётся первой итерации и становится первым элементом перечислителя; если он не задан, первая итерация получает nil, а её результат становится первым элементом итератора.

Вызов StopIteration из блока прекращает итерацию.

Enumerator.produce(1, &:succ)   # => enumerator of 1, 2, 3, 4, ....

Enumerator.produce { rand(10) } # => infinite random number sequence

ancestors = Enumerator.produce(node) { |prev| node = prev.parent or raise StopIteration }
enclosing_section = ancestors.find { |n| n.type == :section }

Использование ::produce вместе с методами Enumerable, такими как Enumerable#detect, Enumerable#slice_after, Enumerable#take_while, позволяет создать альтернативы на основе Enumerator для циклов while и until:

# Find next Tuesday
require "date"
Enumerator.produce(Date.today, &:succ).detect(&:tuesday?)

# Simple lexer:
require "strscan"
scanner = StringScanner.new("7+38/6")
PATTERN = %r{\d+|[-/+*]}
Enumerator.produce { scanner.scan(PATTERN) }.slice_after { scanner.eos? }.first
# => ["7", "+", "38", "/", "6"]

Необязательный ключевой аргумент size задаёт размер перечислителя, который можно получить с помощью Enumerator#size. Это может быть целое число, Float::INFINITY, вызываемый объект (например, лямбда) или nil, обозначающий неизвестный размер. Если аргумент не задан, размер по умолчанию равен Float::INFINITY.

# Infinite enumerator
enum = Enumerator.produce(1, size: Float::INFINITY, &:succ)
enum.size  # => Float::INFINITY

# Finite enumerator with known/computable size
abs_dir = File.expand_path("./baz") # => "/foo/bar/baz"
traverser = Enumerator.produce(abs_dir, size: -> { abs_dir.count("/") + 1 }) {
  raise StopIteration if it == "/"
  File.dirname(it)
}
traverser.size  # => 4

# Finite enumerator with unknown size
calendar = Enumerator.produce(Date.today, size: nil) {
  it.monday? ? raise(StopIteration) : it + 1
}
calendar.size  # => nil

Создаёт новый объект-перечислитель, генерирующий декартово произведение заданных перечисляемых объектов. Это эквивалентно Enumerator::Product.new.

e = Enumerator.product(1..3, [4, 5])
e.to_a #=> [[1, 4], [1, 5], [2, 4], [2, 5], [3, 4], [3, 5]]
e.size #=> 6

Если задан блок, он вызывается с каждым сгенерированным массивом из N элементов, после чего возвращается nil.

Возвращает объект-перечислитель, созданный из этого перечислителя и заданного перечисляемого объекта.

e = (1..3).each + [4, 5]
e.to_a #=> [1, 2, 3, 4, 5]

Выполняет итерацию по блоку в соответствии с тем, как был создан этот Enumerator. Если блок и аргументы не заданы, возвращает self.

Примеры

"Hello, world!".scan(/\w+/)                     #=> ["Hello", "world"]
"Hello, world!".to_enum(:scan, /\w+/).to_a      #=> ["Hello", "world"]
"Hello, world!".to_enum(:scan).each(/\w+/).to_a #=> ["Hello", "world"]

obj = Object.new

def obj.each_arg(a, b=:b, *rest)
  yield a
  yield b
  yield rest
  :method_returned
end

enum = obj.to_enum :each_arg, :a, :x

enum.each.to_a                  #=> [:a, :x, []]
enum.each.equal?(enum)          #=> true
enum.each { |elm| elm }         #=> :method_returned

enum.each(:y, :z).to_a          #=> [:a, :x, [:y, :z]]
enum.each(:y, :z).equal?(enum)  #=> false
enum.each(:y, :z) { |elm| elm } #=> :method_returned

То же, что и Enumerator#with_index(0), то есть начальное смещение отсутствует.

Если блок не задан, возвращается новый Enumerator, содержащий индекс.

Для каждого элемента выполняет заданный блок с произвольным объектом, obj, и возвращает obj

Если блок не задан, возвращается новый Enumerator.

Пример

to_three = Enumerator.new do |y|
  3.times do |x|
    y << x
  end
end

to_three_with_string = to_three.with_object("foo")
to_three_with_string.each do |x,string|
  puts "#{string}: #{x}"
end

# => foo: 0
# => foo: 1
# => foo: 2

Устанавливает значение, которое будет возвращено при следующем вызове yield внутри e.

Если значение не задано, yield возвращает nil.

После выдачи это значение очищается.

# Array#map passes the array's elements to "yield" and collects the
# results of "yield" as an array.
# Following example shows that "next" returns the passed elements and
# values passed to "feed" are collected as an array which can be
# obtained by StopIteration#result.
e = [1,2,3].map
p e.next           #=> 1
e.feed "a"
p e.next           #=> 2
e.feed "b"
p e.next           #=> 3
e.feed "c"
begin
  e.next
rescue StopIteration
  p $!.result      #=> ["a", "b", "c"]
end

o = Object.new
def o.each
  x = yield         # (2) blocks
  p x               # (5) => "foo"
  x = yield         # (6) blocks
  p x               # (8) => nil
  x = yield         # (9) blocks
  p x               # not reached w/o another e.next
end

e = o.to_enum
e.next              # (1)
e.feed "foo"        # (3)
e.next              # (4)
e.next              # (7)
                    # (10)

Создаёт строковое представление e.

Возвращает следующий объект перечислителя и перемещает внутреннюю позицию вперёд. Когда позиция достигает конца, вызывается исключение StopIteration.

Пример

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

См. примечания на уровне класса о внешних итераторах.

Возвращает следующий объект перечислителя в виде массива и перемещает внутреннюю позицию вперёд. Когда позиция достигает конца, вызывается исключение StopIteration.

См. примечания на уровне класса о внешних итераторах.

Этот метод можно использовать, чтобы различать yield и 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]

Возвращает следующий объект перечислителя, не перемещая внутреннюю позицию вперёд. Если позиция уже находится в конце, вызывается исключение StopIteration.

См. примечания на уровне класса о внешних итераторах.

Пример

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.peek   #raises StopIteration

Возвращает следующий объект в виде массива, подобно Enumerator#next_values, но не перемещает внутреннюю позицию вперёд. Если позиция уже находится в конце, вызывается исключение StopIteration.

См. примечания на уровне класса о внешних итераторах.

Пример

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

Возвращает последовательность перечисления к началу.

Если обёрнутый объект поддерживает метод «rewind», он вызывается.

Возвращает размер перечислителя или nil, если его нельзя вычислить лениво.

(1..100).to_a.permutation(4).size # => 94109400
loop.size # => Float::INFINITY
(1..100).drop_while.size # => nil

Обратите внимание, что размер перечислителя может быть неточным, поэтому его следует считать скорее подсказкой. Например, точность размера, переданного в ::new, не проверяется:

e = Enumerator.new(5) { |y| 2.times { y << it} }
e.size # => 5
e.to_a.size # => 2

Другой пример — перечислитель, созданный с помощью ::produce без аргумента size. Такие перечислители возвращают Infinity в качестве размера, однако это значение будет неточным, если переданный блок вызывает StopIteration:

e = Enumerator.produce(1) { it + 1 }
e.size # => Infinity

e = Enumerator.produce(1) { it > 3 ? raise(StopIteration) : it + 1 }
e.size # => Infinity
e.to_a.size # => 4

Для каждого элемента выполняет заданный блок с индексом, который начинается с offset. Если блок не задан, возвращается новый Enumerator с индексом, начинающимся с offset

offset

начальный индекс