# <!-- rdoc-file=enumerator.c -->
# A class which allows both internal and external iteration.
#
# An Enumerator can be created by the following methods.
# *   Object#to_enum
# *   Object#enum_for
# *   Enumerator.new
#
#
# Most methods have two forms: a block form where the contents are evaluated for
# each item in the enumeration, and a non-block form which returns a new
# Enumerator wrapping the iteration.
#
#     enumerator = %w(one two three).each
#     puts enumerator.class # => Enumerator
#
#     enumerator.each_with_object("foo") do |item, obj|
#       puts "#{obj}: #{item}"
#     end
#
#     # foo: one
#     # foo: two
#     # foo: three
#
#     enum_with_obj = enumerator.each_with_object("foo")
#     puts enum_with_obj.class # => Enumerator
#
#     enum_with_obj.each do |item, obj|
#       puts "#{obj}: #{item}"
#     end
#
#     # foo: one
#     # foo: two
#     # foo: three
#
# This allows you to chain Enumerators together.  For example, you can map a
# list's elements to strings containing the index and the element as a string
# via:
#
#     puts %w[foo bar baz].map.with_index { |w, i| "#{i}:#{w}" }
#     # => ["0:foo", "1:bar", "2:baz"]
#
# An Enumerator can also be used as an external iterator. For example,
# Enumerator#next returns the next value of the iterator or raises StopIteration
# if the Enumerator is at the end.
#
#     e = [1,2,3].each   # returns an enumerator object.
#     puts e.next   # => 1
#     puts e.next   # => 2
#     puts e.next   # => 3
#     puts e.next   # raises StopIteration
#
# Note that enumeration sequence by `next`, `next_values`, `peek` and
# `peek_values` do not affect other non-external enumeration methods, unless the
# underlying iteration method itself has side-effect, e.g. IO#each_line.
#
# Moreover, implementation typically uses fibers so performance could be slower
# and exception stacktraces different than expected.
#
# You can use this 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
#       puts yield
#       puts yield(1)
#       puts yield(1, 2)
#       3
#     end
#
#     # use o.each as an internal iterator directly.
#     puts o.each {|*x| puts 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.
#     puts ext_each(o.to_enum) {|*x| puts x; [:b, *x] }
#     # => [], [:b], [1], [:b, 1], [1, 2], [:b, 1, 2], 3
#
class Enumerator[unchecked out Elem, out Return] < Object
  include Enumerable[Elem]

  # <!--
  #   rdoc-file=enumerator.c
  #   - enum.each { |elm| block }                    -> obj
  #   - enum.each                                    -> enum
  #   - enum.each(*appending_args) { |elm| block }   -> obj
  #   - enum.each(*appending_args)                   -> an_enumerator
  # -->
  # Iterates over the block according to how this Enumerator was constructed. If
  # no block and no arguments are given, returns self.
  #
  # ### Examples
  #
  #     "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
  #
  def each: () { (Elem arg0) -> untyped } -> Return
          | () -> self

  # <!--
  #   rdoc-file=enumerator.c
  #   - e.feed obj   -> nil
  # -->
  # Sets the value to be returned by the next yield inside `e`.
  #
  # If the value is not set, the yield returns nil.
  #
  # This value is cleared after being yielded.
  #
  #     # 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)
  #
  def feed: (Elem arg0) -> NilClass

  # <!--
  #   rdoc-file=enumerator.c
  #   - Enumerator.new(size = nil) { |yielder| ... }
  # -->
  # Creates a new Enumerator object, which can be used as an Enumerable.
  #
  # 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
  # (aliased as `<<`):
  #
  #     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]
  #
  # The optional parameter can be used to specify how to calculate the size in a
  # lazy fashion (see Enumerator#size). It can either be a value or a callable
  # object.
  #
  def initialize: (?Integer arg0) { (Enumerator::Yielder arg0) -> void } -> void

  # <!--
  #   rdoc-file=enumerator.c
  #   - e.inspect  -> string
  # -->
  # Creates a printable version of *e*.
  #
  def inspect: () -> String

  # <!--
  #   rdoc-file=enumerator.c
  #   - e.next   -> object
  # -->
  # Returns the next object in the enumerator, and move the internal position
  # forward.  When the position reached at the end, StopIteration is raised.
  #
  # ### Example
  #
  #     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
  #
  # See class-level notes about external iterators.
  #
  def next: () -> Elem

  # <!--
  #   rdoc-file=enumerator.c
  #   - e.next_values   -> array
  # -->
  # 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.
  #
  # See class-level notes about external iterators.
  #
  # This method can be used to distinguish `yield` and `yield nil`.
  #
  # ### Example
  #
  #     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]
  #
  def next_values: () -> ::Array[Elem]

  # <!--
  #   rdoc-file=enumerator.c
  #   - e.peek   -> object
  # -->
  # Returns the next object in the enumerator, but doesn't move the internal
  # position forward.  If the position is already at the end, StopIteration is
  # raised.
  #
  # See class-level notes about external iterators.
  #
  # ### Example
  #
  #     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
  #
  def peek: () -> Elem

  # <!--
  #   rdoc-file=enumerator.c
  #   - e.peek_values   -> array
  # -->
  # Returns the next object as an array, similar to Enumerator#next_values, but
  # doesn't move the internal position forward.  If the position is already at the
  # end, StopIteration is raised.
  #
  # See class-level notes about external iterators.
  #
  # ### Example
  #
  #     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
  #
  def peek_values: () -> ::Array[Elem]

  # <!--
  #   rdoc-file=enumerator.c
  #   - e.rewind   -> e
  # -->
  # Rewinds the enumeration sequence to the beginning.
  #
  # If the enclosed object responds to a "rewind" method, it is called.
  #
  def rewind: () -> self

  # <!--
  #   rdoc-file=enumerator.c
  #   - e.size          -> int, Float::INFINITY or nil
  # -->
  # Returns the size of the enumerator, or `nil` if it can't be calculated lazily.
  #
  #     (1..100).to_a.permutation(4).size # => 94109400
  #     loop.size # => Float::INFINITY
  #     (1..100).drop_while.size # => nil
  #
  def size: () -> (Integer | Float)?

  # <!--
  #   rdoc-file=enumerator.c
  #   - e.with_index(offset = 0) {|(*args), idx| ... }
  #   - e.with_index(offset = 0)
  # -->
  # Iterates the given block for each element with an index, which starts from
  # `offset`.  If no block is given, returns a new Enumerator that includes the
  # index, starting from `offset`
  #
  # `offset`
  # :   the starting index to use
  #
  def with_index: (?Integer offset) { (Elem arg0, Integer arg1) -> untyped } -> Return
                | (?Integer offset) -> ::Enumerator[[ Elem, Integer ], Return]

  # <!-- rdoc-file=enumerator.c -->
  # Iterates the given block for each element with an arbitrary object, `obj`, and
  # returns `obj`
  #
  # If no block is given, returns a new Enumerator.
  #
  # ### Example
  #
  #     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
  #
  def with_object: [U] (U obj) { (Elem, U obj) -> untyped } -> U
                 | [U] (U obj) -> ::Enumerator[[ Elem, U ], U]
