Spaces:
Running on Zero
Running on Zero
File size: 6,261 Bytes
9273228 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | # Complex Number Objects {#complexobjects}
::: index
pair: object; complex number
:::
> This subtype of `PyObject`{.interpreted-text role="c:type"} represents a Python complex number object.
>
> > The complex number value, using the C `Py_complex`{.interpreted-text role="c:type"} representation.
> >
> > ::: deprecated-removed
> > 3.15 3.20 Use `PyComplex_AsCComplex`{.interpreted-text role="c:func"} and `PyComplex_FromCComplex`{.interpreted-text role="c:func"} to convert a Python complex number to/from the C `Py_complex`{.interpreted-text role="c:type"} representation.
> > :::
> This instance of `PyTypeObject`{.interpreted-text role="c:type"} represents the Python complex number type. It is the same object as `complex`{.interpreted-text role="class"} in the Python layer.
> Return true if its argument is a `PyComplexObject`{.interpreted-text role="c:type"} or a subtype of `PyComplexObject`{.interpreted-text role="c:type"}. This function always succeeds.
> Return true if its argument is a `PyComplexObject`{.interpreted-text role="c:type"}, but not a subtype of `PyComplexObject`{.interpreted-text role="c:type"}. This function always succeeds.
> Return a new `PyComplexObject`{.interpreted-text role="c:type"} object from *real* and *imag*. Return `NULL` with an exception set on error.
> Return the real part of *op* as a C `double`{.interpreted-text role="c:expr"}.
>
> If *op* is not a Python complex number object but has a `~object.__complex__`{.interpreted-text role="meth"} method, this method will first be called to convert *op* to a Python complex number object. If `!__complex__`{.interpreted-text role="meth"} is not defined then it falls back to call `PyFloat_AsDouble`{.interpreted-text role="c:func"} and returns its result.
>
> Upon failure, this method returns `-1.0` with an exception set, so one should call `PyErr_Occurred`{.interpreted-text role="c:func"} to check for errors.
>
> ::: versionchanged
> 3.13 Use `~object.__complex__`{.interpreted-text role="meth"} if available.
> :::
> Return the imaginary part of *op* as a C `double`{.interpreted-text role="c:expr"}.
>
> If *op* is not a Python complex number object but has a `~object.__complex__`{.interpreted-text role="meth"} method, this method will first be called to convert *op* to a Python complex number object. If `!__complex__`{.interpreted-text role="meth"} is not defined then it falls back to call `PyFloat_AsDouble`{.interpreted-text role="c:func"} and returns `0.0` on success.
>
> Upon failure, this method returns `-1.0` with an exception set, so one should call `PyErr_Occurred`{.interpreted-text role="c:func"} to check for errors.
>
> ::: versionchanged
> 3.13 Use `~object.__complex__`{.interpreted-text role="meth"} if available.
> :::
> This C structure defines an export format for a Python complex number object.
>
> The structure is defined as:
>
> ``` c
> typedef struct {
> double real;
> double imag;
> } Py_complex;
> ```
> Create a new Python complex number object from a C `Py_complex`{.interpreted-text role="c:type"} value. Return `NULL` with an exception set on error.
> Return the `Py_complex`{.interpreted-text role="c:type"} value of the complex number *op*.
>
> If *op* is not a Python complex number object but has a `~object.__complex__`{.interpreted-text role="meth"} method, this method will first be called to convert *op* to a Python complex number object. If `!__complex__`{.interpreted-text role="meth"} is not defined then it falls back to `~object.__float__`{.interpreted-text role="meth"}. If `!__float__`{.interpreted-text role="meth"} is not defined then it falls back to `~object.__index__`{.interpreted-text role="meth"}.
>
> Upon failure, this method returns `Py_complex`{.interpreted-text role="c:type"} with `~Py_complex.real`{.interpreted-text role="c:member"} set to `-1.0` and with an exception set, so one should call `PyErr_Occurred`{.interpreted-text role="c:func"} to check for errors.
>
> ::: versionchanged
> 3.8 Use `~object.__index__`{.interpreted-text role="meth"} if available.
> :::
## Complex Numbers as C Structures
The API also provides functions for working with complex numbers, using the `Py_complex`{.interpreted-text role="c:type"} representation. Note that the functions which accept these structures as parameters and return them as results do so *by value* rather than dereferencing them through pointers.
Please note, that these functions are `soft deprecated`{.interpreted-text role="term"} since Python 3.15. Avoid using this API in a new code to do complex arithmetic: either use the [Number Protocol](number) API or use native complex types, like `double complex`{.interpreted-text role="c:expr"}.
> Return the sum of two complex numbers, using the C `Py_complex`{.interpreted-text role="c:type"} representation.
>
> ::: deprecated
> 3.15
> :::
> Return the difference between two complex numbers, using the C `Py_complex`{.interpreted-text role="c:type"} representation.
>
> ::: deprecated
> 3.15
> :::
> Return the negation of the complex number *num*, using the C `Py_complex`{.interpreted-text role="c:type"} representation.
>
> ::: deprecated
> 3.15
> :::
> Return the product of two complex numbers, using the C `Py_complex`{.interpreted-text role="c:type"} representation.
>
> ::: deprecated
> 3.15
> :::
> Return the quotient of two complex numbers, using the C `Py_complex`{.interpreted-text role="c:type"} representation.
>
> If *divisor* is null, this method returns zero and sets `errno`{.interpreted-text role="c:data"} to `!EDOM`{.interpreted-text role="c:macro"}.
>
> ::: deprecated
> 3.15
> :::
> Return the exponentiation of *num* by *exp*, using the C `Py_complex`{.interpreted-text role="c:type"} representation.
>
> If *num* is null and *exp* is not a positive real number, this method returns zero and sets `errno`{.interpreted-text role="c:data"} to `!EDOM`{.interpreted-text role="c:macro"}.
>
> Set `errno`{.interpreted-text role="c:data"} to `!ERANGE`{.interpreted-text role="c:macro"} on overflows.
>
> ::: deprecated
> 3.15
> :::
> Return the absolute value of the complex number *num*.
>
> Set `errno`{.interpreted-text role="c:data"} to `!ERANGE`{.interpreted-text role="c:macro"} on overflows.
>
> ::: deprecated
> 3.15
> :::
|