Objetos enteros
***************

Todos los enteros se implementan como objetos enteros "largos"
(*long*) de tamaño arbitrario.

En caso de error, la mayoría de las API "PyLong_As*" retornan "(tipo
de retorno) -1" que no se puede distinguir de un número. Use
"PyErr_Occurred()" para desambiguar.

type PyLongObject
    * Part of the Limited API (as an opaque struct).*

   Este subtipo de "PyObject" representa un objeto entero de Python.

PyTypeObject PyLong_Type
    * Part of the Stable ABI.*

   Esta instancia de "PyTypeObject" representa el tipo entero de
   Python. Este es el mismo objeto que "int" en la capa de Python.

int PyLong_Check(PyObject *p)

   Retorna verdadero si su argumento es un "PyLongObject" o un subtipo
   de "PyLongObject". Esta función siempre finaliza con éxito.

int PyLong_CheckExact(PyObject *p)

   Retorna verdadero si su argumento es un "PyLongObject", pero no un
   subtipo de "PyLongObject". Esta función siempre finaliza con éxito.

PyObject *PyLong_FromLong(long v)
    *Return value: New reference.** Part of the Stable ABI.*

   Retorna un objeto "PyLongObject" nuevo desde *v*, o "NULL" en caso
   de error.

   The current implementation keeps an array of integer objects for
   all integers between "-5" and "256". When you create an int in that
   range you actually just get back a reference to the existing
   object.

PyObject *PyLong_FromUnsignedLong(unsigned long v)
    *Return value: New reference.** Part of the Stable ABI.*

   Return a new "PyLongObject" object from a C unsigned long, or
   "NULL" on failure.

PyObject *PyLong_FromSsize_t(Py_ssize_t v)
    *Return value: New reference.** Part of the Stable ABI.*

   Retorna un objeto "PyLongObject" nuevo desde un C "Py_ssize_t", o
   "NULL" en caso de error.

PyObject *PyLong_FromSize_t(size_t v)
    *Return value: New reference.** Part of the Stable ABI.*

   Retorna un objeto "PyLongObject" nuevo desde un C "size_t", o
   "NULL" en caso de error.

PyObject *PyLong_FromLongLong(long long v)
    *Return value: New reference.** Part of the Stable ABI.*

   Return a new "PyLongObject" object from a C long long, or "NULL" on
   failure.

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)
    *Return value: New reference.** Part of the Stable ABI.*

   Return a new "PyLongObject" object from a C unsigned long long, or
   "NULL" on failure.

PyObject *PyLong_FromDouble(double v)
    *Return value: New reference.** Part of the Stable ABI.*

   Retorna un nuevo objeto "PyLongObject" de la parte entera de *v*, o
   "NULL" en caso de error.

PyObject *PyLong_FromString(const char *str, char **pend, int base)
    *Return value: New reference.** Part of the Stable ABI.*

   Return a new "PyLongObject" based on the string value in *str*,
   which is interpreted according to the radix in *base*, or "NULL" on
   failure.  If *pend* is non-"NULL", **pend* will point to the end of
   *str* on success or to the first character that could not be
   processed on error.  If *base* is "0", *str* is interpreted using
   the Literales enteros definition; in this case, leading zeros in a
   non-zero decimal number raises a "ValueError".  If *base* is not
   "0", it must be between "2" and "36", inclusive.  Leading and
   trailing whitespace and single underscores after a base specifier
   and between digits are ignored.  If there are no digits or *str* is
   not NULL-terminated following the digits and trailing whitespace,
   "ValueError" will be raised.

   Ver también:

     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)
    *Return value: New reference.*

   Convierte una secuencia de dígitos Unicode en la cadena de
   caracteres *u* en un valor entero de Python.

   Added in version 3.3.

PyObject *PyLong_FromVoidPtr(void *p)
    *Return value: New reference.** Part of the Stable ABI.*

   Crea un entero de Python desde el puntero *p*. El valor del puntero
   se puede recuperar del valor resultante usando
   "PyLong_AsVoidPtr()".

PyObject *PyLong_FromNativeBytes(const void *buffer, size_t n_bytes, int flags)

   Create a Python integer from the value contained in the first
   *n_bytes* of *buffer*, interpreted as a two's-complement signed
   number.

   *flags* are as for "PyLong_AsNativeBytes()". Passing "-1" will
   select the native endian that CPython was compiled with and assume
   that the most-significant bit is a sign bit. Passing
   "Py_ASNATIVEBYTES_UNSIGNED_BUFFER" will produce the same result as
   calling "PyLong_FromUnsignedNativeBytes()". Other flags are
   ignored.

   Added in version 3.13.

