Current File : //opt/plesk/ruby/3.1.3/lib64/ruby/gems/3.1.0/gems/rbs-2.7.0/core/enumerator.rbs
# <!-- 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
Mini Shell