Add specifications for functions for searching arrays (#23)

spec/API_specification/index.rst

@@ -15,4 +15,5 @@ API specification
    out_keyword
    elementwise_functions
    statistical_functions
-   linear_algebra_functions
+   searching_functions
+   linear_algebra_functions

spec/API_specification/searching_functions.md

@@ -0,0 +1,110 @@
+# Searching Functions
+
+> Array API specification for functions for searching arrays.
+
+A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
+
+-   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
+-   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
+-   The `out` keyword argument must follow the conventions defined in :ref:`out-keyword`.
+-   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
+-   Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
+-   Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`.
+
+<!-- NOTE: please keep the functions in alphabetical order -->
+
+### <a name="argmax" href="#argmax">#</a> argmax(x, /, *, axis=None, keepdims=False, out=None)
+
+Returns the indices of the maximum values along a specified axis. When the maximum value occurs multiple times, only the indices corresponding to the first occurrence are returned.
+
+#### Parameters
+
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **axis**: _int_
+
+    -   axis along which to search. If `None`, the function must return the index of the maximum value of the flattened array. Default: `None`.
+
+-   **keepdims**: _bool_
+
+    -   If `True`, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if `False`, the reduced axes (dimensions) must not be included in the result. Default: `False`.
+
+-   **out**: _Optional\[ &lt;array&gt; ]_
+
+    -   output array. If provided, the output array must have the expected output shape. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each computation. Default: `None`.
+
+#### Returns
+
+-   **out**: _&lt;array&gt;_
+
+    -   if `axis` is `None`, a zero-dimensional array containing the index of the first occurrence of the maximum value; otherwise, a non-zero-dimensional array containing the indices of the maximum values.
+
+### <a name="argmin" href="#argmin">#</a> argmin(x, /, *, axis=None, keepdims=False, out=None)
+
+Returns the indices of the minimum values along a specified axis. When the minimum value occurs multiple times, only the indices corresponding to the first occurrence are returned.
+
+#### Parameters
+
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **axis**: _int_
+
+    -   axis along which to search. If `None`, the function must return the index of the minimum value of the flattened array. Default: `None`.
+
+-   **keepdims**: _bool_
+
+    -   If `True`, the reduced axes (dimensions) must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if `False`, the reduced axes (dimensions) must not be included in the result. Default: `False`.
+
+-   **out**: _Optional\[ &lt;array&gt; ]_
+
+    -   output array. If provided, the output array must have the expected output shape. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each computation. Default: `None`.
+
+#### Returns
+
+-   **out**: _&lt;array&gt;_
+
+    -   if `axis` is `None`, a zero-dimensional array containing the index of the first occurrence of the minimum value; otherwise, a non-zero-dimensional array containing the indices of the minimum values.
+
+### <a name="nonzero" href="#nonzero">#</a> nonzero(x, /)
+
+Returns the indices of the array elements which are non-zero.
+
+#### Parameters
+
+-   **x**: _&lt;array&gt;_
+
+    -   input array. Must have a positive rank. If `x` is zero-dimensional, the function must raise an exception.
+
+#### Returns
+
+-   **out**: _Tuple\[ &lt;array&gt;, ... ]_
+
+    -   a tuple of `k` arrays, one for each dimension of `x` and each of size `n` (where `n` is the total number of non-zero elements), containing the indices of the non-zero elements in that dimension. The indices must be returned in row-major, C-style order. 
+
+### <a name="where" href="#where">#</a> where(condition, x1, x2, /)
+
+Returns elements chosen from `x1` or `x2` depending on `condition`.
+
+#### Parameters
+
+-   **condition**: _&lt;array&lt;bool&gt;&gt;_
+
+    -   when `True`, yield `x1_i`; otherwise, yield `x2_i`. Must be compatible with `x1` and `x2` (see :ref:`broadcasting`). 
+
+-   **x1**: _&lt;array&gt;_
+
+    -   first input array. Must be compatible with `condition` and `x2` (see :ref:`broadcasting`). 
+
+-   **x2**: _&lt;array&gt;_
+
+    -   second input array. Must be compatible with `condition` and `x1` (see :ref:`broadcasting`). 
+
+#### Returns
+
+-   **out**: _&lt;array&gt;_
+
+    -   an array with elements from `x1` where `condition` is `True`, and elements from `x2` elsewhere.