diff options
Diffstat (limited to 'devdocs/python~3.12/c-api%2Fiter.html')
| -rw-r--r-- | devdocs/python~3.12/c-api%2Fiter.html | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/devdocs/python~3.12/c-api%2Fiter.html b/devdocs/python~3.12/c-api%2Fiter.html new file mode 100644 index 00000000..9029c472 --- /dev/null +++ b/devdocs/python~3.12/c-api%2Fiter.html @@ -0,0 +1,46 @@ + <span id="iterator"></span><h1>Iterator Protocol</h1> <p>There are two functions specifically for working with iterators.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyIter_Check"> +<code>int PyIter_Check(PyObject *o)</code> </dt> <dd> +<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.8.</em><p>Return non-zero if the object <em>o</em> can be safely passed to <a class="reference internal" href="#c.PyIter_Next" title="PyIter_Next"><code>PyIter_Next()</code></a>, and <code>0</code> otherwise. This function always succeeds.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyAIter_Check"> +<code>int PyAIter_Check(PyObject *o)</code> </dt> <dd> +<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Return non-zero if the object <em>o</em> provides the <code>AsyncIterator</code> protocol, and <code>0</code> otherwise. This function always succeeds.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyIter_Next"> +<code>PyObject *PyIter_Next(PyObject *o)</code> </dt> <dd> +<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the next value from the iterator <em>o</em>. The object must be an iterator according to <a class="reference internal" href="#c.PyIter_Check" title="PyIter_Check"><code>PyIter_Check()</code></a> (it is up to the caller to check this). If there are no remaining values, returns <code>NULL</code> with no exception set. If an error occurs while retrieving the item, returns <code>NULL</code> and passes along the exception.</p> </dd> +</dl> <p>To write a loop which iterates over an iterator, the C code should look something like this:</p> <pre data-language="c">PyObject *iterator = PyObject_GetIter(obj); +PyObject *item; + +if (iterator == NULL) { + /* propagate error */ +} + +while ((item = PyIter_Next(iterator))) { + /* do something with item */ + ... + /* release reference when done */ + Py_DECREF(item); +} + +Py_DECREF(iterator); + +if (PyErr_Occurred()) { + /* propagate error */ +} +else { + /* continue doing useful work */ +} +</pre> <dl class="c type"> <dt class="sig sig-object c" id="c.PySendResult"> +<code>type PySendResult</code> </dt> <dd> +<p>The enum value used to represent different results of <a class="reference internal" href="#c.PyIter_Send" title="PyIter_Send"><code>PyIter_Send()</code></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyIter_Send"> +<code>PySendResult PyIter_Send(PyObject *iter, PyObject *arg, PyObject **presult)</code> </dt> <dd> +<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Sends the <em>arg</em> value into the iterator <em>iter</em>. Returns:</p> <ul class="simple"> <li> +<code>PYGEN_RETURN</code> if iterator returns. Return value is returned via <em>presult</em>.</li> <li> +<code>PYGEN_NEXT</code> if iterator yields. Yielded value is returned via <em>presult</em>.</li> <li> +<code>PYGEN_ERROR</code> if iterator has raised and exception. <em>presult</em> is set to <code>NULL</code>.</li> </ul> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd> +</dl> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/c-api/iter.html" class="_attribution-link">https://docs.python.org/3.12/c-api/iter.html</a> + </p> +</div> |