Add clip to the specification

spec/draft/API_specification/elementwise_functions.rst

@@ -33,6 +33,7 @@ Objects in API
    bitwise_right_shift
    bitwise_xor
    ceil
+   clip
    conj
    copysign
    cos

src/array_api_stubs/_draft/elementwise_functions.py

@@ -15,6 +15,7 @@
     "bitwise_right_shift",
     "bitwise_xor",
     "ceil",
+    "clip",
     "conj",
     "copysign",
     "cos",
@@ -62,7 +63,7 @@
 ]
 
 
-from ._types import array
+from ._types import Optional, Union, array
 
 
 def abs(x: array, /) -> array:
@@ -772,6 +773,38 @@ def ceil(x: array, /) -> array:
     """
 
 
+def clip(
+    x: array,
+    /,
+    min: Optional[Union[int, float, array]] = None,
+    max: Optional[Union[int, float, array]] = None,
+) -> array:
+    r"""
+    Clamps each element ``x_i`` of the input array ``x`` to the range ``[min, max]``.
+
+    Parameters
+    ----------
+    x: array
+      input array. Should have a real-valued data type.
+    min: Optional[Union[int, float, array]]
+      lower-bound of the range to which to clamp. If ``None``, no lower bound must be applied. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``.
+    max: Optional[Union[int, float, array]]
+      upper-bound of the range to which to clamp. If ``None``, no upper bound must be applied. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``.
+
+    Returns
+    -------
+    out: array
+      an array containing element-wise results. The returned array must have the same data type as ``x``.
+
+    Notes
+    -----
+
+    - If both ``min`` and ``max`` are ``None``, the elements of the returned array must equal the respective elements in ``x``.
+    - If a broadcasted element in ``min`` is greater than a corresponding broadcasted element in ``max``, behavior is unspecified and thus implementation-dependent.
+    - If ``x`` and either ``min`` or ``max`` have different data type kinds (e.g., integer versus floating-point), behavior is unspecified and thus implementation-dependent.
+    """
+
+
 def conj(x: array, /) -> array:
     """
     Returns the complex conjugate for each element ``x_i`` of the input array ``x``.