refactor: remove specialized APIs

spec/draft/API_specification/searching_functions.rst

@@ -24,6 +24,4 @@ Objects in API
    argmin
    nonzero
    top_k
-   top_k_indices
-   top_k_values
    where

src/array_api_stubs/_draft/searching_functions.py

@@ -3,8 +3,6 @@
     "argmin",
     "nonzero",
     "top_k",
-    "top_k_values",
-    "top_k_indices",
     "where",
 ]
 
@@ -139,88 +137,6 @@ def top_k(
     """
 
 
-def top_k_indices(
-    x: array,
-    k: int,
-    /,
-    *,
-    axis: Optional[int] = None,
-    mode: Literal["largest", "smallest"] = "largest",
-) -> array:
-    """
-    Returns the indices of the ``k`` largest (or smallest) elements of an input array ``x`` along a specified dimension.
-
-    Parameters
-    ----------
-    x: array
-        input array. Should have a real-valued data type.
-    k: int
-        number of elements to find. Must be a positive integer value.
-    axis: Optional[int]
-        axis along which to search. If ``None``, the function must search the flattened array. Default: ``None``.
-    mode: Literal['largest', 'smallest']
-        search mode. Must be one of the following modes:
-
-        -  ``'largest'``: return the indices of the ``k`` largest elements.
-        -  ``'smallest'``: return the indices of the ``k`` smallest elements.
-
-        Default: ``'largest'``.
-
-    Returns
-    -------
-    out: array
-        an array containing indices corresponding to the ``k`` largest (or smallest) elements of ``x``. The array must have the default array index data type.  If ``axis`` is ``None``, the array must be a one-dimensional array having shape ``(k,)`` and contain the indices of a flattened ``x``; otherwise, if ``axis`` is an integer value, the array must have the same rank (number of dimensions) and shape as ``x``, except for the axis specified by ``axis`` which must have size ``k``.
-
-    Notes
-    -----
-
-    -   If ``k`` exceeds the number of elements in ``x`` or along the axis specified by ``axis``, behavior is left unspecified and thus implementation-dependent. Conforming implementations may choose, e.g., to raise an exception or return all indices.
-    -   The order of the returned indices is left unspecified and thus implementation-dependent. Conforming implementations may return indices corresponding to sorted or unsorted values.
-    -   Conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
-    """
-
-
-def top_k_values(
-    x: array,
-    k: int,
-    /,
-    *,
-    axis: Optional[int] = None,
-    mode: Literal["largest", "smallest"] = "largest",
-) -> array:
-    """
-    Returns the ``k`` largest (or smallest) elements of an input array ``x`` along a specified dimension.
-
-    Parameters
-    ----------
-    x: array
-        input array. Should have a real-valued data type.
-    k: int
-        number of elements to find. Must be a positive integer value.
-    axis: Optional[int]
-        axis along which to search. If ``None``, the function must search the flattened array. Default: ``None``.
-    mode: Literal['largest', 'smallest']
-        search mode. Must be one of the following modes:
-
-        -  ``'largest'``: return the indices of the ``k`` largest elements.
-        -  ``'smallest'``: return the indices of the ``k`` smallest elements.
-
-        Default: ``'largest'``.
-
-    Returns
-    -------
-    out: array
-        an array containing the ``k`` largest (or smallest) elements of ``x``. The array must have the same data type as ``x``.  If ``axis`` is ``None``, the array must be a one-dimensional array having shape ``(k,)``; otherwise, if ``axis`` is an integer value, the array must have the same rank (number of dimensions) and shape as ``x``, except for the axis specified by ``axis`` which must have size ``k``.
-
-    Notes
-    -----
-
-    -   If ``k`` exceeds the number of elements in ``x`` or along the axis specified by ``axis``, behavior is left unspecified and thus implementation-dependent. Conforming implementations may choose, e.g., to raise an exception or return all indices.
-    -   The order of the returned values is left unspecified and thus implementation-dependent. Conforming implementations may return sorted or unsorted values.
-    -   Conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`).
-    """
-
-
 def where(condition: array, x1: array, x2: array, /) -> array:
     """
     Returns elements chosen from ``x1`` or ``x2`` depending on ``condition``.