# 复数对象

type PyComplexObject

  这个 C 类型 `PyObject` 的子类型代表一个 Python 复数对象。

  Py_complex cval

    The complex number value, using the C `Py_complex` representation.

    从 3.15 版起已弃用，将在 3.20 版中移除: Use `PyComplex_AsCComplex()` and `PyComplex_FromCComplex()` to convert a Python complex number to/from the C `Py_complex` representation.

PyTypeObject PyComplex_Type
  属于 稳定 ABI.

  这是个属于 `PyTypeObject` 的代表 Python 复数类型的实例。在 Python 层面的类型 `complex` 是同一个对象。

int PyComplex_Check(PyObject *p)

  如果它的参数是一个 `PyComplexObject` 或者 `PyComplexObject` 的子类型则返回真值。 此函数总是会成功执行。

int PyComplex_CheckExact(PyObject *p)

  如果它的参数是一个 `PyComplexObject` 但不是 `PyComplexObject` 的子类型则返回真值。 此函数总是会成功执行。

PyObject *PyComplex_FromDoubles(double real, double imag)
  返回值：新的引用。 属于 稳定 ABI.

  根据 real 和 imag 返回一个新的 `PyComplexObject` 对象。 当发生错误时将返回 `NULL` 并设置一个异常。

double PyComplex_RealAsDouble(PyObject *op)
  属于 稳定 ABI.

  以 C 类型 double 返回 op 的实部。

  如果 op 不是一个 Python 复数对象但是具有 `__complex__()` 方法，则会先调用该方法将 op 转换为 Python 复数对象。 如果未定义 `__complex__()` 则将回退为调用 `PyFloat_AsDouble()` 并返回其结果。

  当失败时，此方法将返回 `-1.0` 并设置一个异常，因此开发者应当调用 `PyErr_Occurred()` 来检查错误。

  在 3.13 版本发生变更: 如果可能将使用 `__complex__()`。

double PyComplex_ImagAsDouble(PyObject *op)
  属于 稳定 ABI.

  以 C 类型 double 返回 op 的虚部。

  如果 op 不是一个 Python 复数对象但是具有 `__complex__()` 方法，则会先调用该方法将 op 转换为 Python 复数对象。 如果未定义 `__complex__()` 则将回退为调用 `PyFloat_AsDouble()` 并在成功时返回 `0.0`。

  当失败时，此方法将返回 `-1.0` 并设置一个异常，因此开发者应当调用 `PyErr_Occurred()` 来检查错误。

  在 3.13 版本发生变更: 如果可能将使用 `__complex__()`。

type Py_complex

  This C structure defines an export format for a Python complex number object.

  double real
  double imag

  其结构定义如下：

      typedef struct {
          double real;
          double imag;
      } Py_complex;

PyObject *PyComplex_FromCComplex(Py_complex v)
  返回值：新的引用。

  根据一个 C `Py_complex` 值新建 Python 复数对象。 当发生错误时将返回 `NULL` 并设置一个异常。

Py_complex PyComplex_AsCComplex(PyObject *op)

  返回复数 op 的 C 类型 `Py_complex` 值。

  如果 op 不是一个 Python 复数对象但是具有 `__complex__()` 方法，则会先调用该方法将 op 转换为 Python 复数对象。 如果未定义 `__complex__()` 则将回退至 `__float__()`。 如果未定义 `__float__()` 则将回退至 `__index__()`。

  当失败时，此方法将返回 `Py_complex` 其中 `real` 为 `-1.0` 并设置一个异常，因此开发者应当调用 `PyErr_Occurred()` 来检查错误。

  在 3.8 版本发生变更: 如果可能将使用 `__index__()`。

## 表示复数的 C 结构体

The API also provides functions for working with complex numbers, using the `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 soft deprecated since Python 3.15. Avoid using this API in a new code to do complex arithmetic: either use the Number Protocol API or use native complex types, like double complex.

Py_complex _Py_c_sum(Py_complex left, Py_complex right)

  返回两个复数的和，用 C 类型 `Py_complex` 表示。

  自 3.15 版本弃用.

Py_complex _Py_c_diff(Py_complex left, Py_complex right)

  返回两个复数的差，用 C 类型 `Py_complex` 表示。

  自 3.15 版本弃用.

Py_complex _Py_c_neg(Py_complex num)

  返回复数 num 的负值，用 C `Py_complex` 表示。

  自 3.15 版本弃用.

Py_complex _Py_c_prod(Py_complex left, Py_complex right)

  返回两个复数的乘积，用 C 类型 `Py_complex` 表示。

  自 3.15 版本弃用.

Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)

  返回两个复数的商，用 C 类型 `Py_complex` 表示。

  如果 divisor 为空，则此方法将返回零并将 `errno` 设为 `EDOM`。

  自 3.15 版本弃用.

Py_complex _Py_c_pow(Py_complex num, Py_complex exp)

  返回 num 的 exp 次幂，用 C 类型 `Py_complex` 表示。

  如果 num 为空且 exp 不是正实数，则此方法将返回零并将 `errno` 设为 `EDOM`。

  当溢出时将 `errno` 设为 `ERANGE`。

  自 3.15 版本弃用.

double _Py_c_abs(Py_complex num)

  Return the absolute value of the complex number num.

  当溢出时将 `errno` 设为 `ERANGE`。

  自 3.15 版本弃用.