Objetos Inteiros
****************

Todos os inteiros são implementados como objetos inteiros "longos" de
tamanho arbitrário.

Em caso de erro, a maioria das APIs "PyLong_As*" retorna "(tipo de
retorno)-1" que não pode ser distinguido de um número. Use
"PyErr_Occurred()" para desambiguar.

type PyLongObject
    * Parte da API Limitada (como uma estrutura opaca).*

   Este subtipo de "PyObject" representa um objeto inteiro Python.

PyTypeObject PyLong_Type
    * Parte da ABI Estável.*

   Esta instância de "PyTypeObject" representa o tipo inteiro Python.
   Este é o mesmo objeto que "int" na camada Python.

int PyLong_Check(PyObject *p)

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

int PyLong_CheckExact(PyObject *p)

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

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

   Retorna um novo objeto "PyLongObject" de *v* ou "NULL" em caso de
   falha.

   A implementação atual mantém um vetor de objetos inteiros para
   todos os inteiros entre "-5" e "256". Quando você cria um int nesse
   intervalo, você na verdade apenas obtém uma referência ao objeto
   existente.

PyObject *PyLong_FromUnsignedLong(unsigned long v)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Retorna um novo objeto "PyLongObject" de um unsigned long C ou
   "NULL" em caso de falha.

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

   Retorna um novo objeto "PyLongObject" de um "Py_ssize_t" C ou
   "NULL" em caso de falha.

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

   Retorna um novo objeto "PyLongObject" de um "size_t" C ou "NULL" em
   caso de falha.

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

   Retorna um novo objeto "PyLongObject" de um long long C ou "NULL"
   em caso de falha.

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Retorna um novo objeto "PyLongObject" de um unsigned long long C ou
   "NULL" em caso de falha.

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

   Retorna um novo objeto "PyLongObject" da parte inteira de *v* ou
   "NULL" em caso de falha.

PyObject *PyLong_FromString(const char *str, char **pend, int base)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Retorna um novo "PyLongObject" com base no valor da string em
   *str*, que é interpretado de acordo com a raiz em *base*. Se *pend*
   não for "NULL", **pend* apontará para o primeiro caractere em *str*
   que segue a representação do número. Se *base* for "0", *str* é
   interpretado usando a definição de Inteiros literais; neste caso,
   zeros à esquerda em um número decimal diferente de zero aumenta um
   "ValueError". Se *base* não for "0", deve estar entre "2" e "36",
   inclusive. Espaços iniciais e sublinhados simples após um
   especificador de base e entre dígitos são ignorados. Se não houver
   dígitos, "ValueError" será levantada.

   Ver também:

     Python methods "int.to_bytes()" and "int.from_bytes()" to convert
     a "PyLongObject" to/from an array of bytes in base "256". You can
     call those from C using "PyObject_CallMethod()".

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)
    *Retorna valor: Nova referência.*

   Converte uma sequência de dígitos Unicode na string *u* para um
   valor inteiro Python.

   Novo na versão 3.3.

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

   Cria um inteiro Python a partir do ponteiro *p*. O valor do
   ponteiro pode ser recuperado do valor resultante usando
   "PyLong_AsVoidPtr()".

long PyLong_AsLong(PyObject *obj)
    * Parte da ABI Estável.*

   Return a C long representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__index__()" method (if
   present) to convert it to a "PyLongObject".

   Raise "OverflowError" if the value of *obj* is out of range for a
   long.

   Retorna "-1" no caso de erro.  Use "PyErr_Occurred()" para
   desambiguar.

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

   Alterado na versão 3.10: This function will no longer use
   "__int__()".

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
    * Parte da ABI Estável.*

   Return a C long representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__index__()" method (if
   present) to convert it to a "PyLongObject".

   If the value of *obj* is greater than "LONG_MAX" or less than
   "LONG_MIN", set **overflow* to "1" or "-1", respectively, and
   return "-1"; otherwise, set **overflow* to "0".  If any other
   exception occurs set **overflow* to "0" and return "-1" as usual.

   Retorna "-1" no caso de erro.  Use "PyErr_Occurred()" para
   desambiguar.

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

   Alterado na versão 3.10: This function will no longer use
   "__int__()".

long long PyLong_AsLongLong(PyObject *obj)
    * Parte da ABI Estável.*

   Return a C long long representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__index__()" method (if
   present) to convert it to a "PyLongObject".

   Raise "OverflowError" if the value of *obj* is out of range for a
   long long.

   Retorna "-1" no caso de erro.  Use "PyErr_Occurred()" para
   desambiguar.

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

   Alterado na versão 3.10: This function will no longer use
   "__int__()".