PyObject *PyLong_FromUnsignedNativeBytes(const void *buffer, size_t n_bytes, int flags)

   Create a Python integer from the value contained in the first
   *n_bytes* of *buffer*, interpreted as an unsigned number.

   *flags* are as for "PyLong_AsNativeBytes()". Passing "-1" will
   select the native endian that CPython was compiled with and assume
   that the most-significant bit is not a sign bit. Flags other than
   endian are ignored.

   Added in version 3.13.

long PyLong_AsLong(PyObject *obj)
    * Part of the Stable ABI.*

   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" en caso de error. Use "PyErr_Occurred()" para
   desambiguar.

   Distinto en la versión 3.8: Use "__index__()" if available.

   Distinto en la versión 3.10: This function will no longer use
   "__int__()".

int PyLong_AsInt(PyObject *obj)
    * Part of the Stable ABI since version 3.13.*

   Similar to "PyLong_AsLong()", but store the result in a C int
   instead of a C long.

   Added in version 3.13.

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
    * Part of the Stable ABI.*

   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" en caso de error. Use "PyErr_Occurred()" para
   desambiguar.

   Distinto en la versión 3.8: Use "__index__()" if available.

   Distinto en la versión 3.10: This function will no longer use
   "__int__()".

long long PyLong_AsLongLong(PyObject *obj)
    * Part of the Stable ABI.*

   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" en caso de error. Use "PyErr_Occurred()" para
   desambiguar.

   Distinto en la versión 3.8: Use "__index__()" if available.

   Distinto en la versión 3.10: This function will no longer use
   "__int__()".

long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
    * Part of the Stable ABI.*

   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" en caso de error. Use "PyErr_Occurred()" para
   desambiguar.

   Added in version 3.2.

   Distinto en la versión 3.8: Use "__index__()" if available.

   Distinto en la versión 3.10: This function will no longer use
   "__int__()".

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
    * Part of the Stable ABI.*

   Retorna una representación de C "Py_ssize_t" de *pylong*. *pylong*
   debe ser una instancia de "PyLongObject".

   Lanza "OverflowError" si el valor de *pylong* está fuera de rango
   para un "Py_ssize_t".

   Retorna "-1" en caso de error. Use "PyErr_Occurred()" para
   desambiguar.

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
    * Part of the Stable ABI.*

   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" en caso de error. Use
   "PyErr_Occurred()" para desambiguar.

size_t PyLong_AsSize_t(PyObject *pylong)
    * Part of the Stable ABI.*

   Retorna una representación de C "size_t" de *pylong*. *pylong* debe
   ser una instancia de "PyLongObject".

   Lanza "OverflowError" si el valor de *pylong* está fuera de rango
   para un "size_t".

   Retorna "(size_t) -1" en caso de error. Use "PyErr_Occurred()" para
   desambiguar.

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
    * Part of the Stable ABI.*

   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" en caso de error. Use
   "PyErr_Occurred()" para desambiguar.

   Distinto en la versión 3.1: Ahora un *pylong* negativo lanza un
   "OverflowError", no "TypeError".

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
    * Part of the Stable ABI.*

   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" en caso de error. Use
   "PyErr_Occurred()" para desambiguar.

   Distinto en la versión 3.8: Use "__index__()" if available.

   Distinto en la versión 3.10: This function will no longer use
   "__int__()".

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
    * Part of the Stable ABI.*

   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" por error. Use "PyErr_Occurred()"
   para desambiguar.

   Distinto en la versión 3.8: Use "__index__()" if available.

   Distinto en la versión 3.10: This function will no longer use
   "__int__()".

double PyLong_AsDouble(PyObject *pylong)
    * Part of the Stable ABI.*

   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" en caso de error. Use "PyErr_Occurred()" para
   desambiguar.

void *PyLong_AsVoidPtr(PyObject *pylong)
    * Part of the Stable ABI.*

   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" en caso de error. Use "PyErr_Occurred()" para
   desambiguar.

