عرض مصدر Ruby/Enumerator

{{DISPLAYTITLE:الصنف <code>Enumerator</code> في روبي}}
الصنف <code>Enumerator</code> هو صنفٌ يسمح بتنفيذ عملية التكرار الداخلي والخارجي على الكائنات. يمكن إنشاء كائنات من هذا الصنف باستعمال إحدى التوابع التالية: <code>Kernel.to_enum</code>، أو <code>Kernel.enum_for</code>، أو <code>[[Ruby/Enumerator/new|new]]</code>.
__TOC__
أغلب التوابع في هذا الصنف تملك شكلين هما: الشكل الكتلي (block form) الذي تقيَّم فيه المحتويات لكل عنصر في المجموعة التعدادية، والشكل الغير كتلي (non-block form) الذي يعيد كائنًا جديدًا من النوع <code>Enumerator</code> يغلِّف التكرار.<syntaxhighlight lang="ruby">
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
</syntaxhighlight>هذا يسمح لك بربط الكائنات <code>Enumerator</code> مع بعضها بعضًا. على سبيل المثال، يمكنك تحويل كل عنصر من عناصر قائمة إلى سلسلة نصية تحوي الفهرس والعنصر بالشكل التالي:<syntaxhighlight lang="ruby">
puts %w[foo bar baz].map.with_index { |w, i| "#{i}:#{w}" }
# => ["0:foo", "1:bar", "2:baz"]
</syntaxhighlight>يمكن أيضًا استعمال الصنف <code>Enumerator</code> كمكرِّر داخلي. على سبيل المثال، يعيد التابع <code>next</code> القيمة التالية للمكرِّر أو يطلق الاستثناء <code>[[Ruby/StopIteration|StopIteration]]</code> إن وصل الكائن <code>Enumerator</code> إلى النهاية.<syntaxhighlight lang="ruby">
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
</syntaxhighlight>يمكنك استعمال هذا المثال لتنفيذ تكرار داخلي بالشكل التالي:<syntaxhighlight lang="ruby">
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
</syntaxhighlight>

== توابع الصنف العامة ==

=== <code>[[Ruby/Enumerator/new|new]]</code> ===
ينشئ كائنًا جديدًا من النوع <code>[[Ruby/Enumerator|Enumerator]]</code> يمكن استعماله ككائن [[Ruby/Enumerable|قابل للتعداد]] (Enumerable).

== توابع النسخة العامة ==
===<code>[[Ruby/Enumerator/each|each]]</code>===
يتكرر عبر الكتلة المعطاة وفقًا للكائن [[Ruby/Enumerator|المُعدِّد]] الذي استدعي معه والطريقة التي أُنشِئ بها.

===<code>[[Ruby/Enumerator/each_with_index|each_with_index]]</code>===
يشبه التابع <code>[[Ruby/Enumerator/with index|with_index]]</code> باستثناء أنه لا يوجد إزاحة بادئة لبدء العملية عند قيمة محدَّدة.

===<code>[[Ruby/Enumerator/each_with_object|each_with_object]]</code>===
يكرر الكتلة المعطاة على كل عنصر من عناصر الكائن الذي استدعي معه مع كائن آخر اعتباطي (الكائن المُمرَّر إليه).

===<code>[[Ruby/Enumerator/feed|feed]]</code>===
يضبط القيمة المراد إعادتها عبر الاستدعاء <code>yield</code> التالي داخل <code>e</code>.

===<code>[[Ruby/Enumerator/inspect|inspect]]</code>===
ينشئ نسخةً قابلةً للطباعة من e.

===<code>[[Ruby/Enumerator/next|next]]</code>===
يعيد الكائن التالي في [[Ruby/Enumerator|المُعدِّد]] الذي استدعي معه، ويحرك موضع المؤشر الداخلي للأمام خطوة واحدة.

===<code>[[Ruby/Enumerator/next_values|next_values]]</code>===
يعيد مصفوفة تحوي الكائن التالي في [[Ruby/Enumerator|المُعدِّد]] الذي استدعي معه، ويحرك موضع المؤشر الداخلي للأمام خطوةً واحدةً.

===<code>[[Ruby/Enumerator/peek|peek]]</code>===
يعيد الكائن التالي في [[Ruby/Enumerator|المُعدِّد]] الذي استدعي معه ولكن لا يحرِّك موضع المؤشر الداخلي للأمام. 

===<code>[[Ruby/Enumerator/peek_values|peek_values]]</code>===
يعيد مصفوفة تحوي القيمة التالية في [[Ruby/Enumerator|المُعدِّد]] الذي استدعي معه بشكل مشابه للتابع <code>[[Ruby/Enumerator/next values|next_values]]</code> ولكن لا يحرِّك موضع المؤشر الداخلي للأمام.

===<code>[[Ruby/Enumerator/rewind|rewind]]</code>===
يعيد موضع مؤشر السلسلة التعدادية (enumeration sequence) إلى البداية.

===<code>[[Ruby/Enumerator/size|size]]</code>===
يعيد حجم [[Ruby/Enumerator|المُعدِّد]] الذي استدعي معه، أو يعيد القيمة <code>nil</code> إن لم يكن بالإمكان حساب الحجم بالنمط الكسول (lazily).

===<code>[[Ruby/Enumerator/with_index|with_index]]</code>===
يكرر الكتلة المعطاة على كل عنصر من عناصر [[Ruby/Enumerator|المُعدِّد]] الذي استدعي معه مع فهارسها والتي تبدأ عند موضع محدَّد.

===<code>[[Ruby/Enumerator/with_object|with_object]]</code>===
يكرر الكتلة المعطاة على كل عنصر من عناصر [[Ruby/Enumerator|المُعدِّد]] الذي استدعي معه مع كائن اعتباطي (الكائن المُمرَّر إليه) ثم يعيد هذا الكائن.

== مصادر ==
* [http://ruby-doc.org/core-2.5.1/Enumerator.html صفحة الصنف Enumerator في توثيق روبي الرسمي.]

[[تصنيف:Ruby]]
[[تصنيف:Ruby Class]]
[[تصنيف:Ruby Enumerator]]