Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/complex.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents 74ff71b2f53d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _complexobjects:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Complex Number Objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ----------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index:: object: complex number
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 Python's complex number objects are implemented as two distinct types when
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 viewed from the C API: one is the Python object exposed to Python programs, and
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 the other is a C structure which represents the actual complex number value.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 The API provides functions for working with both.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 Complex Numbers as C Structures
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 Note that the functions which accept these structures as parameters and return
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 them as results do so *by value* rather than dereferencing them through
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 pointers. This is consistent throughout the API.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
24 .. c:type:: Py_complex
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 The C structure which corresponds to the value portion of a Python complex
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 number object. Most of the functions for dealing with complex number objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 use structures of this type as input or output values, as appropriate. It is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 defined as::
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 typedef struct {
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 double real;
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 double imag;
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 } Py_complex;
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
37 .. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
39 Return the sum of two complex numbers, using the C :c:type:`Py_complex`
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 representation.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
43 .. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
44
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 Return the difference between two complex numbers, using the C
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
46 :c:type:`Py_complex` representation.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
49 .. c:function:: Py_complex _Py_c_neg(Py_complex complex)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
50
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 Return the negation of the complex number *complex*, using the C
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
52 :c:type:`Py_complex` representation.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
55 .. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
57 Return the product of two complex numbers, using the C :c:type:`Py_complex`
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 representation.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
61 .. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
62
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
63 Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 representation.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
65
74025
059e4d752fbe Issue #13522: document error return values of some float and complex C API functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 44796
diff changeset
66 If *divisor* is null, this method returns zero and sets
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
67 :c:data:`errno` to :c:data:`EDOM`.
74025
059e4d752fbe Issue #13522: document error return values of some float and complex C API functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 44796
diff changeset
68
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
70 .. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
72 Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 representation.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
74030
2863470caebb Issue #13522: Fix _Py_co_pow() documentation
Victor Stinner <victor.stinner@haypocalc.com>
parents: 74025
diff changeset
75 If *num* is null and *exp* is not a positive real number,
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
76 this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.
74025
059e4d752fbe Issue #13522: document error return values of some float and complex C API functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 44796
diff changeset
77
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
78
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 Complex Numbers as Python Objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
81
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
83 .. c:type:: PyComplexObject
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
85 This subtype of :c:type:`PyObject` represents a Python complex number object.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
88 .. c:var:: PyTypeObject PyComplex_Type
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
90 This instance of :c:type:`PyTypeObject` represents the Python complex number
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 type. It is the same object as ``complex`` and ``types.ComplexType``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
92
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
94 .. c:function:: int PyComplex_Check(PyObject *p)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
95
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
96 Return true if its argument is a :c:type:`PyComplexObject` or a subtype of
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
97 :c:type:`PyComplexObject`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
98
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 .. versionchanged:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 Allowed subtypes to be accepted.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
101
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
103 .. c:function:: int PyComplex_CheckExact(PyObject *p)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
105 Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
106 :c:type:`PyComplexObject`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
107
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
111 .. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
112
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
113 Create a new Python complex number object from a C :c:type:`Py_complex` value.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
114
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
115
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
116 .. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
118 Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
121 .. c:function:: double PyComplex_RealAsDouble(PyObject *op)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
122
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
123 Return the real part of *op* as a C :c:type:`double`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
125
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
126 .. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
127
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
128 Return the imaginary part of *op* as a C :c:type:`double`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
129
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
130
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
131 .. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
132
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74030
diff changeset
133 Return the :c:type:`Py_complex` value of the complex number *op*.
74025
059e4d752fbe Issue #13522: document error return values of some float and complex C API functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 44796
diff changeset
134 Upon failure, this method returns ``-1.0`` as a real value.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
135
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 .. versionchanged:: 2.6
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 If *op* is not a Python complex number object but has a :meth:`__complex__`
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
138 method, this method will first be called to convert *op* to a Python complex
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 number object.