mirror of
https://github.com/python/cpython.git
synced 2026-03-02 19:10:46 +00:00
gh-128813: cleanup C-API docs for PyComplexObject (GH-137579)
* move non-deprecated API up * make a dedicated section for deprecated low-leved API
This commit is contained in:
Sergey B Kirpichev
GitHub
parent
4497ad409e
commit
bc4996c125
1 changed files with 103 additions and 113 deletions
|
|
@ -3,116 +3,10 @@
|
|||
.. _complexobjects:
|
||||
|
||||
Complex Number Objects
|
||||
----------------------
|
||||
======================
|
||||
|
||||
.. index:: pair: object; complex number
|
||||
|
||||
Python's complex number objects are implemented as two distinct types when
|
||||
viewed from the C API: one is the Python object exposed to Python programs, and
|
||||
the other is a C structure which represents the actual complex number value.
|
||||
The API provides functions for working with both.
|
||||
|
||||
|
||||
Complex Numbers as C Structures
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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. This is consistent throughout the API.
|
||||
|
||||
|
||||
.. c:type:: Py_complex
|
||||
|
||||
The C structure which corresponds to the value portion of a Python complex
|
||||
number object. Most of the functions for dealing with complex number objects
|
||||
use structures of this type as input or output values, as appropriate.
|
||||
|
||||
.. c:member:: double real
|
||||
double imag
|
||||
|
||||
The structure is defined as::
|
||||
|
||||
typedef struct {
|
||||
double real;
|
||||
double imag;
|
||||
} Py_complex;
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
|
||||
|
||||
Return the sum of two complex numbers, using the C :c:type:`Py_complex`
|
||||
representation.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
This function is :term:`soft deprecated`.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
This function is :term:`soft deprecated`.
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_neg(Py_complex num)
|
||||
|
||||
Return the negation of the complex number *num*, using the C
|
||||
:c:type:`Py_complex` representation.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
This function is :term:`soft deprecated`.
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
|
||||
|
||||
Return the product of two complex numbers, using the C :c:type:`Py_complex`
|
||||
representation.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
This function is :term:`soft deprecated`.
|
||||
|
||||
|
||||
.. 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`
|
||||
representation.
|
||||
|
||||
If *divisor* is null, this method returns zero and sets
|
||||
:c:data:`errno` to :c:macro:`!EDOM`.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
This function is :term:`soft deprecated`.
|
||||
|
||||
|
||||
.. 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`
|
||||
representation.
|
||||
|
||||
If *num* is null and *exp* is not a positive real number,
|
||||
this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
|
||||
|
||||
Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
This function is :term:`soft deprecated`.
|
||||
|
||||
|
||||
.. c:function:: double _Py_c_abs(Py_complex num)
|
||||
|
||||
Return the absolute value of the complex number *num*.
|
||||
|
||||
Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
This function is :term:`soft deprecated`.
|
||||
|
||||
|
||||
Complex Numbers as Python Objects
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
.. c:type:: PyComplexObject
|
||||
|
||||
|
|
@ -147,12 +41,6 @@ Complex Numbers as Python Objects
|
|||
:c:type:`PyComplexObject`. This function always succeeds.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
|
||||
|
||||
Create a new Python complex number object from a C :c:type:`Py_complex` value.
|
||||
Return ``NULL`` with an exception set on error.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
|
||||
|
||||
Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
|
||||
|
|
@ -191,6 +79,29 @@ Complex Numbers as Python Objects
|
|||
.. versionchanged:: 3.13
|
||||
Use :meth:`~object.__complex__` if available.
|
||||
|
||||
|
||||
.. c:type:: Py_complex
|
||||
|
||||
This C structure defines export format for a Python complex
|
||||
number object.
|
||||
|
||||
.. c:member:: double real
|
||||
double imag
|
||||
|
||||
The structure is defined as::
|
||||
|
||||
typedef struct {
|
||||
double real;
|
||||
double imag;
|
||||
} Py_complex;
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
|
||||
|
||||
Create a new Python complex number object from a C :c:type:`Py_complex` value.
|
||||
Return ``NULL`` with an exception set on error.
|
||||
|
||||
|
||||
.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
|
||||
|
||||
Return the :c:type:`Py_complex` value of the complex number *op*.
|
||||
|
|
@ -207,3 +118,82 @@ Complex Numbers as Python Objects
|
|||
|
||||
.. versionchanged:: 3.8
|
||||
Use :meth:`~object.__index__` if available.
|
||||
|
||||
|
||||
Complex Numbers as C Structures
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The API also provides functions for working with complex numbers, using the
|
||||
:c:type:`Py_complex` 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 :term:`soft deprecated` 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
|
||||
:c:expr:`double complex`.
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
|
||||
|
||||
Return the sum of two complex numbers, using the C :c:type:`Py_complex`
|
||||
representation.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_neg(Py_complex num)
|
||||
|
||||
Return the negation of the complex number *num*, using the C
|
||||
:c:type:`Py_complex` representation.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
|
||||
|
||||
Return the product of two complex numbers, using the C :c:type:`Py_complex`
|
||||
representation.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
|
||||
|
||||
.. 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`
|
||||
representation.
|
||||
|
||||
If *divisor* is null, this method returns zero and sets
|
||||
:c:data:`errno` to :c:macro:`!EDOM`.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
|
||||
|
||||
.. 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`
|
||||
representation.
|
||||
|
||||
If *num* is null and *exp* is not a positive real number,
|
||||
this method returns zero and sets :c:data:`errno` to :c:macro:`!EDOM`.
|
||||
|
||||
Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
|
||||
|
||||
.. c:function:: double _Py_c_abs(Py_complex num)
|
||||
|
||||
Return the absolute value of the complex number *num*.
|
||||
|
||||
Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
|
||||
|
||||
.. deprecated:: 3.15
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue