| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _iterator-objects: |
| 4 |
|
| 5 |
Iterator Objects |
| 6 |
---------------- |
| 7 |
|
| 8 |
Python provides two general-purpose iterator objects. The first, a sequence |
| 9 |
iterator, works with an arbitrary sequence supporting the :meth:`~object.__getitem__` |
| 10 |
method. The second works with a callable object and a sentinel value, calling |
| 11 |
the callable for each item in the sequence, and ending the iteration when the |
| 12 |
sentinel value is returned. |
| 13 |
|
| 14 |
|
| 15 |
.. c:var:: PyTypeObject PySeqIter_Type |
| 16 |
|
| 17 |
Type object for iterator objects returned by :c:func:`PySeqIter_New` and the |
| 18 |
one-argument form of the :func:`iter` built-in function for built-in sequence |
| 19 |
types. |
| 20 |
|
| 21 |
|
| 22 |
.. c:function:: int PySeqIter_Check(PyObject *op) |
| 23 |
|
| 24 |
Return true if the type of *op* is :c:data:`PySeqIter_Type`. This function |
| 25 |
always succeeds. |
| 26 |
|
| 27 |
|
| 28 |
.. c:function:: PyObject* PySeqIter_New(PyObject *seq) |
| 29 |
|
| 30 |
Return an iterator that works with a general sequence object, *seq*. The |
| 31 |
iteration ends when the sequence raises :exc:`IndexError` for the subscripting |
| 32 |
operation. |
| 33 |
|
| 34 |
|
| 35 |
.. c:var:: PyTypeObject PyCallIter_Type |
| 36 |
|
| 37 |
Type object for iterator objects returned by :c:func:`PyCallIter_New` and the |
| 38 |
two-argument form of the :func:`iter` built-in function. |
| 39 |
|
| 40 |
|
| 41 |
.. c:function:: int PyCallIter_Check(PyObject *op) |
| 42 |
|
| 43 |
Return true if the type of *op* is :c:data:`PyCallIter_Type`. This |
| 44 |
function always succeeds. |
| 45 |
|
| 46 |
|
| 47 |
.. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel) |
| 48 |
|
| 49 |
Return a new iterator. The first parameter, *callable*, can be any Python |
| 50 |
callable object that can be called with no parameters; each call to it should |
| 51 |
return the next item in the iteration. When *callable* returns a value equal to |
| 52 |
*sentinel*, the iteration will be terminated. |
| 53 |
|
| 54 |
|
| 55 |
Range Objects |
| 56 |
^^^^^^^^^^^^^ |
| 57 |
|
| 58 |
.. c:var:: PyTypeObject PyRange_Type |
| 59 |
|
| 60 |
The type object for :class:`range` objects. |
| 61 |
|
| 62 |
|
| 63 |
.. c:function:: int PyRange_Check(PyObject *o) |
| 64 |
|
| 65 |
Return true if the object *o* is an instance of a :class:`range` object. |
| 66 |
This function always succeeds. |
| 67 |
|
| 68 |
|
| 69 |
Builtin Iterator Types |
| 70 |
^^^^^^^^^^^^^^^^^^^^^^ |
| 71 |
|
| 72 |
These are built-in iteration types that are included in Python's C API, but |
| 73 |
provide no additional functions. They are here for completeness. |
| 74 |
|
| 75 |
|
| 76 |
.. list-table:: |
| 77 |
:widths: auto |
| 78 |
:header-rows: 1 |
| 79 |
|
| 80 |
* * C type |
| 81 |
* Python type |
| 82 |
* * .. c:var:: PyTypeObject PyEnum_Type |
| 83 |
* :py:class:`enumerate` |
| 84 |
* * .. c:var:: PyTypeObject PyFilter_Type |
| 85 |
* :py:class:`filter` |
| 86 |
* * .. c:var:: PyTypeObject PyMap_Type |
| 87 |
* :py:class:`map` |
| 88 |
* * .. c:var:: PyTypeObject PyReversed_Type |
| 89 |
* :py:class:`reversed` |
| 90 |
* * .. c:var:: PyTypeObject PyZip_Type |
| 91 |
* :py:class:`zip` |
| 92 |
|
| 93 |
|
| 94 |
Other Iterator Objects |
| 95 |
^^^^^^^^^^^^^^^^^^^^^^ |
| 96 |
|
| 97 |
.. c:var:: PyTypeObject PyByteArrayIter_Type |
| 98 |
.. c:var:: PyTypeObject PyBytesIter_Type |
| 99 |
.. c:var:: PyTypeObject PyListIter_Type |
| 100 |
.. c:var:: PyTypeObject PyListRevIter_Type |
| 101 |
.. c:var:: PyTypeObject PySetIter_Type |
| 102 |
.. c:var:: PyTypeObject PyTupleIter_Type |
| 103 |
.. c:var:: PyTypeObject PyRangeIter_Type |
| 104 |
.. c:var:: PyTypeObject PyLongRangeIter_Type |
| 105 |
.. c:var:: PyTypeObject PyDictIterKey_Type |
| 106 |
.. c:var:: PyTypeObject PyDictRevIterKey_Type |
| 107 |
.. c:var:: PyTypeObject PyDictIterValue_Type |
| 108 |
.. c:var:: PyTypeObject PyDictRevIterValue_Type |
| 109 |
.. c:var:: PyTypeObject PyDictIterItem_Type |
| 110 |
.. c:var:: PyTypeObject PyDictRevIterItem_Type |
| 111 |
.. c:var:: PyTypeObject PyODictIter_Type |
| 112 |
|
| 113 |
Type objects for iterators of various built-in objects. |
| 114 |
|
| 115 |
Do not create instances of these directly; prefer calling |
| 116 |
:c:func:`PyObject_GetIter` instead. |
| 117 |
|
| 118 |
Note that there is no guarantee that a given built-in type uses a given iterator |
| 119 |
type. For example, iterating over :class:`range` will use one of two iterator |
| 120 |
types depending on the size of the range. Other types may start using a |
| 121 |
similar scheme in the future, without warning. |