long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
    * Parte da ABI Estável.*

   Return a C long long representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__index__()" method (if
   present) to convert it to a "PyLongObject".

   If the value of *obj* is greater than "LLONG_MAX" or less than
   "LLONG_MIN", set **overflow* to "1" or "-1", respectively, and
   return "-1"; otherwise, set **overflow* to "0".  If any other
   exception occurs set **overflow* to "0" and return "-1" as usual.

   Retorna "-1" no caso de erro.  Use "PyErr_Occurred()" para
   desambiguar.

   Novo na versão 3.2.

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

   Alterado na versão 3.10: This function will no longer use
   "__int__()".

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
    * Parte da ABI Estável.*

   Retorna uma representação de "Py_ssize_t" C de *pylong*. *pylong*
   deve ser uma instância de "PyLongObject".

   Levanta "OverflowError" se o valor de *pylong* estiver fora do
   intervalo de um "Py_ssize_t".

   Retorna "-1" no caso de erro.  Use "PyErr_Occurred()" para
   desambiguar.

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
    * Parte da ABI Estável.*

   Return a C unsigned long representation of *pylong*.  *pylong* must
   be an instance of "PyLongObject".

   Raise "OverflowError" if the value of *pylong* is out of range for
   a unsigned long.

   Retorna "(unsigned long)-1" no caso de erro.  Use
   "PyErr_Occurred()" para desambiguar.

size_t PyLong_AsSize_t(PyObject *pylong)
    * Parte da ABI Estável.*

   Retorna uma representação de "size_t" C de *pylong*. *pylong* deve
   ser uma instância de "PyLongObject".

   Levanta "OverflowError" se o valor de *pylong* estiver fora do
   intervalo de um "size_t".

   Retorna "(size)-1" no caso de erro.  Use "PyErr_Occurred()" para
   desambiguar.

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
    * Parte da ABI Estável.*

   Return a C unsigned long long representation of *pylong*.  *pylong*
   must be an instance of "PyLongObject".

   Raise "OverflowError" if the value of *pylong* is out of range for
   an unsigned long long.

   Retorna "(unsigned long long)-1" no caso de erro.  Use
   "PyErr_Occurred()" para desambiguar.

   Alterado na versão 3.1: Um *pylong* negativo agora levanta
   "OverflowError", não "TypeError".

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
    * Parte da ABI Estável.*

   Return a C unsigned long representation of *obj*.  If *obj* is not
   an instance of "PyLongObject", first call its "__index__()" method
   (if present) to convert it to a "PyLongObject".

   If the value of *obj* is out of range for an unsigned long, return
   the reduction of that value modulo "ULONG_MAX + 1".

   Retorna "(unsigned long)-1" no caso de erro.  Use
   "PyErr_Occurred()" para desambiguar.

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

   Alterado na versão 3.10: This function will no longer use
   "__int__()".

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
    * Parte da ABI Estável.*

   Return a C unsigned long long representation of *obj*.  If *obj* is
   not an instance of "PyLongObject", first call its "__index__()"
   method (if present) to convert it to a "PyLongObject".

   If the value of *obj* is out of range for an unsigned long long,
   return the reduction of that value modulo "ULLONG_MAX + 1".

   Retorna "(unsigned long long)-1" no caso de erro.  Use
   "PyErr_Occurred()" para desambiguar.

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

   Alterado na versão 3.10: This function will no longer use
   "__int__()".

double PyLong_AsDouble(PyObject *pylong)
    * Parte da ABI Estável.*

   Return a C double representation of *pylong*.  *pylong* must be an
   instance of "PyLongObject".

   Raise "OverflowError" if the value of *pylong* is out of range for
   a double.

   Retorna "-1.0" no caso de erro.  Use "PyErr_Occurred()" para
   desambiguar.

void *PyLong_AsVoidPtr(PyObject *pylong)
    * Parte da ABI Estável.*

   Convert a Python integer *pylong* to a C void pointer. If *pylong*
   cannot be converted, an "OverflowError" will be raised.  This is
   only assured to produce a usable void pointer for values created
   with "PyLong_FromVoidPtr()".

   Retorna "NULL" no caso de erro.  Use "PyErr_Occurred()" para
   desambiguar.
