Objetos de ponto flutuante
**************************

type PyFloatObject

   Este subtipo de "PyObject" representa um objeto de ponto flutuante
   do Python.

PyTypeObject PyFloat_Type
    * Parte da ABI Estável.*

   Esta instância do "PyTypeObject" representa o tipo de ponto
   flutuante do Python. Este é o mesmo objeto "float" na camada do
   Python.

int PyFloat_Check(PyObject *p)

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

int PyFloat_CheckExact(PyObject *p)

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

PyObject *PyFloat_FromString(PyObject *str)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Cria um objeto "PyFloatObject" baseado em uma string de valor "str"
   ou "NULL" em falha.

PyObject *PyFloat_FromDouble(double v)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Cria um objeto "PyFloatObject" de *v* ou "NULL" em falha.

double PyFloat_AsDouble(PyObject *pyfloat)
    * Parte da ABI Estável.*

   Retorna uma representação C double do conteúdo de *pyfloat*. Se
   *pyfloat* não é um objeto de ponto flutuante do Python, mas possui
   o método "__float__()", esse método será chamado primeiro para
   converter *pyfloat* em um ponto flutuante. Se "__float__()" não
   estiver definido, será usado "__index__()". Este método retorna
   "-1.0" em caso de falha, portanto, deve-se chamar
   "PyErr_Occurred()" para verificar se há erros.

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

double PyFloat_AS_DOUBLE(PyObject *pyfloat)

   Retorna uma representação C double do conteúdo de *pyfloat*, mas
   sem verificação de erro.

PyObject *PyFloat_GetInfo(void)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Retorna uma instância de structseq que contém informações sobre a
   precisão, os valores mínimo e máximo de um ponto flutuante. É um
   invólucro fino em torno do arquivo de cabeçalho "float.h".

double PyFloat_GetMax()
    * Parte da ABI Estável.*

   Retorna o ponto flutuante finito máximo representável *DBL_MAX*
   como double do C.

double PyFloat_GetMin()
    * Parte da ABI Estável.*

   Retorna o ponto flutuante positivo mínimo normalizado *DBL_MIN*
   como double do C.

Py_INFINITY

   Esta macro expande uma expressão constante do tipo double, que
   representa o infinito positivo.

   Na maioria das plataformas, isso equivale à macro "INFINITY" do
   cabeçalho "<math.h>" do padrão C11.

Py_NAN

   Esta macro expande uma expressão constante do tipo double, que
   representa um valor não um número quieto (qNaN).

   Na maioria das plataformas, isso equivale à macro "NAN" do
   cabeçalho "<math.h>" do padrão C11.

Py_HUGE_VAL

   Equivalente a "INFINITY".

   Descontinuado desde a versão 3.14: A macro está *suavemente
   descontinuada*.

Py_MATH_E

   A definição (precisa para um tipo double) da constante "math.e".

Py_MATH_El

   Definição de alta precisão (long double) da constante "e".

Py_MATH_PI

   A definição (precisa para um tipo double) da constante "math.pi".

Py_MATH_PIl

   Definição de alta precisão (long double) da constante "pi".

Py_MATH_TAU

   A definição (precisa para um tipo double) da constante "math.tau".

   Adicionado na versão 3.6.

Py_RETURN_NAN

   Retorna "math.nan" de uma função.

   Na maioria das plataformas, isso equivale a "return
   PyFloat_FromDouble(NAN)".

Py_RETURN_INF(sign)

   Retorna "math.inf" ou "-math.inf" de uma função, dependendo do
   sinal de *sign*.

   Na maioria das plataformas, isso equivale ao seguinte:

      return PyFloat_FromDouble(copysign(INFINITY, sign));

Py_IS_FINITE(X)

   Retorna "1" se o número de ponto flutuante *X* fornecido for
   finito, ou seja, for normal, subnormal ou zero, mas não infinito ou
   NaN. Caso contrário, retorna "0".

   Descontinuado desde a versão 3.14: A macro está *suavemente
   descontinuada*. Use "isfinite" em vez disso.

Py_IS_INFINITY(X)

   Retorna "1" se o número de ponto flutuante *X* fornecido for
   infinito positivo ou negativo. Caso contrário, retorna "0".

   Descontinuado desde a versão 3.14: A macro está *suavemente
   descontinuada*. Use "isinf" em vez disso.

