Add signbit specification for determining whether a sign bit is set (data-apis#705)

Author: kgryte

spec/draft/API_specification/elementwise_functions.rst

@@ -69,6 +69,7 @@ Objects in API
    remainder
    round
    sign
+   signbit
    sin
    sinh
    square

src/array_api_stubs/_draft/elementwise_functions.py

@@ -51,6 +51,7 @@
     "remainder",
     "round",
     "sign",
+    "signbit",
     "sin",
     "sinh",
     "square",
@@ -2215,6 +2216,40 @@ def sign(x: array, /) -> array:
     """
 
 
+def signbit(x: array, /) -> array:
+    r"""
+    Determines whether the sign bit is set for each element ``x_i`` of the input array ``x``.
+
+    The sign bit of a real-valued floating-point number ``x_i`` is set whenever ``x_i`` is either ``-0``, less than zero, or a signed ``NaN`` (i.e., a ``NaN`` value whose sign bit is ``1``).
+
+    Parameters
+    ----------
+    x: array
+        input array. Should have a real-valued floating-point data type.
+
+    Returns
+    -------
+    out: array
+        an array containing the evaluated result for each element in ``x``. The returned array must have a data type of ``bool``.
+
+    Notes
+    -----
+
+    **Special cases**
+
+    For real-valued floating-point operands,
+
+    - If ``x_i`` is ``+0``, the result is ``False``.
+    - If ``x_i`` is ``-0``, the result is ``True``.
+    - If ``x_i`` is ``+infinity``, the result is ``False``.
+    - If ``x_i`` is ``-infinity``, the result is ``True``.
+    - If ``x_i`` is a positive (i.e., greater than ``0``) finite number, the result is ``False``.
+    - If ``x_i`` is a negative (i.e., less than ``0``) finite number, the result is ``True``.
+    - If ``x_i`` is ``NaN`` and the sign bit of ``x_i`` is ``0``, the result is ``False``.
+    - If ``x_i`` is ``NaN`` and the sign bit of ``x_i`` is ``1``, the result is ``True``.
+    """
+
+
 def sin(x: array, /) -> array:
     r"""
     Calculates an implementation-dependent approximation to the sine for each element ``x_i`` of the input array ``x``.