module Iterator(T)
Overview
An Iterator allows processing sequences lazily, as opposed to Enumerable which processes
sequences eagerly and produces an Array in most of its methods.
As an example, let's compute the first three numbers in the range 1..10_000_000 that are even,
multiplied by three. One way to do this is:
(1..10_000_000).select(&.even?).map { |x| x * 3 }.first(3) # => [6, 12, 18]The above works, but creates many intermediate arrays: one for the select call,
one for the map call and one for the take call. A more efficient way is to invoke
Range#each without a block, which gives us an Iterator so we can process the operations
lazily:
(1..10_000_000).each.select(&.even?).map { |x| x * 3 }.first(3) # => #< Iterator(T)::First...Iterator redefines many of Enumerable's method in a lazy way, returning iterators
instead of arrays.
At the end of the call chain we get back a new iterator: we need to consume it, either
using each or Enumerable#to_a:
(1..10_000_000).each.select(&.even?).map { |x| x * 3 }.first(3).to_a # => [6, 12, 18]To implement an Iterator you need to define a next method that must return the next
element in the sequence or Iterator::Stop::INSTANCE, which signals the end of the sequence
(you can invoke stop inside an iterator as a shortcut).
For example, this is an iterator that returns a sequence of N zeros:
class Zeros
include Iterator(Int32)
def initialize(@size : Int32)
@produced = 0
end
def next
if @produced < @size
@produced += 1
0
else
stop
end
end
end
zeros = Zeros.new(5)
zeros.to_a # => [0, 0, 0, 0, 0]The standard library provides iterators for many classes, like Array, Hash, Range, String and IO.
Usually to get an iterator you invoke a method that would usually yield elements to a block,
but without passing a block: Array#each, Array#each_index, Hash#each, String#each_char,
IO#each_line, etc.