複素数オブジェクト
******************

Python の複素数オブジェクトは、C API 側から見ると二つの別個の型として
実装されています: 一方は Python プログラムに対して公開されている
Python のオブジェクトで、他方は実際の複素数値を表現する C の構造体です
。API では、これら双方を扱う関数を提供しています。


C 構造体としての複素数
======================

複素数の C 構造体を引数として受理したり、戻り値として返したりする関数
は、ポインタ渡しを行うのではなく *値渡し* を行うので注意してください。
これは API 全体を通して一貫しています。

type Py_complex

   Python 複素数オブジェクトの値の部分に対応する C の構造体です。複素
   数オブジェクトを扱うほとんどの関数は、この型の構造体を場合に応じて
   入力や出力として使います。構造体は以下のように定義されています:

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

Py_complex _Py_c_sum(Py_complex left, Py_complex right)

   二つの複素数の和を C の "Py_complex" 型で返します。

Py_complex _Py_c_diff(Py_complex left, Py_complex right)

   二つの複素数の差を C の "Py_complex" 型で返します。

Py_complex _Py_c_neg(Py_complex num)

   複素数 *num* の符号反転 C の "Py_complex" 型で返します。

Py_complex _Py_c_prod(Py_complex left, Py_complex right)

   二つの複素数の積を C の "Py_complex" 型で返します。

Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)

   二つの複素数の商を C の "Py_complex" 型で返します。

   *divisor* が null の場合は、このメソッドはゼロを返し、 "errno" に
   "EDOM" をセットします。

Py_complex _Py_c_pow(Py_complex num, Py_complex exp)

   指数 *exp* の *num* 乗を C の "Py_complex" 型で返します。

   *num* が null で *exp* が正の実数でない場合は、このメソッドはゼロを
   返し、 "errno" に "EDOM" をセットします。


Python オブジェクトとしての複素数型
===================================

type PyComplexObject

   この "PyObject" のサブタイプは Python の複素数型を表現します。

PyTypeObject PyComplex_Type
    * Part of the Stable ABI.*

   この "PyTypeObject" のインスタンスは Python の複素数型を表現します
   。 Pythonレイヤの "complex" と同じオブジェクトです。

int PyComplex_Check(PyObject *p)

   引数が "PyComplexObject" か "PyComplexObject" のサブタイプであると
   きに真を返します。この関数は常に成功します。

int PyComplex_CheckExact(PyObject *p)

   引数が "PyComplexObject" であるが "PyComplexObject" のサブタイプで
   ないときに真を返します。この関数は常に成功します。

PyObject *PyComplex_FromCComplex(Py_complex v)
    *Return value: New reference.*

   C の "Py_complex" 型から Python の複素数値を生成します。

PyObject *PyComplex_FromDoubles(double real, double imag)
    *Return value: New reference.** Part of the Stable ABI.*

   新たな "PyComplexObject" オブジェクトを *real* と *imag* から生成し
   ます。

double PyComplex_RealAsDouble(PyObject *op)
    * Part of the Stable ABI.*

   *op* の実数部分を C の double 型で返します。

   If *op* is not a Python complex number object but has a
   "__complex__()" method, this method will first be called to convert
   *op* to a Python complex number object.  If "__complex__()" is not
   defined then it falls back to call "PyFloat_AsDouble()" and returns
   its result.  Upon failure, this method returns "-1.0", so one
   should call "PyErr_Occurred()" to check for errors.

   バージョン 3.13 で変更: Use "__complex__()" if available.

double PyComplex_ImagAsDouble(PyObject *op)
    * Part of the Stable ABI.*

   *op* の虚数部分を C の double 型で返します。

   If *op* is not a Python complex number object but has a
   "__complex__()" method, this method will first be called to convert
   *op* to a Python complex number object.  If "__complex__()" is not
   defined then it falls back to call "PyFloat_AsDouble()" and returns
   "0.0" on success.  Upon failure, this method returns "-1.0", so one
   should call "PyErr_Occurred()" to check for errors.

   バージョン 3.13 で変更: Use "__complex__()" if available.

Py_complex PyComplex_AsCComplex(PyObject *op)

   複素数値 *op* から "Py_complex" 型を生成します。

   *op* が Python の複素数オブジェクトではないが、 "__complex__()" メ
   ソッドを持っていた場合、このメソッドが最初に呼ばれ、 *op* が Python
   の複素数オブジェクトに変換されます。 "__complex__()" が定義されてい
   ない場合は、 "__float__()" にフォールバックされます。 "__float__()"
   が定義されていない場合は、 "__index__()" にフォールバックされます。
   処理が失敗した場合は、このメソッドは実数の "-1.0" を返します。

   バージョン 3.8 で変更: 可能であれば "__index__()" を使うようになり
   ました。
