# 整数型对象

所有整数都实现为长度任意的长整数对象。

在出错时，大多数 `PyLong_As*` API 都会返回 `(return type)-1`，这与数字无法区分开。请采用 `PyErr_Occurred()` 来加以区分。

type PyLongObject
  属于 受限 API （作为不透明的结构体）.

  表示 Python 整数对象的 `PyObject` 子类型。

PyTypeObject PyLong_Type
  属于 稳定 ABI.

  这个 `PyTypeObject` 的实例表示 Python 的整数类型。与 Python 语言中的 `int` 相同。

int PyLong_Check( PyObject *p)

  如果参数是 `PyLongObject` 或 `PyLongObject` 的子类型，则返回 True。该函数一定能够执行成功。

int PyLong_CheckExact( PyObject *p)

  如果其参数属于 `PyLongObject`，但不是 `PyLongObject` 的子类型则返回真值。 此函数总是会成功执行。

PyObject *PyLong_FromLong(long v)
  返回值：新的引用。 属于 稳定 ABI.

  由 v 返回一个新的 `PyLongObject` 对象，失败时返回 `NULL` 。

  当前的实现维护着一个整数对象数组，包含 `-5` 和 `256` 之间的所有整数对象。 若创建一个位于该区间的 int 时，实际得到的将是对已有对象的引用。

PyObject *PyLong_FromUnsignedLong(unsigned long v)
  返回值：新的引用。 属于 稳定 ABI.

  基于 C unsigned long 返回一个新的 `PyLongObject` 对象，失败时返回 `NULL`。

PyObject *PyLong_FromSsize_t( Py_ssize_t v)
  返回值：新的引用。 属于 稳定 ABI.

  由 C `Py_ssize_t` 返回一个新的 `PyLongObject` 对象，失败时返回 `NULL` 。

PyObject *PyLong_FromSize_t(size_t v)
  返回值：新的引用。 属于 稳定 ABI.

  由 C `size_t` 返回一个新的 `PyLongObject` 对象，失败则返回 `NULL` 。

PyObject *PyLong_FromLongLong(long long v)
  返回值：新的引用。 属于 稳定 ABI.

  基于 C long long 返回一个新的 `PyLongObject`，失败时返回 `NULL`。

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)
  返回值：新的引用。 属于 稳定 ABI.

  基于 C unsigned long long 返回一个新的 `PyLongObject` 对象，失败时返回 `NULL`。

PyObject *PyLong_FromDouble(double v)
  返回值：新的引用。 属于 稳定 ABI.

  由 v 的整数部分返回一个新的 `PyLongObject` 对象，失败则返回 `NULL` 。

PyObject *PyLong_FromString(const char *str, char **pend, int base)
  返回值：新的引用。 属于 稳定 ABI.

  根据 str 字符串值返回一个新的 `PyLongObject`，它将根据 base 指定的基数来解读，或是在失败时返回 `NULL`。 如果 pend 不为 `NULL`，则在成功时 *pend 将指向 str 中末尾而在出错时将指向第一个无法处理的字符。 如果 base 为 `0`，则 str 将使用 整数字面值 定义来解读；在此情况下，非零十进制数以零开头将会引发 `ValueError`。 如果 base 不为 `0`，则必须在 `2` 和 `36`，包括这两个值。 开头和末尾的空格以及基数标示符之后和数码之间的单下划线将被忽略。 如果没有数码或 str 中数码和末尾空格之后不以 NULL 结束，则将引发 `ValueError`。

  参见

  Python 方法 `int.to_bytes()` 和 `int.from_bytes()` 用于 `PyLongObject` 到/从字节数组之间以 `256` 为基数进行转换。 你可以使用 `PyObject_CallMethod()` 从 C 调用它们。

PyObject *PyLong_FromUnicodeObject( PyObject *u, int base)
  返回值：新的引用。

  将字符串 u 中的 Unicode 数字序列转换为 Python 整数值。

  Added in version 3.3.

