feat: add support for integer array indexing

spec/draft/API_specification/indexing.rst

@@ -7,6 +7,9 @@ Indexing
 
 A conforming implementation of the array API standard must adhere to the following conventions.
 
+
+.. _indexing-single-axis:
+
 Single-axis Indexing
 --------------------
 
@@ -121,6 +124,9 @@ The behavior outside of these bounds is unspecified.
 .. note::
    *Rationale: this is consistent with bounds checking for integer indexing; the behavior of out-of-bounds indices is left unspecified. Implementations may choose to clip (consistent with Python* ``list`` *slicing semantics), raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations.*
 
+
+.. _indexing-multi-axis:
+
 Multi-axis Indexing
 -------------------
 
@@ -173,6 +179,43 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult
 
     *Rationale: this is consistent with bounds-checking for single-axis indexing. An implementation may choose to set the axis (dimension) size of the result array to* ``0`` *, raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations.*
 
+Integer Array Indexing
+----------------------
+
+An array must support indexing a one-dimensional array by a one-dimensional integer array according to the following rules. Let ``A`` be a one-dimensional array with shape ``S1 = (n,)``, and let ``J`` be a one-dimensional integer array with shape ``S2 = (k,)``.
+
+- Each integer index element in ``J`` must satisfy the rules stated above for indexing a single-axis (see :ref:`indexing-single-axis`). Namely,
+
+  - Nonnegative indices must start at ``0`` (i.e., zero-based indexing).
+  - **Valid** nonnegative indices must reside on the half-open interval ``[0, n)``.
+  - Negative indices must count backward from the last index, starting from ``-1`` (i.e., negative-one-based indexing, where ``-1`` refers to the last index).
+  - **Valid** negative indices must reside on the closed interval ``[-n, -1]``.
+  - A negative index ``j`` is related to a zero-based nonnegative index ``i`` via ``i = n+j``.
+
+  .. note::
+    This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified.
+
+- Providing duplicate integer index elements in ``J`` must result in the duplication of the corresponding elements of ``A`` in the resulting array.
+
+- The result of providing a valid integer index for each element in ``J`` must be an array having shape ``(k,)``.
+
+An array must support indexing an array having more than one dimension by an indexing tuple which includes only integers and one-dimensional integer arrays according to the following rules. Let ``A`` be an ``N``-dimensional array with shape ``S1 = (s1, s2, ..., sN)`` and ``T`` be a tuple ``(t1, t2, ..., tN)`` having length ``N`` and containing only valid integer and one-dimensional integer array indices.
+
+- Providing an integer tuple element ``tk`` having value ``k`` must be equivalent to providing a zero-dimensional integer array ``K`` containing ``k``.
+
+- If ``T`` consists of only integers and zero-dimensional integer arrays, the result must be equivalent to indexing multiple axes using integer indices (see :ref:`indexing-multi-axis`).
+
+- When ``T`` contains a one-dimensional integer array ``J`` having shape ``S2 = (m,)``, where ``m`` is greater than or equal to the number of elements in any other one-dimensional integer array in ``T``, each element of ``T`` must be broadcast to the same shape as ``J``.
+
+- An ``IndexError`` exception must be raised if any element of ``T`` is not broadcast-compatible with ``J`` (see :ref:`broadcasting`).
+
+- After broadcasting, ``T`` must be equivalent to a tuple ``U = (u1, u2, ..., uN)`` containing only one-dimensional integer arrays having shape ``S2``.
+
+- Let ``v_i`` be the tuple formed by the integer indices ``u1[i], u2[i], ..., uN[i]``. When applying the indexing tuple ``U`` to ``A``, the resulting array must be a one-dimensional array having shape ``(m,)`` and containing each element ``A[v_i]`` for ``i`` on the half-open interval ``[0, m)``.
+
+.. note::
+   This specification does not currently address indexing tuples which combine slices and integer arrays. Behavior for such indexing tuples is left unspecified and thus implementation-defined. This may be revisited in a future revision of this standard.
+
 Boolean Array Indexing
 ----------------------