end

# <!-- rdoc-file=enumerator.c -->
# Generator
#
class Enumerator::Generator[out Elem] < Object
  include Enumerable[Elem]

  def each: () { (Elem) -> void } -> void
end

# <!-- rdoc-file=enumerator.c -->
# Enumerator::Lazy is a special type of Enumerator, that allows constructing
# chains of operations without evaluating them immediately, and evaluating
# values on as-needed basis. In order to do so it redefines most of Enumerable
# methods so that they just construct another lazy enumerator.
#
# Enumerator::Lazy can be constructed from any Enumerable with the
# Enumerable#lazy method.
#
#     lazy = (1..Float::INFINITY).lazy.select(&:odd?).drop(10).take_while { |i| i < 30 }
#     # => #<Enumerator::Lazy: #<Enumerator::Lazy: #<Enumerator::Lazy: #<Enumerator::Lazy: 1..Infinity>:select>:drop(10)>:take_while>
#
# The real enumeration is performed when any non-redefined Enumerable method is
# called, like Enumerable#first or Enumerable#to_a (the latter is aliased as
# #force for more semantic code):
#
#     lazy.first(2)
#     #=> [21, 23]
#
#     lazy.force
#     #=> [21, 23, 25, 27, 29]
#
# Note that most Enumerable methods that could be called with or without a
# block, on Enumerator::Lazy will always require a block:
#
#     [1, 2, 3].map       #=> #<Enumerator: [1, 2, 3]:map>
#     [1, 2, 3].lazy.map  # ArgumentError: tried to call lazy map without a block
#
# This class allows idiomatic calculations on long or infinite sequences, as
# well as chaining of calculations without constructing intermediate arrays.
#
# Example for working with a slowly calculated sequence:
#
#     require 'open-uri'
#
#     # This will fetch all URLs before selecting
#     # necessary data
#     URLS.map { |u| JSON.parse(URI.open(u).read) }
#       .select { |data| data.key?('stats') }
#       .first(5)
#
#     # This will fetch URLs one-by-one, only till
#     # there is enough data to satisfy the condition
#     URLS.lazy.map { |u| JSON.parse(URI.open(u).read) }
#       .select { |data| data.key?('stats') }
#       .first(5)
#
# Ending a chain with ".eager" generates a non-lazy enumerator, which is
# suitable for returning or passing to another method that expects a normal
# enumerator.
#
#     def active_items
#       groups
#         .lazy
#         .flat_map(&:items)
#         .reject(&:disabled)
#         .eager
#     end
#
#     # This works lazily; if a checked item is found, it stops
#     # iteration and does not look into remaining groups.
#     first_checked = active_items.find(&:checked)
#
#     # This returns an array of items like a normal enumerator does.
#     all_checked = active_items.select(&:checked)
#
class Enumerator::Lazy[out Elem, out Return] < Enumerator[Elem, Return]
  # <!-- rdoc-file=enumerator.c -->
  # Expands `lazy` enumerator to an array. See Enumerable#to_a.
  #
  alias force to_a

  # <!--
  #   rdoc-file=enumerator.c
  #   - lazy.compact                  -> lazy_enumerator
  # -->
  # Like Enumerable#compact, but chains operation to be lazy-evaluated.
  #
  def compact: () -> Enumerator::Lazy[Elem, Return]
