1 .. highlightlang:: c

     2 

     3 .. _complexobjects:

     4 

     5 Complex Number Objects

     6 ----------------------

     7 

     8 .. index:: object: complex number

     9 

    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 .. ctype:: Py_complex

    25 

    26    The C structure which corresponds to the value portion of a Python complex

    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.  It is

    29    defined as::

    30 

    31       typedef struct {

    32          double real;

    33          double imag;

    34       } Py_complex;

    35 

    36 

    37 .. cfunction:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)

    38 

    39    Return the sum of two complex numbers, using the C :ctype:`Py_complex`

    40    representation.

    41 

    42 

    43 .. cfunction:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)

    44 

    45    Return the difference between two complex numbers, using the C

    46    :ctype:`Py_complex` representation.

    47 

    48 

    49 .. cfunction:: Py_complex _Py_c_neg(Py_complex complex)

    50 

    51    Return the negation of the complex number *complex*, using the C

    52    :ctype:`Py_complex` representation.

    53 

    54 

    55 .. cfunction:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)

    56 

    57    Return the product of two complex numbers, using the C :ctype:`Py_complex`

    58    representation.

    59 

    60 

    61 .. cfunction:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)

    62 

    63    Return the quotient of two complex numbers, using the C :ctype:`Py_complex`

    64    representation.

    65 

    66 

    67 .. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)

    68 

    69    Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex`

    70    representation.

    71 

    72 

    73 Complex Numbers as Python Objects

    74 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    75 

    76 

    77 .. ctype:: PyComplexObject

    78 

    79    This subtype of :ctype:`PyObject` represents a Python complex number object.

    80 

    81 

    82 .. cvar:: PyTypeObject PyComplex_Type

    83 

    84    This instance of :ctype:`PyTypeObject` represents the Python complex number

    85    type. It is the same object as ``complex`` and ``types.ComplexType``.

    86 

    87 

    88 .. cfunction:: int PyComplex_Check(PyObject *p)

    89 

    90    Return true if its argument is a :ctype:`PyComplexObject` or a subtype of

    91    :ctype:`PyComplexObject`.

    92 

    93    .. versionchanged:: 2.2

    94       Allowed subtypes to be accepted.

    95 

    96 

    97 .. cfunction:: int PyComplex_CheckExact(PyObject *p)

    98 

    99    Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of

   100    :ctype:`PyComplexObject`.

   101 

   102    .. versionadded:: 2.2

   103 

   104 

   105 .. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v)

   106 

   107    Create a new Python complex number object from a C :ctype:`Py_complex` value.

   108 

   109 

   110 .. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag)

   111 

   112    Return a new :ctype:`PyComplexObject` object from *real* and *imag*.

   113 

   114 

   115 .. cfunction:: double PyComplex_RealAsDouble(PyObject *op)

   116 

   117    Return the real part of *op* as a C :ctype:`double`.

   118 

   119 

   120 .. cfunction:: double PyComplex_ImagAsDouble(PyObject *op)

   121 

   122    Return the imaginary part of *op* as a C :ctype:`double`.

   123 

   124 

   125 .. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op)

   126 

   127    Return the :ctype:`Py_complex` value of the complex number *op*.

   128 

   129    .. versionchanged:: 2.6

   130       If *op* is not a Python complex number object but has a :meth:`__complex__`

   131       method, this method will first be called to convert *op* to a Python complex

   132       number object.