Py_IS_NAN(X)

   Retorna "1" se o número de ponto flutuante fornecido *X* for um
   valor não numérico (NaN). Caso contrário, retorna "0".

   Descontinuado desde a versão 3.14: A macro está *suavemente
   descontinuada*. Use "isnan" em vez disso.


As funções Pack e Unpack
========================

As funções de empacotamento e desempacotamento, pack e unpack
respectivamente, fornecem uma maneira eficiente e independente de
plataforma de armazenar valores de ponto flutuante como strings de
bytes. As rotinas de Pack produzem uma string de bytes a partir de um
C double, e as rotinas de Unpack produzem um C double a partir dessa
string de bytes. O sufixo (2, 4 ou 8) especifica o número de bytes na
string de bytes.

Em plataformas que parecem usar o formato IEEE 754, essas funções
funcionam copiando bits. Em outras plataformas, o formato de 2 bytes é
idêntico ao formato de meia precisão binário 16 do IEEE 754, o formato
de 4 bytes (32 bits) é idêntico ao formato de precisão simples binário
32 do IEEE 754 e o formato de 8 bytes ao formato de precisão dupla
binário 64 do IEEE 754, embora o empacotamento de INFs e NaNs (se tais
recursos existirem na plataforma) não seja tratado corretamente, e
tentar desempacotar uma string de bytes contendo um INF ou NaN do IEEE
levantará uma exceção.

Observe que o tipo NaNs pode não ser preservado em plataformas IEEE
(NaN sinalizantes tornam-se silenciosos), por exemplo, em sistemas x86
no modo de 32 bits.

Em plataformas que não aderem IEEE com maior precisão ou maior alcance
dinâmico do que o suportado pelo IEEE 754, nem todos os valores podem
ser empacotados; em plataformas que não aderem IEEE com menor precisão
ou menor alcance dinâmico, nem todos os valores podem ser
desempacotados. O que acontece nesses casos é em parte acidental
(infelizmente).

Adicionado na versão 3.11.


Funções Pack
------------

As rotinas de empacotamento gravam 2, 4 ou 8 bytes, começando em *p*.
*le* é um argumento int, diferente de zero se você quiser a sequência
de bytes no formato little-endian (expoente por último, em "p+1",
"p+3" ou "p+6" "p+7"), zero se você quiser o formato big-endian
(expoente primeiro, em *p*). A constante "PY_BIG_ENDIAN" pode ser
usada para usar o endian nativo: é igual a "1" em processadores big-
endian ou "0" em processadores little-endian.

Valor de retorno: "0" se tudo estiver OK, "-1" se houver erro (e uma
exceção for definida, provavelmente "OverflowError").

Existem dois problemas em plataformas não IEEE:

* O que isso faz é indefinido se *x* é um NaN ou infinito.

* "-0.0" e "+0.0" produzem a mesma sequência de bytes.

int PyFloat_Pack2(double x, char *p, int le)

   Empacota um C duplo como o formato de meia precisão binário16 IEEE
   754.

int PyFloat_Pack4(double x, char *p, int le)

   Empacota um C duplo como o formato de precisão simples binário32
   IEEE 754.

int PyFloat_Pack8(double x, char *p, int le)

   Empacota um C duplo como o formato de precisão dupla binária 64
   IEEE 754.


Funções de Unpack
-----------------

As rotinas de desempacotamento leem 2, 4 ou 8 bytes, começando em *p*.
*le* é um argumento int, diferente de zero se a sequência de bytes
estiver no formato little-endian (expoente por último, em "p+1", "p+3"
ou "p+6" e "p+7"), zero se big-endian (expoente primeiro, em *p*). A
constante "PY_BIG_ENDIAN" pode ser usada para usar o endian nativo: é
igual a "1" em processadores big-endian ou "0" em processadores
little-endian.

Valor de retorno: O double descompactado. Em caso de erro, é "-1.0" e
"PyErr_Occurred()" é verdadeiro (e uma exceção é definida,
provavelmente "OverflowError").

Observe que em uma plataforma que não adere IEEE isso se recusará a
descompactar uma sequência de bytes que representa um NaN ou infinito.

double PyFloat_Unpack2(const char *p, int le)

   Descompacta o formato de meia precisão IEEE 754 binary16 como um
   double C.

double PyFloat_Unpack4(const char *p, int le)

   Descompacta o formato IEEE 754 binary32 de precisão simples como um
   C double.

double PyFloat_Unpack8(const char *p, int le)

   Descompacta o formato IEEE 754 binary64 de precisão dupla como um C
   double.
