gh-69639: Add mixed-mode rules for complex arithmetic (C-like) (GH-124829)

"Generally, mixed-mode arithmetic combining real and complex variables should
be performed directly, not by first coercing the real to complex, lest the sign
of zero be rendered uninformative; the same goes for combinations of pure
imaginary quantities with complex variables." (c) Kahan, W: Branch cuts for
complex elementary functions.

This patch implements mixed-mode arithmetic rules, combining real and
complex variables as specified by C standards since C99 (in particular,
there is no special version for the true division with real lhs
operand).  Most C compilers implementing C99+ Annex G have only these
special rules (without support for imaginary type, which is going to be
deprecated in C2y).

1 files changed, 54 insertions, 0 deletions

diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index 16bd794..d1f5d8e 100644
--- a/Doc/c-api/complex.rst
+++ b/Doc/c-api/complex.rst
@@ -44,12 +44,36 @@ pointers.  This is consistent throughout the API.
    representation.
 
 
+.. c:function:: Py_complex _Py_cr_sum(Py_complex left, double right)
+
+   Return the sum of a complex number and a real number, using the C :c:type:`Py_complex`
+   representation.
+
+   .. versionadded:: 3.14
+
+
 .. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
 
    Return the difference between two complex numbers, using the C
    :c:type:`Py_complex` representation.
 
 
+.. c:function:: Py_complex _Py_cr_diff(Py_complex left, double right)
+
+   Return the difference between a complex number and a real number, using the C
+   :c:type:`Py_complex` representation.
+
+   .. versionadded:: 3.14
+
+
+.. c:function:: Py_complex _Py_rc_diff(double left, Py_complex right)
+
+   Return the difference between a real number and a complex number, using the C
+   :c:type:`Py_complex` representation.
+
+   .. versionadded:: 3.14
+
+
 .. c:function:: Py_complex _Py_c_neg(Py_complex num)
 
    Return the negation of the complex number *num*, using the C
@@ -62,6 +86,14 @@ pointers.  This is consistent throughout the API.
    representation.
 
 
+.. c:function:: Py_complex _Py_cr_prod(Py_complex left, double right)
+
+   Return the product of a complex number and a real number, using the C
+   :c:type:`Py_complex` representation.
+
+   .. versionadded:: 3.14
+
+
 .. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
 
    Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
@@ -71,6 +103,28 @@ pointers.  This is consistent throughout the API.
    :c:data:`errno` to :c:macro:`!EDOM`.
 
 
+.. c:function:: Py_complex _Py_cr_quot(Py_complex dividend, double divisor)
+
+   Return the quotient of a complex number and a real number, using the C
+   :c:type:`Py_complex` representation.
+
+   If *divisor* is zero, this method returns zero and sets
+   :c:data:`errno` to :c:macro:`!EDOM`.
+
+   .. versionadded:: 3.14
+
+
+.. c:function:: Py_complex _Py_rc_quot(double dividend, Py_complex divisor)
+
+   Return the quotient of a real number and a complex number, using the C
+   :c:type:`Py_complex` representation.
+
+   If *divisor* is zero, this method returns zero and sets
+   :c:data:`errno` to :c:macro:`!EDOM`.
+
+   .. versionadded:: 3.14
+
+
 .. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
 
    Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`