diff options
Diffstat (limited to 'devdocs/python~3.12/c-api%2Fslice.html')
| -rw-r--r-- | devdocs/python~3.12/c-api%2Fslice.html | 37 |
1 files changed, 37 insertions, 0 deletions
diff --git a/devdocs/python~3.12/c-api%2Fslice.html b/devdocs/python~3.12/c-api%2Fslice.html new file mode 100644 index 00000000..a7a94407 --- /dev/null +++ b/devdocs/python~3.12/c-api%2Fslice.html @@ -0,0 +1,37 @@ + <span id="id1"></span><h1>Slice Objects</h1> <dl class="c var"> <dt class="sig sig-object c" id="c.PySlice_Type"> +<code>PyTypeObject PySlice_Type</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>.</em><p>The type object for slice objects. This is the same as <a class="reference internal" href="../library/functions#slice" title="slice"><code>slice</code></a> in the Python layer.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySlice_Check"> +<code>int PySlice_Check(PyObject *ob)</code> </dt> <dd> +<p>Return true if <em>ob</em> is a slice object; <em>ob</em> must not be <code>NULL</code>. This function always succeeds.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySlice_New"> +<code>PyObject *PySlice_New(PyObject *start, PyObject *stop, PyObject *step)</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 a new slice object with the given values. The <em>start</em>, <em>stop</em>, and <em>step</em> parameters are used as the values of the slice object attributes of the same names. Any of the values may be <code>NULL</code>, in which case the <code>None</code> will be used for the corresponding attribute. Return <code>NULL</code> if the new object could not be allocated.</p> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySlice_GetIndices"> +<code>int PySlice_GetIndices(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)</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>.</em><p>Retrieve the start, stop and step indices from the slice object <em>slice</em>, assuming a sequence of length <em>length</em>. Treats indices greater than <em>length</em> as errors.</p> <p>Returns <code>0</code> on success and <code>-1</code> on error with no exception set (unless one of the indices was not <code>None</code> and failed to be converted to an integer, in which case <code>-1</code> is returned with an exception set).</p> <p>You probably do not want to use this function.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>The parameter type for the <em>slice</em> parameter was <code>PySliceObject*</code> before.</p> </div> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySlice_GetIndicesEx"> +<code>int PySlice_GetIndicesEx(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)</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>.</em><p>Usable replacement for <a class="reference internal" href="#c.PySlice_GetIndices" title="PySlice_GetIndices"><code>PySlice_GetIndices()</code></a>. Retrieve the start, stop, and step indices from the slice object <em>slice</em> assuming a sequence of length <em>length</em>, and store the length of the slice in <em>slicelength</em>. Out of bounds indices are clipped in a manner consistent with the handling of normal slices.</p> <p>Returns <code>0</code> on success and <code>-1</code> on error with exception set.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>This function is considered not safe for resizable sequences. Its invocation should be replaced by a combination of <a class="reference internal" href="#c.PySlice_Unpack" title="PySlice_Unpack"><code>PySlice_Unpack()</code></a> and <a class="reference internal" href="#c.PySlice_AdjustIndices" title="PySlice_AdjustIndices"><code>PySlice_AdjustIndices()</code></a> where</p> <pre data-language="c">if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) { + // return error +} +</pre> <p>is replaced by</p> <pre data-language="c">if (PySlice_Unpack(slice, &start, &stop, &step) < 0) { + // return error +} +slicelength = PySlice_AdjustIndices(length, &start, &stop, step); +</pre> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>The parameter type for the <em>slice</em> parameter was <code>PySliceObject*</code> before.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6.1: </span>If <code>Py_LIMITED_API</code> is not set or set to the value between <code>0x03050400</code> and <code>0x03060000</code> (not including) or <code>0x03060100</code> or higher <code>PySlice_GetIndicesEx()</code> is implemented as a macro using <code>PySlice_Unpack()</code> and <code>PySlice_AdjustIndices()</code>. Arguments <em>start</em>, <em>stop</em> and <em>step</em> are evaluated more than once.</p> </div> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.6.1: </span>If <code>Py_LIMITED_API</code> is set to the value less than <code>0x03050400</code> or between <code>0x03060000</code> and <code>0x03060100</code> (not including) <code>PySlice_GetIndicesEx()</code> is a deprecated function.</p> </div> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySlice_Unpack"> +<code>int PySlice_Unpack(PyObject *slice, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)</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.7.</em><p>Extract the start, stop and step data members from a slice object as C integers. Silently reduce values larger than <code>PY_SSIZE_T_MAX</code> to <code>PY_SSIZE_T_MAX</code>, silently boost the start and stop values less than <code>PY_SSIZE_T_MIN</code> to <code>PY_SSIZE_T_MIN</code>, and silently boost the step values less than <code>-PY_SSIZE_T_MAX</code> to <code>-PY_SSIZE_T_MAX</code>.</p> <p>Return <code>-1</code> on error, <code>0</code> on success.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.6.1.</span></p> </div> </dd> +</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PySlice_AdjustIndices"> +<code>Py_ssize_t PySlice_AdjustIndices(Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step)</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.7.</em><p>Adjust start/end slice indices assuming a sequence of the specified length. Out of bounds indices are clipped in a manner consistent with the handling of normal slices.</p> <p>Return the length of the slice. Always successful. Doesn’t call Python code.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.6.1.</span></p> </div> </dd> +</dl> <section id="ellipsis-object"> <h2>Ellipsis Object</h2> <dl class="c var"> <dt class="sig sig-object c" id="c.Py_Ellipsis"> +<code>PyObject *Py_Ellipsis</code> </dt> <dd> +<p>The Python <code>Ellipsis</code> object. This object has no methods. Like <a class="reference internal" href="none#c.Py_None" title="Py_None"><code>Py_None</code></a>, it is an <a class="reference external" href="https://peps.python.org/pep-0683/">immortal</a>. singleton object.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span><a class="reference internal" href="#c.Py_Ellipsis" title="Py_Ellipsis"><code>Py_Ellipsis</code></a> is immortal.</p> </div> </dd> +</dl> </section> <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/slice.html" class="_attribution-link">https://docs.python.org/3.12/c-api/slice.html</a> + </p> +</div> |