| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _iterator: |
| 4 |
|
| 5 |
Iterator Protocol |
| 6 |
================= |
| 7 |
|
| 8 |
There are two functions specifically for working with iterators. |
| 9 |
|
| 10 |
.. c:function:: int PyIter_Check(PyObject *o) |
| 11 |
|
| 12 |
Return non-zero if the object *o* can be safely passed to |
| 13 |
:c:func:`PyIter_NextItem` and ``0`` otherwise. |
| 14 |
This function always succeeds. |
| 15 |
|
| 16 |
.. c:function:: int PyAIter_Check(PyObject *o) |
| 17 |
|
| 18 |
Return non-zero if the object *o* provides the :class:`AsyncIterator` |
| 19 |
protocol, and ``0`` otherwise. This function always succeeds. |
| 20 |
|
| 21 |
.. versionadded:: 3.10 |
| 22 |
|
| 23 |
.. c:function:: int PyIter_NextItem(PyObject *iter, PyObject **item) |
| 24 |
|
| 25 |
Return ``1`` and set *item* to a :term:`strong reference` of the |
| 26 |
next value of the iterator *iter* on success. |
| 27 |
Return ``0`` and set *item* to ``NULL`` if there are no remaining values. |
| 28 |
Return ``-1``, set *item* to ``NULL`` and set an exception on error. |
| 29 |
|
| 30 |
.. versionadded:: 3.14 |
| 31 |
|
| 32 |
.. c:function:: PyObject* PyIter_Next(PyObject *o) |
| 33 |
|
| 34 |
This is an older version of :c:func:`!PyIter_NextItem`, |
| 35 |
which is retained for backwards compatibility. |
| 36 |
Prefer :c:func:`PyIter_NextItem`. |
| 37 |
|
| 38 |
Return the next value from the iterator *o*. The object must be an iterator |
| 39 |
according to :c:func:`PyIter_Check` (it is up to the caller to check this). |
| 40 |
If there are no remaining values, returns ``NULL`` with no exception set. |
| 41 |
If an error occurs while retrieving the item, returns ``NULL`` and passes |
| 42 |
along the exception. |
| 43 |
|
| 44 |
.. c:type:: PySendResult |
| 45 |
|
| 46 |
The enum value used to represent different results of :c:func:`PyIter_Send`. |
| 47 |
|
| 48 |
.. versionadded:: 3.10 |
| 49 |
|
| 50 |
|
| 51 |
.. c:function:: PySendResult PyIter_Send(PyObject *iter, PyObject *arg, PyObject **presult) |
| 52 |
|
| 53 |
Sends the *arg* value into the iterator *iter*. Returns: |
| 54 |
|
| 55 |
- ``PYGEN_RETURN`` if iterator returns. Return value is returned via *presult*. |
| 56 |
- ``PYGEN_NEXT`` if iterator yields. Yielded value is returned via *presult*. |
| 57 |
- ``PYGEN_ERROR`` if iterator has raised and exception. *presult* is set to ``NULL``. |
| 58 |
|
| 59 |
.. versionadded:: 3.10 |