33.. _complexobjects :
44
55Complex Number Objects
6- ----------------------
6+ ======================
77
88.. index :: pair: object; complex number
99
10- Python's complex number objects are implemented as two distinct types when
11- viewed from the C API: one is the Python object exposed to Python programs, and
12- the other is a C structure which represents the actual complex number value.
13- The API provides functions for working with both.
14-
15-
16- Complex Numbers as C Structures
17- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
18-
19- Note that the functions which accept these structures as parameters and return
20- them as results do so *by value * rather than dereferencing them through
21- pointers. This is consistent throughout the API.
22-
23-
24- .. c :type :: Py_complex
25-
26-
27- number object. Most of the functions for dealing with complex number objects
28- use structures of this type as input or output values, as appropriate.
29-
30- .. c :member :: double real
31- double imag
32-
33-
34-
35- typedef struct {
36- double real;
37- double imag;
38- } Py_complex;
39-
40-
41- .. c :function :: Py_complex _Py_c_sum (Py_complex left, Py_complex right)
42-
43- Return the sum of two complex numbers, using the C :c:type:`Py_complex`
44- representation.
45-
46- .. deprecated:: 3.15
47- This function is :term:`soft deprecated`.
48-
49-
50- .. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
51-
52- Return the difference between two complex numbers, using the C
53- :c:type:`Py_complex` representation.
54-
55- .. deprecated:: 3.15
56- This function is :term:`soft deprecated`.
57-
58-
59- .. c:function:: Py_complex _Py_c_neg(Py_complex num)
60-
61- Return the negation of the complex number *num*, using the C
62- :c:type:`Py_complex` representation.
63-
64- .. deprecated:: 3.15
65- This function is :term:`soft deprecated`.
66-
67-
68- .. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
69-
70- Return the product of two complex numbers, using the C :c:type:`Py_complex`
71- representation.
72-
73- .. deprecated:: 3.15
74- This function is :term:`soft deprecated`.
75-
76-
77- .. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
78-
79- Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
80- representation.
81-
82- If *divisor* is null, this method returns zero and sets
83- :c:data:`errno` to :c:macro:`!EDOM`.
84-
85- .. deprecated:: 3.15
86- This function is :term:`soft deprecated`.
87-
88-
89- .. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
90-
91- Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
92- representation.
93-
94- If *num* is null and *exp* is not a positive real number,
95- this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
96-
97- Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
98-
99- .. deprecated:: 3.15
100- This function is :term:`soft deprecated`.
101-
102-
103- .. c:function:: double _Py_c_abs(Py_complex num)
104-
105- Return the absolute value of the complex number *num*.
106-
107- Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
108-
109- .. deprecated:: 3.15
110- This function is :term:`soft deprecated`.
111-
112-
113- Complex Numbers as Python Objects
114- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
115-
11610
11711.. c :type :: PyComplexObject
11812
@@ -147,12 +41,6 @@ Complex Numbers as Python Objects
14741 :c:type: `PyComplexObject `. This function always succeeds.
14842
14943
150- .. c :function :: PyObject* PyComplex_FromCComplex (Py_complex v)
151-
152- Create a new Python complex number object from a C :c:type:`Py_complex` value.
153- Return ``NULL`` with an exception set on error.
154-
155-
15644.. c :function :: PyObject* PyComplex_FromDoubles (double real, double imag)
15745
15846 Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
@@ -191,6 +79,29 @@ Complex Numbers as Python Objects
19179 .. versionchanged :: 3.13
19280 Use :meth: `~object.__complex__ ` if available.
19381
82+
83+ .. c :type :: Py_complex
84+
85+
86+ number object.
87+
88+ .. c :member :: double real
89+ double imag
90+
91+
92+
93+ typedef struct {
94+ double real;
95+ double imag;
96+ } Py_complex;
97+
98+
99+ .. c :function :: PyObject* PyComplex_FromCComplex (Py_complex v)
100+
101+ Create a new Python complex number object from a C :c:type:`Py_complex` value.
102+ Return ``NULL`` with an exception set on error.
103+
104+
194105.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
195106
196107 Return the :c:type: `Py_complex ` value of the complex number *op *.
@@ -207,3 +118,82 @@ Complex Numbers as Python Objects
207118
208119 .. versionchanged :: 3.8
209120 Use :meth: `~object.__index__ ` if available.
121+
122+
123+ Complex Numbers as C Structures
124+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
125+
126+ The API also provides functions for working with complex numbers, using the
127+ :c:type: `Py_complex ` representation. Note that the functions which accept
128+ these structures as parameters and return them as results do so *by value *
129+ rather than dereferencing them through pointers.
130+
131+ Please note, that these functions are :term: `soft deprecated ` since Python
132+ 3.15. Avoid using this API in a new code to do complex arithmetic: either use
133+ the `Number Protocol <number >`_ API or use native complex types, like
134+ :c:expr: `double complex `.
135+
136+
137+ .. c :function :: Py_complex _Py_c_sum (Py_complex left, Py_complex right)
138+
139+ Return the sum of two complex numbers, using the C :c:type:`Py_complex`
140+ representation.
141+
142+ .. deprecated:: 3.15
143+
144+
145+ .. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
146+
147+ Return the difference between two complex numbers, using the C
148+ :c:type:`Py_complex` representation.
149+
150+ .. deprecated:: 3.15
151+
152+
153+ .. c:function:: Py_complex _Py_c_neg(Py_complex num)
154+
155+ Return the negation of the complex number *num*, using the C
156+ :c:type:`Py_complex` representation.
157+
158+ .. deprecated:: 3.15
159+
160+
161+ .. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
162+
163+ Return the product of two complex numbers, using the C :c:type:`Py_complex`
164+ representation.
165+
166+ .. deprecated:: 3.15
167+
168+
169+ .. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
170+
171+ Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
172+ representation.
173+
174+ If *divisor* is null, this method returns zero and sets
175+ :c:data:`errno` to :c:macro:`!EDOM`.
176+
177+ .. deprecated:: 3.15
178+
179+
180+ .. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
181+
182+ Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
183+ representation.
184+
185+ If *num* is null and *exp* is not a positive real number,
186+ this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
187+
188+ Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
189+
190+ .. deprecated:: 3.15
191+
192+
193+ .. c:function:: double _Py_c_abs(Py_complex num)
194+
195+ Return the absolute value of the complex number *num*.
196+
197+ Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
198+
199+ .. deprecated:: 3.15
0 commit comments