Debian Codegraph @

Doc/c-api/iterator.rst

raw
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.