Add support for copysign to the specification

kgryte · web-flow · commit 03886d61efdd · 2023-10-18T16:44:46.000-07:00
PR-URL: #693
diff --git a/spec/draft/API_specification/elementwise_functions.rst b/spec/draft/API_specification/elementwise_functions.rst
@@ -34,6 +34,7 @@ Objects in API
    bitwise_xor
    ceil
    conj
+   copysign
    cos
    cosh
    divide
diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py
@@ -16,6 +16,7 @@
     "bitwise_xor",
     "ceil",
     "conj",
+    "copysign",
     "cos",
     "cosh",
     "divide",
@@ -804,6 +805,47 @@ def conj(x: array, /) -> array:
     """
 
 
+def copysign(x1: array, x2: array, /) -> array:
+    r"""
+    Composes a floating-point value with the magnitude of ``x1_i`` and the sign of ``x2_i`` for each element of the input array ``x1``.
+
+    Parameters
+    ----------
+    x1: array
+       input array containing magnitudes. Should have a real-valued floating-point data type.
+    x2: array
+       input array whose sign bits are applied to the magnitudes of ``x1``. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued floating-point data type.
+
+    Returns
+    -------
+    out: array
+       an array containing the element-wise results. The returned array must have a floating-point data type determined by :ref:`type-promotion`.
+
+    Notes
+    -----
+
+    **Special cases**
+
+    For real-valued floating-point operands, let ``|x|`` be the absolute value, and if ``x1_i`` is not ``NaN``,
+
+    - If ``x2_i`` is less than ``0``, the result is ``-|x1_i|``.
+    - If ``x2_i`` is ``-0``, the result is ``-|x1_i|``.
+    - If ``x2_i`` is ``+0``, the result is ``|x1_i|``.
+    - If ``x2_i`` is greater than ``0``, the result is ``|x1_i|``.
+    - If ``x2_i`` is ``NaN`` and the sign bit of ``x2_i`` is ``1``, the result is ``-|x1_i|``.
+    - If ``x2_i`` is ``NaN`` and the sign bit of ``x2_i`` is ``0``, the result is ``|x1_i|``.
+
+    If ``x1_i`` is ``NaN``,
+
+    - If ``x2_i`` is less than ``0``, the result is ``NaN`` with a sign bit of ``1``.
+    - If ``x2_i`` is ``-0``, the result is ``NaN`` with a sign bit of ``1``.
+    - If ``x2_i`` is ``+0``, the result is ``NaN`` with a sign bit of ``0``.
+    - If ``x2_i`` is greater than ``0``, the result is ``NaN`` with a sign bit of ``0``.
+    - If ``x2_i`` is ``NaN`` and the sign bit of ``x2_i`` is ``1``, the result is ``NaN`` with a sign bit of ``1``.
+    - If ``x2_i`` is ``NaN`` and the sign bit of ``x2_i`` is ``0``, the result is ``NaN`` with a sign bit of ``0``.
+    """
+
+
 def cos(x: array, /) -> array:
     r"""
     Calculates an implementation-dependent approximation to the cosine for each element ``x_i`` of the input array ``x``.
