Merge pull request numpy#19844 from Mukulikaa/c-api-additions

DOC: Added missing C-API functions

Author: charris

doc/source/reference/c-api/array.rst

@@ -584,25 +584,26 @@ From other objects
     did not have the _ARRAY_ macro namespace in them. That form
     of the constant names is deprecated in 1.7.
 
-.. c:macro:: NPY_ARRAY_NOTSWAPPED
+    .. c:macro:: NPY_ARRAY_NOTSWAPPED
 
-    Make sure the returned array has a data-type descriptor that is in
-    machine byte-order, over-riding any specification in the *dtype*
-    argument. Normally, the byte-order requirement is determined by
-    the *dtype* argument. If this flag is set and the dtype argument
-    does not indicate a machine byte-order descriptor (or is NULL and
-    the object is already an array with a data-type descriptor that is
-    not in machine byte- order), then a new data-type descriptor is
-    created and used with its byte-order field set to native.
+        Make sure the returned array has a data-type descriptor that is in
+        machine byte-order, over-riding any specification in the *dtype*
+        argument. Normally, the byte-order requirement is determined by
+        the *dtype* argument. If this flag is set and the dtype argument
+        does not indicate a machine byte-order descriptor (or is NULL and
+        the object is already an array with a data-type descriptor that is
+        not in machine byte- order), then a new data-type descriptor is
+        created and used with its byte-order field set to native.
 
-.. c:macro:: NPY_ARRAY_BEHAVED_NS
+    .. c:macro:: NPY_ARRAY_BEHAVED_NS
 
-    :c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEABLE` \| :c:data:`NPY_ARRAY_NOTSWAPPED`
+        :c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEABLE` \|
+        :c:data:`NPY_ARRAY_NOTSWAPPED`
 
-.. c:macro:: NPY_ARRAY_ELEMENTSTRIDES
+    .. c:macro:: NPY_ARRAY_ELEMENTSTRIDES
 
-    Make sure the returned array has strides that are multiples of the
-    element size.
+        Make sure the returned array has strides that are multiples of the
+        element size.
 
 .. c:function:: PyObject* PyArray_FromArray( \
         PyArrayObject* op, PyArray_Descr* newtype, int requirements)
@@ -723,6 +724,13 @@ From other objects
     broadcastable to the shape of ``dest``. The data areas of dest
     and src must not overlap.
 
+.. c:function:: int PyArray_CopyObject(PyArrayObject* dest, PyObject* src)
+
+    Assign an object ``src`` to a NumPy array ``dest`` according to
+    array-coercion rules. This is basically identical to
+    :c:func:`PyArray_FromAny`, but assigns directly to the output array.
+    Returns 0 on success and -1 on failures.
+
 .. c:function:: int PyArray_MoveInto(PyArrayObject* dest, PyArrayObject* src)
 
     Move data from the source array, ``src``, into the destination
@@ -2707,6 +2715,45 @@ cost of a slight overhead.
     neighborhood. Calling this function after every point of the
     neighborhood has been visited is undefined.
 
+Array mapping
+-------------
+
+Array mapping is the machinery behind advanced indexing.
+
+.. c:function:: PyObject* PyArray_MapIterArray(PyArrayObject *a, \
+                 PyObject *index)
+
+    Use advanced indexing to iterate an array.
+
+.. c:function:: void PyArray_MapIterSwapAxes(PyArrayMapIterObject *mit, \
+                PyArrayObject **ret, int getmap)
+
+    Swap the axes to or from their inserted form. ``MapIter`` always puts the
+    advanced (array) indices first in the iteration. But if they are
+    consecutive, it will insert/transpose them back before returning.
+    This is stored as ``mit->consec != 0`` (the place where they are inserted).
+    For assignments, the opposite happens: the values to be assigned are
+    transposed (``getmap=1`` instead of ``getmap=0``). ``getmap=0`` and
+    ``getmap=1`` undo the other operation.
+
+.. c:function:: void PyArray_MapIterNext(PyArrayMapIterObject *mit)
+
+    This function needs to update the state of the map iterator
+    and point ``mit->dataptr`` to the memory-location of the next object.
+
+    Note that this function never handles an extra operand but provides
+    compatibility for an old (exposed) API.
+
+.. c:function:: PyObject* PyArray_MapIterArrayCopyIfOverlap(PyArrayObject *a, \
+                PyObject *index, int copy_if_overlap, PyArrayObject *extra_op)
+
+    Similar to :c:func:`PyArray_MapIterArray` but with an additional
+    ``copy_if_overlap`` argument. If ``copy_if_overlap != 0``, checks if ``a``
+    has memory overlap with any of the arrays in ``index`` and with
+    ``extra_op``, and make copies as appropriate to avoid problems if the
+    input is modified during the iteration. ``iter->array`` may contain a
+    copied array (UPDATEIFCOPY/WRITEBACKIFCOPY set).
+
 Array Scalars
 -------------