整数型对象
**********

所有整数都使用以任意大小的长整数对象表示。

在出错时，大多数 "PyLong_As*" API返回 "(返回类型)-1" ，无法与一般的数
字区分开来。请使用 "PyErr_Occurred()" 来区分。

PyLongObject

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

PyTypeObject PyLong_Type

   这个 "PyTypeObject" 的实例表示 Python 的整数类型。与Python层中的
   "int" 相同。

int PyLong_Check(PyObject *p)

   如果它的参数是 "PyLongObject" 或 "PyLongObject" 的子类型则返回真值
   。 此函数总是会成功执行。

int PyLong_CheckExact(PyObject *p)

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

PyObject* PyLong_FromLong(long v)
    *Return value: New reference.*

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

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

PyObject* PyLong_FromUnsignedLong(unsigned long v)
    *Return value: New reference.*

   由 C "unsigned long" 类型返回一个新的 "PyLongObject" 对象，失败时返
   回 "NULL" 。

PyObject* PyLong_FromSsize_t(Py_ssize_t v)
    *Return value: New reference.*

   从 C "Py_ssize_t" 类型返回一个新的 "PyLongObject" 对象，如果失败则
   返回 "NULL" 。

PyObject* PyLong_FromSize_t(size_t v)
    *Return value: New reference.*

   从 C "size_t" 返回一个新的 "PyLongObject" 对象，如果失败则返回
   "NULL" 。

PyObject* PyLong_FromLongLong(long long v)
    *Return value: New reference.*

   从 C "long long" 返回一个新的 "PyLongObject" 对象，失败时返回
   "NULL" 。

PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
    *Return value: New reference.*

   从 C "unsigned long long" 返回一个新的 "PyLongObject" 对象，失败时
   返回 "NULL" 。

PyObject* PyLong_FromDouble(double v)
    *Return value: New reference.*

   从 *v* 的整数部分返回一个新的 "PyLongObject" 对象，如果失败则返回
   "NULL" 。

PyObject* PyLong_FromString(const char *str, char **pend, int base)
    *Return value: New reference.*

   根据 *str* 字符串值返回一个新的 "PyLongObject" ，*base* 指定基数。
   如果 *pend* 不是 "NULL" ， */*pend* 将指向 *str* 中表示这个数字部分
   的后面的第一个字符。如果 *base* 是 "0" ， *str* 将使用 整数字面值
   定义来解释；在这种情况下，一个非零的十进制数中的前导零会引发一个
   "ValueError" 。如果 *base* 不是 "0" ，它必须在 "2" 和 "36" 之间，包
   括2和36。基数说明符后以及数字之间的前导空格、单下划线将被忽略。如果
   没有数字，将引发 "ValueError"。

PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
    *Return value: New reference.*

   将 Unicode 数字序列转换为 Python 整数值。

   Deprecated since version 3.3, will be removed in version 3.10: 旧的
   "Py_UNICODE" API的一部分;请迁移到使用 "PyLong_FromUnicodeObject()"
   。

PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)
    *Return value: New reference.*

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

   3.3 新版功能.

PyObject* PyLong_FromVoidPtr(void *p)
    *Return value: New reference.*

   从指针 *p* 创建一个 Python 整数。可以使用 "PyLong_AsVoidPtr()" 返回
   的指针值。

long PyLong_AsLong(PyObject *obj)

   返回 *obj* 的 C "long" 表达方式。 如果 *obj* 不是 "PyLongObject" 的
   实例，先调用它的 "__index__()" 或 "__int__()" 方法(如果有)将其转换
   为 "PyLongObject" 。

   如果 *obj* 的值溢出了 "long" 的范围，会引发 "OverflowError"。

   发生错误时返回 "-1" 。使用 "PyErr_Occurred()" 来消歧义。

   在 3.8 版更改: 如果可用将使用 "__index__()"。

   3.8 版后已移除: "__int__()" 已被弃用。

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

   返回 *obj* 的 C "long" 表达方式。 如果 *obj* 不是 "PyLongObject" 的
   实例，先调用它的 "__index__()" 或 "__int__()" 方法(如果有)将其转换
   为 "PyLongObject" 。

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

   发生错误时返回 "-1" 。使用 "PyErr_Occurred()" 来消歧义。

   在 3.8 版更改: 如果可用将使用 "__index__()"。

   3.8 版后已移除: "__int__()" 已被弃用。

long long PyLong_AsLongLong(PyObject *obj)

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

   如果 *obj* 值超出 "long long" ，触发 "OverflowError"

   发生错误时返回 "-1" 。使用 "PyErr_Occurred()" 来消歧义。

   在 3.8 版更改: 如果可用将使用 "__index__()"。

   3.8 版后已移除: "__int__()" 已被弃用。

long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)

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

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

   发生错误时返回 "-1" 。使用 "PyErr_Occurred()" 来消歧义。

   3.2 新版功能.

   在 3.8 版更改: 如果可用将使用 "__index__()"。

   3.8 版后已移除: "__int__()" 已被弃用。

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

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

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

   发生错误时返回 "-1" 。使用 "PyErr_Occurred()" 来消歧义。

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

   返回 *pylong* 的 C "unsigned long" 形式。 *pylong* 必须是
   "PyLongObject" 的实例。

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

   出错时返回 "(unsigned long)-1" ，请利用 "PyErr_Occurred()" 获取详细
   信息。

size_t PyLong_AsSize_t(PyObject *pylong)

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

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

   出错时返回  "(size_t)-1" ，请利用 "PyErr_Occurred()" 获取详细信息。

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)

   返回 *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)

   返回 *obj* 的 C "unsigned long" 表示形式。 如果 *obj* 不是
   "PyLongObject" 的实例，则会先调用其 "__index__()" 或 "__int__()" 方
   法（如果有的话）将其转为 "PyLongObject"。

   如果 *obj* 的值超出了 "unsigned long" 的范围，则返回该值对
   "ULONG_MAX + 1" 求模的差值。

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

   在 3.8 版更改: 如果可用将使用 "__index__()"。

   3.8 版后已移除: "__int__()" 已被弃用。

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)

   返回 *obj* 的 C "unsigned long long" 表示形式。 如果 *obj* 不是
   "PyLongObject" 的实例，则会先调用其 "__index__()" 或 "__int__()" 方
   法（如果有的话）将其转为 "PyLongObject"。

   如果 *obj* 的值超出了 "unsigned long long" 的范围，则返回该值对
   "ULLONG_MAX + 1" 求模的差值。

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

   在 3.8 版更改: 如果可用将使用 "__index__()"。

   3.8 版后已移除: "__int__()" 已被弃用。

double PyLong_AsDouble(PyObject *pylong)

   返回 *pylong* 的 C 语言 "double" 形式。*pylong* 必须是
   "PyLongObject" 的实例。

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

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

void* PyLong_AsVoidPtr(PyObject *pylong)

   将一个 Python 整数 *pylong* 转换为 C 语言的 "void" 指针。 如果
   *pylong* 无法转换，则会触发 "OverflowError"。 这只是保证为
   "PyLong_FromVoidPtr()" 创建的值产生一个合法的  "void" 指针。

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