bpo-27867: Add a porting guide for PySlice_GetIndicesEx(). (#1973)
diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index f8395ec..8ad9a29 100644
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -53,6 +53,22 @@
Returns ``0`` on success and ``-1`` on error with exception set.
+ .. note::
+ This function is considered not safe for resizable sequences.
+ Its invocation should be replaced by a combination of
+ :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices` where ::
+
+ if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) {
+ // return error
+ }
+
+ is replaced by ::
+
+ if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {
+ // return error
+ }
+ slicelength = PySlice_AdjustIndices(length, &start, &stop, step);
+
.. versionchanged:: 3.2
The parameter type for the *slice* parameter was ``PySliceObject*``
before.
@@ -61,7 +77,7 @@
If ``Py_LIMITED_API`` is not set or set to the value between ``0x03050400``
and ``0x03060000`` (not including) or ``0x03060100`` or higher
:c:func:`!PySlice_GetIndicesEx` is implemented as a macro using
- :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`.
+ :c:func:`!PySlice_Unpack` and :c:func:`!PySlice_AdjustIndices`.
Arguments *start*, *stop* and *step* are evaluated more than once.
.. deprecated:: 3.6.1