end

# <!-- rdoc-file=enumerator.c -->
# Yielder
#
class Enumerator::Yielder < Object
  def <<: (untyped arg0) -> void

  def yield: (*untyped arg0) -> void

  # <!--
  #   rdoc-file=enumerator.c
  #   - to_proc()
  # -->
  # Returns a Proc object that takes arguments and yields them.
  #
  # This method is implemented so that a Yielder object can be directly passed to
  # another method as a block argument.
  #
  #     enum = Enumerator.new { |y|
  #       Dir.glob("*.rb") { |file|
  #         File.open(file) { |f| f.each_line(&y) }
  #       }
  #     }
  #
  def to_proc: () -> Proc
end

# <!-- rdoc-file=enumerator.c -->
# Enumerator::Chain is a subclass of Enumerator, which represents a chain of
# enumerables that works as a single enumerator.
#
# This type of objects can be created by Enumerable#chain and Enumerator#+.
#
class Enumerator::Chain[out Elem] < Enumerator[Elem, void]
  include Enumerable[Elem]

  # <!--
  #   rdoc-file=enumerator.c
  #   - obj.each(*args) { |...| ... } -> obj
  #   - obj.each(*args) -> enumerator
  # -->
  # Iterates over the elements of the first enumerable by calling the "each"
  # method on it with the given arguments, then proceeds to the following
  # enumerables in sequence until all of the enumerables are exhausted.
  #
  # If no block is given, returns an enumerator.
  #
  def each: () { (Elem) -> void } -> void
end