PyObject *PyLong_FromVoidPtr(void *p)
  返回值：新的引用。 属于 稳定 ABI.

  从指针 p 创建一个 Python 整数。可以使用 `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)
  属于 稳定 ABI.

  返回 obj 的 C long 表示形式。 如果 obj 不是 `PyLongObject` 的实例，则会先调用其 `__index__()` 方法（如果存在）将其转换为 `PyLongObject`。

  如果 obj 的值超出了 long 的取值范围则会引发 `OverflowError`。

  出错则返回 `-1` 。请用 `PyErr_Occurred()` 找出具体问题。

  在 3.8 版本发生变更: 如果可能将使用 `__index__()`。

  在 3.10 版本发生变更: 此函数将不再使用 `__int__()`。

int PyLong_AsInt( PyObject *obj)
  属于 稳定 ABI 自 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)
  属于 稳定 ABI.

  返回 obj 的 C long 表示形式。 如果 obj 不是 `PyLongObject` 的实例，则会先调用其 `__index__()` 方法（如果存在）将其转换为 `PyLongObject`。

  如果 obj 的值大于 `LONG_MAX` 或小于 `LONG_MIN`，则会把 *overflow 分别置为 `1` 或 `-1`，并返回 `-1`；否则，将 *overflow 置为 `0`。 如果发生其他异常则按常规把 *overflow 置为 `0` 并返回 `-1`。

  出错则返回 `-1` 。请用 `PyErr_Occurred()` 找出具体问题。

  在 3.8 版本发生变更: 如果可能将使用 `__index__()`。

  在 3.10 版本发生变更: 此函数将不再使用 `__int__()`。

long long PyLong_AsLongLong( PyObject *obj)
  属于 稳定 ABI.

  返回 obj 的 C long long 表示形式。 如果 obj 不是 `PyLongObject` 的实例，则会先调用其 `__index__()` 方法（如果存在）将其转换为 `PyLongObject`。

  如果 obj 值超出 long long 的取值范围则会引发 `OverflowError`。

  出错则返回 `-1` 。请用 `PyErr_Occurred()` 找出具体问题。

  在 3.8 版本发生变更: 如果可能将使用 `__index__()`。

  在 3.10 版本发生变更: 此函数将不再使用 `__int__()`。

long long PyLong_AsLongLongAndOverflow( PyObject *obj, int *overflow)
  属于 稳定 ABI.

  返回 obj 的 C long long 表示形式。 如果 obj 不是 `PyLongObject` 的实例，则会先调用其 `__index__()` 方法（如果存在）将其转换为 `PyLongObject`。

  如果 obj 的值大于 `LLONG_MAX` 或小于 `LLONG_MIN`，则会把 *overflow 分别置为 `1` 或 `-1`，并返回 `-1`；否则，将 *overflow 置为 `0`。 如果发生其他异常则按常规把 *overflow 置为 `0` 并返回 `-1`。

  出错则返回 `-1` 。请用 `PyErr_Occurred()` 找出具体问题。

  Added in version 3.2.

  在 3.8 版本发生变更: 如果可能将使用 `__index__()`。

  在 3.10 版本发生变更: 此函数将不再使用 `__int__()`。

Py_ssize_t PyLong_AsSsize_t( PyObject *pylong)
  属于 稳定 ABI.

  返回 pylong 的 C 语言 `Py_ssize_t` 形式。pylong 必须是 `PyLongObject` 的实例。

  如果 pylong 的值超出了 `Py_ssize_t` 的取值范围则会引发 `OverflowError`。

  出错则返回 `-1` 。请用 `PyErr_Occurred()` 找出具体问题。

unsigned long PyLong_AsUnsignedLong( PyObject *pylong)
  属于 稳定 ABI.

  返回 pylong 的 C unsigned long 表示形式。 pylong 必须是 `PyLongObject` 的实例。

  如果 pylong 的值超出了 unsigned long 的取值范围则会引发 `OverflowError`。

  出错时返回 `(unsigned long)-1` ，请利用 `PyErr_Occurred()` 辨别具体问题。

size_t PyLong_AsSize_t( PyObject *pylong)
  属于 稳定 ABI.

  返回 pylong 的 C 语言 `size_t` 形式。pylong 必须是 `PyLongObject` 的实例。

  如果 pylong 的值超出了 `size_t` 的取值范围则会引发 `OverflowError`。

  出错时返回 `(size_t)-1` ，请利用 `PyErr_Occurred()` 辨别具体问题。

unsigned long long PyLong_AsUnsignedLongLong( PyObject *pylong)
  属于 稳定 ABI.

  返回 pylong 的 C unsigned long long 表示形式。 pylong 必须是 `PyLongObject` 的实例。

  如果 pylong 的值超出 unsigned long long 的取值范围则会引发 `OverflowError`。

  出错时返回 `(unsigned long long)-1`，请利用 `PyErr_Occurred()` 辨别具体问题。

  在 3.1 版本发生变更: 现在 pylong 为负值会触发 `OverflowError`，而不是 `TypeError`。

unsigned long PyLong_AsUnsignedLongMask( PyObject *obj)
  属于 稳定 ABI.

  返回 obj 的 C unsigned long 表示形式。 如果 obj 不是 `PyLongObject` 的实例，则会先调用其 `__index__()` 方法（如果存在）将其转换为 `PyLongObject`。

  如果 obj 的值超出了 unsigned long 的取值范围，则返回该值对 `ULONG_MAX + 1` 求模的余数。

  出错时返回 `(unsigned long)-1`，请利用 `PyErr_Occurred()` 辨别具体问题。

  在 3.8 版本发生变更: 如果可能将使用 `__index__()`。

  在 3.10 版本发生变更: 此函数将不再使用 `__int__()`。

unsigned long long PyLong_AsUnsignedLongLongMask( PyObject *obj)
  属于 稳定 ABI.

  返回 obj 的 C unsigned long long 表示形式。 如果 obj 不是 `PyLongObject` 的实例，则会先调用其 `__index__()` 方法（如果存在）将其转换为 `PyLongObject`。

  如果 obj 的值超出了 unsigned long long 的取值范围，则返回该值对 `ULLONG_MAX + 1` 求模的余数。

  出错时返回 `(unsigned long long)-1`，请利用 `PyErr_Occurred()` 辨别具体问题。

  在 3.8 版本发生变更: 如果可能将使用 `__index__()`。

  在 3.10 版本发生变更: 此函数将不再使用 `__int__()`。

double PyLong_AsDouble( PyObject *pylong)
  属于 稳定 ABI.

  返回 pylong 的 C double 表示形式。 pylong 必须是 `PyLongObject` 的实例。

  如果 pylong 的值超出了 double 的取值范围则会引发 `OverflowError`。

  出错时返回 `-1.0` ，请利用 `PyErr_Occurred()` 辨别具体问题。

void *PyLong_AsVoidPtr( PyObject *pylong)
  属于 稳定 ABI.

  将一个 Python 整数 pylong 转换为 C void 指针。 如果 pylong 无法被转换，则将引发 `OverflowError`。 这只是为了保证将通过 `PyLong_FromVoidPtr()` 创建的值产生一个可用的 void 指针。

  出错时返回 `NULL`，请利用 `PyErr_Occurred()` 辨别具体问题。

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.

  备注

  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. If n_bytes=0, buffer may be `NULL`.

  备注

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

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

  标志位 | 值
  --- | ---

  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`

  Py_ASNATIVEBYTES_ALLOW_INDEX

  `16`

  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.

  If `Py_ASNATIVEBYTES_ALLOW_INDEX` is specified and a non-integer value is passed, its `__index__()` method will be called first. This may result in Python code executing and other threads being allowed to run, which could cause changes to other objects or values in use. When flags is `-1`, this option is not set, and non-integer values will raise `TypeError`.

  备注

  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 PyLong_GetSign( PyObject *obj, int *sign)

  Get the sign of the integer object obj.

  On success, set *sign to the integer sign (0, -1 or +1 for zero, negative or positive integer, respectively) and return 0.

  On failure, return -1 with an exception set. This function always succeeds if obj is a `PyLongObject` or its subtype.

  Added in version 3.14.

int PyUnstable_Long_IsCompact(const PyLongObject *op)
  这是 不稳定 API。它可在次发布版中不经警告地改变。

  如果 op 为紧凑形式则返回 1，否则返回 0。

  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()`.

  此项加速对于大多数用户来说是可以忽略的。

  具体有哪些值会被视为紧凑形式属于实现细节并可能发生改变。

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)
  这是 不稳定 API。它可在次发布版中不经警告地改变。

  如果 op 为紧凑形式，如 `PyUnstable_Long_IsCompact()` 所确定的，则返回它的值。

  在其他情况下，返回值是未定义的。