Python/iter

تعيد الدّالة iter()‎ مُكرّرًا حسب المُعاملات المُعطاة.

البنية العامة

iter(object[, sentinel])

المعاملات

object

إن لم يكن المُعامل الثّاني sentinel حاضرًا، فلا بدّ لهذا المُعامل أن يكون كائنًا يدعم بروتوكول التّكرار (أي أنّ صنفه يُعرّف التّابع الخاصّ ‎_‎_‎iter‎_‎_‎(‎)‎)، أو يجب أن يدعم بروتوكول التّسلسلات (sequence protocol) الذي يُعرّف صنفه التّابع الخاصّ ‎_‎_‎getitem‎_‎_‎(‎)‎ مع مُعاملات تكون أعدادًا صحيحةً وتبدأ من الصّفر. وإن لم يدعم الكائن أيًّا من هذين البروتوكولين، فسيُطلق الاستثناء TypeError.

sentinel

مُعامل اختيّاريّ.

إن مُرّرت قيمة لهذا المُعامل، فلا بدّ على المُعامل object أن يكون كائنًا قابلًا للاستدعاء (كدالّة أو تابع مثلًا).

يستدعي المُكرّر المُنشأ في هذه الحالة الكائن object دون مُعاملات لكلّ استدعاءٍ لتابعه الخاصّ ‎_‎_‎next‎_‎_‎(‎)‎ وإن كانت القيمة المُعادة مُساويّة لقيمة المُعامل sentinel فسيُطلَق استثناء StopIteration الذي يوقف التّكرار، وفي غير ذلك، ستُعاد القيمة.

القيمة المعادة

مُكرّر يعمل حسب نوع المُعاملات المُعطاة.

أمثلة

المثال التّالي يوضّح كيفيّة عمل هذه الدّالة عند تمرير قيم قابلة للتكرار إلى المُعامل object:

>>> abcd = iter('abcd') # تحويل سلسلة نصيّة إلى مُكرّر
>>> for i in abcd:
...     print(i)
... 
a
b
c
d
>>> abcd # كائن مكرّر
<str_iterator object at 0x7f992a45c080>

>>> chars = ['a', 'b', 'c'] # قائمة بايثون عاديّة
>>> next(chars) # لا يُمكننا استخدام الدّالة
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'list' object is not an iterator
>>> chars = iter(chars) # تحويل القائمة إلى مكرّر
>>> next(chars)
'a'
>>> next(chars)
'b'
>>> next(chars)
'c'
>>> next(chars) # انتهت قيم المُكرّر لذا لا يُمكننا الاستمرار
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
StopIteration

المثال التّالي يُوضّح كيفيّة الاستفادة من المُعامل sentinel، وذلك عبر قراءة أسطرٍ من ملفّ إلى أن نصل إلى سطرٍ فارغ:

with open('mydata.txt') as fp:
    for line in iter(fp.readline, ''):
        process_line(line)

انظر أيضًا

• المكرِّرات Iterators في بايثون.

مصادر

• قسم الدالة iter في صفحة Functions في توثيق Python الرسمي.