Py_ssize_t PyLong_AsNativeBytes(PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)

   Copy the Python integer value *pylong* to a native *buffer* of size
   *n_bytes*. The *flags* can be set to "-1" to behave similarly to a
   C cast, or to values documented below to control the behavior.

   Returns "-1" with an exception raised on error.  This may happen if
   *pylong* cannot be interpreted as an integer, or if *pylong* was
   negative and the "Py_ASNATIVEBYTES_REJECT_NEGATIVE" flag was set.

   Otherwise, returns the number of bytes required to store the value.
   If this is equal to or less than *n_bytes*, the entire value was
   copied. All *n_bytes* of the buffer are written: large buffers are
   padded with zeroes.

   If the returned value is greater than than *n_bytes*, the value was
   truncated: as many of the lowest bits of the value as could fit are
   written, and the higher bits are ignored. This matches the typical
   behavior of a C-style downcast.

   Nota:

     Overflow is not considered an error. If the returned value is
     larger than *n_bytes*, most significant bits were discarded.

   "0" will never be returned.

   Values are always copied as two's-complement.

   Usage example:

      int32_t value;
      Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);
      if (bytes < 0) {
          // Failed. A Python exception was set with the reason.
          return NULL;
      }
      else if (bytes <= (Py_ssize_t)sizeof(value)) {
          // Success!
      }
      else {
          // Overflow occurred, but 'value' contains the truncated
          // lowest bits of pylong.
      }

   Passing zero to *n_bytes* will return the size of a buffer that
   would be large enough to hold the value. This may be larger than
   technically necessary, but not unreasonably so.

   Nota:

     Passing *n_bytes=0* to this function is not an accurate way to
     determine the bit length of a value.

   If *n_bytes=0*, *buffer* may be "NULL".

   To get at the entire Python value of an unknown size, the function
   can be called twice: first to determine the buffer size, then to
   fill it:

      // Ask how much space we need.
      Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);
      if (expected < 0) {
          // Failed. A Python exception was set with the reason.
          return NULL;
      }
      assert(expected != 0);  // Impossible per the API definition.
      uint8_t *bignum = malloc(expected);
      if (!bignum) {
          PyErr_SetString(PyExc_MemoryError, "bignum malloc failed.");
          return NULL;
      }
      // Safely get the entire value.
      Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);
      if (bytes < 0) {  // Exception has been set.
          free(bignum);
          return NULL;
      }
      else if (bytes > expected) {  // This should not be possible.
          PyErr_SetString(PyExc_RuntimeError,
              "Unexpected bignum truncation after a size check.");
          free(bignum);
          return NULL;
      }
      // The expected success given the above pre-check.
      // ... use bignum ...
      free(bignum);

   *flags* is either "-1" ("Py_ASNATIVEBYTES_DEFAULTS") to select
   defaults that behave most like a C cast, or a combintation of the
   other flags in the table below. Note that "-1" cannot be combined
   with other flags.

   Currently, "-1" corresponds to "Py_ASNATIVEBYTES_NATIVE_ENDIAN |
   Py_ASNATIVEBYTES_UNSIGNED_BUFFER".

   +-----------------------------------------------+--------+
   | Flag                                          | Value  |
   |===============================================|========|
   | Py_ASNATIVEBYTES_DEFAULTS                     | "-1"   |
   +-----------------------------------------------+--------+
   | Py_ASNATIVEBYTES_BIG_ENDIAN                   | "0"    |
   +-----------------------------------------------+--------+
   | Py_ASNATIVEBYTES_LITTLE_ENDIAN                | "1"    |
   +-----------------------------------------------+--------+
   | Py_ASNATIVEBYTES_NATIVE_ENDIAN                | "3"    |
   +-----------------------------------------------+--------+
   | Py_ASNATIVEBYTES_UNSIGNED_BUFFER              | "4"    |
   +-----------------------------------------------+--------+
   | Py_ASNATIVEBYTES_REJECT_NEGATIVE              | "8"    |
   +-----------------------------------------------+--------+

   Specifying "Py_ASNATIVEBYTES_NATIVE_ENDIAN" will override any other
   endian flags. Passing "2" is reserved.

   By default, sufficient buffer will be requested to include a sign
   bit. For example, when converting 128 with *n_bytes=1*, the
   function will return 2 (or more) in order to store a zero sign bit.

   If "Py_ASNATIVEBYTES_UNSIGNED_BUFFER" is specified, a zero sign bit
   will be omitted from size calculations. This allows, for example,
   128 to fit in a single-byte buffer. If the destination buffer is
   later treated as signed, a positive input value may become
   negative. Note that the flag does not affect handling of negative
   values: for those, space for a sign bit is always requested.

   Specifying "Py_ASNATIVEBYTES_REJECT_NEGATIVE" causes an exception
   to be set if *pylong* is negative. Without this flag, negative
   values will be copied provided there is enough space for at least
   one sign bit, regardless of whether
   "Py_ASNATIVEBYTES_UNSIGNED_BUFFER" was specified.

   Nota:

     With the default *flags* ("-1", or *UNSIGNED_BUFFER*  without
     *REJECT_NEGATIVE*), multiple Python integers can map to a single
     value without overflow. For example, both "255" and "-1" fit a
     single-byte buffer and set all its bits. This matches typical C
     cast behavior.

   Added in version 3.13.

int PyUnstable_Long_IsCompact(const PyLongObject *op)

   *This is Unstable API. It may change without warning in minor
   releases.*

   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 "PyLong_AsNativeBytes()".

   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.

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)

   *This is Unstable API. It may change without warning in minor
   releases.*

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

   Otherwise, the return value is undefined.
