Objetos números complexos
*************************

Os objetos números complexos do Python são implementados como dois
tipos distintos quando visualizados na API C: um é o objeto Python
exposto aos programas Python e o outro é uma estrutura C que
representa o valor real do número complexo. A API fornece funções para
trabalhar com ambos.


Números complexos como estruturas C.
====================================

Observe que as funções que aceitam essas estruturas como parâmetros e
as retornam como resultados o fazem *por valor* em vez de
desreferenciá-las por meio de ponteiros. Isso é consistente em toda a
API.

type Py_complex

   A estrutura C que corresponde à parte do valor de um objeto de
   número complexo Python. A maioria das funções para lidar com
   objetos de números complexos usa estruturas desse tipo como valores
   de entrada ou saída, conforme apropriado.

   double real
   double imag

   A estrutura é definida como:

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

Py_complex _Py_c_sum(Py_complex left, Py_complex right)

   Retorna a soma de dois números complexos, utilizando a
   representação C "Py_complex".

Py_complex _Py_c_diff(Py_complex left, Py_complex right)

   Retorna a diferença entre dois números complexos, utilizando a
   representação C "Py_complex".

Py_complex _Py_c_neg(Py_complex num)

   Retorna a negação do número complexo *num*, utilizando a
   representação C "Py_complex".

Py_complex _Py_c_prod(Py_complex left, Py_complex right)

   Retorna o produto de dois números complexos, utilizando a
   representação C "Py_complex".

Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)

   Retorna o quociente de dois números complexos, utilizando a
   representação C "Py_complex".

   Se *divisor* é nulo, este método retorna zero e define "errno" para
   "EDOM".

Py_complex _Py_c_pow(Py_complex num, Py_complex exp)

   Retorna a exponenciação de *num* por *exp*, utilizando a
   representação C "Py_complex"

   Se *num* for nulo e *exp* não for um número real positivo, este
   método retorna zero e define "errno" para "EDOM".

   Define "errno" para "ERANGE" em caso de estouros.


Números complexos como objetos Python
=====================================

type PyComplexObject

   Este subtipo de "PyObject" representa um objeto Python de número
   complexo.

PyTypeObject PyComplex_Type
    * Parte da ABI Estável.*

   Esta instância de "PyTypeObject" representa o tipo de número
   complexo Python. É o mesmo objeto que "complex" na camada Python.

int PyComplex_Check(PyObject *p)

   Retorna true se seu argumento é um "PyComplexObject" ou um subtipo
   de "PyComplexObject". Esta função sempre tem sucesso.

int PyComplex_CheckExact(PyObject *p)

   Retorna true se seu argumento é um "PyComplexObject", mas não um
   subtipo de "PyComplexObject". Esta função sempre tem sucesso.

PyObject *PyComplex_FromCComplex(Py_complex v)
    *Retorna valor: Nova referência.*

   Cria um novo objeto de número complexo Python a partir de um valor
   C "Py_complex". Retorna "NULL" com uma exceção definida ao ocorrer
   um erro.

PyObject *PyComplex_FromDoubles(double real, double imag)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Retorna um novo objeto "PyComplexObject" de *real* e *imag*.
   Retorna "NULL" com uma exceção definida ao ocorrer um erro.

double PyComplex_RealAsDouble(PyObject *op)
    * Parte da ABI Estável.*

   Retorna a parte real de *op* como um double C.

   Se *op* não é um objeto de número complexo Python, mas tem um
   método "__complex__()", este método será primeiro chamado para
   converter *op* em um objeto de número complexo Python. Se
   "__complex__()" não estiver definido, ele volta a chamar
   "PyFloat_AsDouble()" e retorna seu resultado.

   Em caso de falha, este método retorna "-1.0" com uma exceção
   definida, então deve-se chamar "PyErr_Occurred()" para verificar se
   há erros.

   Alterado na versão 3.13: Usa "__complex__()", se disponível.

double PyComplex_ImagAsDouble(PyObject *op)
    * Parte da ABI Estável.*

   Retorna a parte imaginária de *op* como um double C.

   Se *op* não é um objeto de número complexo Python, mas tem um
   método "__complex__()", este método será primeiro chamado para
   converter *op* em um objeto de número complexo Python. Se
   "__complex__()" não estiver definido, ele volta a chamar
   "PyFloat_AsDouble()" e retorna "0.0" em caso de sucesso.

   Em caso de falha, este método retorna "-1.0" com uma exceção
   definida, então deve-se chamar "PyErr_Occurred()" para verificar se
   há erros.

   Alterado na versão 3.13: Usa "__complex__()", se disponível.

Py_complex PyComplex_AsCComplex(PyObject *op)

   Retorna o valor "Py_complex" do número complexo *op*.

   Se *op* não é um objeto de número complexo Python, mas tem um
   método "__complex__()", este método será primeiro chamado para
   converter *op* em um objeto de número complexo Python. Se
   "__complex__()" não for definido, então ele recorre a
   "__float__()". Se "__float__()" não estiver definido, então ele
   volta para "__index__()".

   Em caso de falha, este método retorna "Py_complex" com "real"
   definido para "-1.0" e com uma exceção definida, então deve-se
   chamar "PyErr_Occurred()" para verificar se há erros.

   Alterado na versão 3.8: Usa "__index__()", se disponível.
