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* ou "NULL"
   em caso de falha. Se *pend* não for "NULL", **pend* apontará para o
   fim do *str* em caso de sucesso ou para seu primeiro caractere que
   não pode ser processado em caso de erro. 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 em branco no início ou no final e sublinhados
   simples após um especificador de base e entre dígitos são
   ignorados. Se não houver dígitos ou *str* não for terminado em NULL
   após os dígitos e espaços em branco à direita, "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.

   Adicionado 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_AS_LONG(PyObject *obj)

      A *soft deprecated* alias. Exactly equivalent to the preferred
      "PyLong_AsLong". In particular, it can fail with "OverflowError"
      or another exception.

      Descontinuado desde a versão 3.14: The function is soft
      deprecated.

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.

   Adicionado 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.

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

   On success, return a read only *named tuple*, that holds
   information about Python's internal representation of integers. See
   "sys.int_info" for description of individual fields.

   Em caso de falha, retorna "NULL" com uma exceção definida.

   Adicionado na versão 3.1.

int PyUnstable_Long_IsCompact(const PyLongObject *op)

   *Esta é uma API Instável. Isso pode se alterado sem aviso em
   lançamentos menores.*

   Return 1 if *op* is compact, 0 otherwise.

   This function makes it possible for performance-critical code to
   implement a “fast path” for small integers. For compact values use
   "PyUnstable_Long_CompactValue()"; for others fall back to a
   "PyLong_As*" function or "calling" "int.to_bytes()".

   The speedup is expected to be negligible for most users.

   Exactly what values are considered compact is an implementation
   detail and is subject to change.

   Adicionado na versão 3.12.

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)

   *Esta é uma API Instável. Isso pode se alterado sem aviso em
   lançamentos menores.*

   If *op* is compact, as determined by "PyUnstable_Long_IsCompact()",
   return its value.

   Otherwise, the return value is undefined.

   Adicionado na versão 3.12.
